bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-create-skill/references/sub/fetch-docs.md

@@ -1,17 +1,41 @@
 ---
 nextStepFile: '../enrich.md'
-# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
+forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
+# Resolve `{forgeTierRwHelper}` by probing `{forgeTierRwProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves.
-atomicWriteProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
-  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# path wins. §5b changes the registry only through it. If neither resolves,
+# §5b skips the registry change with a warning: a docs fetch 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 `{deriveAssemblyShapeHelper}` the same way — used in §1 to decide
 # whether this is a whole-language reference (registry-corpora prose retained
 # as a Language Guide) or a standard skill (unchanged behaviour).
 deriveAssemblyShapeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-derive-assembly-shape.py'
   - '{project-root}/src/shared/scripts/skf-derive-assembly-shape.py'
+# If neither path exists, §3 looks for no subpages.
+detectDocsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
+# §5 merges the T3 items into the extraction inventory and counts it through
+# it; step 3 §5 already halted when neither path exists.
+extractionInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extraction-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-extraction-inventory.py'
+# §4a writes the Language Guide's index beside the inventory through it; if
+# neither path exists, step 5 has no guide and says so.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# HARD HALT helpers (Rules).
+sourceTreeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
+  - '{project-root}/src/shared/scripts/skf-source-tree.py'
+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}. -->
@@ -26,9 +50,10 @@ Fetch remote documentation from brief-specified URLs using whatever web fetching
 
 - No tier gate — runs at any tier when `doc_urls` are present in the brief
 - Tool-agnostic — use whatever web fetching capability is available
-- Do not halt the workflow if web fetching is unavailable or fails
+- Do not halt the workflow if web fetching is unavailable or fails, with one exception: a `docs-only` brief left with nothing to compile halts at §5's zero-content check, before anything is staged. The user may still stop the run at §5's zero-export gate ([R])
 - Do not override existing T1, T1-low, or T2 extraction data with T3 content
-- Never delete the staging directory of a `docs-only` skill — the fetched pages are its only source corpus
+- Never delete the staging directory of a `docs-only` skill, whose only source corpus is the fetched pages, or of a whole-language reference, whose Language Guide step 5 reads from them
+- 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
 
@@ -62,67 +87,64 @@ Content fetched from external URLs is classified as **T3** (external, untrusted)
 **Discover available web fetching capability.** Try tools in any order — use whatever is accessible in the current environment (e.g., Firecrawl scrape, WebFetch, web-reader, MCP fetch, curl, browser tools). If no web fetching capability can be found:
 
 - Log warning: "No web fetching capability available in this environment. Skipping documentation fetch."
-- Skip to section 7 (auto-proceed).
+- Continue at §5's **Zero-content check**: nothing was fetched.
 
-**For each URL in `doc_urls`:**
+Bind `{docs_staging}` ← `{project-root}/_bmad-output/{skill-name}-docs`, the folder that holds every page this step fetches. Just before the first page this run fetched is saved, create the folder or empty it (`mkdir -p "{docs_staging}" && rm -f "{docs_staging}"/*.md`), so a corpus kept from an earlier docs-only run (§5c) is replaced by this run's pages, never mixed with them, and stays as it was when every fetch fails.
+
+**For each URL in `doc_urls`** (the `{n}`th entry, counting from 1):
 
 - Fetch the content at `{url}` as clean markdown using the discovered web tool.
-- **If fetch succeeds:** Store the markdown content with the URL as provenance source.
+- **If fetch succeeds:** Store the markdown content with the URL as provenance source, and save it as `{docs_staging}/page-{n}.md`.
 - **If fetch fails:** Log warning: "Failed to fetch {url}: {reason}. Skipping." Continue with remaining URLs.
 
 **Subpage discovery (root URL detection):**
 
-After fetching a URL, apply the following heuristic to detect documentation root pages that contain no useful API content. This is common with modern documentation sites (Mintlify, Docusaurus, ReadTheDocs, GitBook) that render API content on subpages.
-
-**Root page detection — apply only when the URL path ends in `/`, `/index`, `/index.html`, has no path component (bare domain), or has 1 path segment (e.g., `/docs`). For deeper URL paths (2+ segments like `/api/reference`), skip this heuristic and keep the content as-is.**
+A documentation root page often holds no API content of its own: Mintlify, Docusaurus, ReadTheDocs and GitBook sites render it on subpages. Resolve `{detectDocsHelper}` from `{detectDocsProbeOrder}` (first existing path wins) and measure each saved page, from `{project-root}`:
 
-Subpage discovery is triggered if **either** of the following independent triggers fires:
-
-**Trigger 1 — Content-based (both conditions must be true):**
-
-1. **Zero API content indicators:** The fetched markdown contains none of: fenced code blocks (`` ``` ``), parameter tables (`|---|`), or function signature patterns (`def `, `function `, `fn `, `func `, `export `).
-2. **High link density:** More than 70% of non-empty lines are markdown links (matching `[text](url)` with no other substantive content on the line).
-
-**Trigger 2 — URL-based (independent of content analysis):**
-
-The URL matches the path criteria above (ends in `/`, bare domain, or 1 segment) AND the fetched content is under **2000 words**. Short content on root-like URLs almost certainly indicates a navigation hub or landing page, even if it contains introductory code examples that would prevent Trigger 1 from firing. This handles modern doc sites (Mintlify, Docusaurus, GitBook) that include hero sections with code snippets on their root pages.
+```bash
+uv run {detectDocsHelper} page-metrics --url "{url}" "{docs_staging}/page-{n}.md"
+```
 
-If neither trigger fires, keep the page content as-is and do not trigger subpage discovery.
+It prints `discover_subpages`, true when the page is a documentation root with little API content of its own (`uv run {detectDocsHelper} page-metrics --help` gives the test and the counts it prints with it). When it is false, the command exits non-zero, or no candidate resolves, keep the page as it is and look for no subpages.
 
-**If a root URL with minimal content is detected:**
+**If `discover_subpages` is true:**
 
 1. **Attempt sitemap/map discovery:** Use whatever discovery tool is available:
    - Firecrawl: `firecrawl_map({url})` to discover all subpages
-   - Manual: try fetching `{url}/sitemap.xml` and parsing URLs from it
+   - Manual: fetch `{url}/sitemap.xml`
    - Crawl: if a crawl tool is available, use it with depth=1 on the root URL
    - If no discovery tool is available, keep the root page content as-is and continue
 
-2. **Filter discovered URLs by relevance and origin:** Restrict candidates to the same **registrable domain** as the root URL — strip the URL down to its eTLD+1 (e.g., for root `https://docs.example.com/intro`, accept any subdomain of `example.com` such as `api.example.com` or `docs.example.com`, but reject `example.org` or `cdn.partner.io`). Cross-origin links must be discarded before any fetch. The same-registrable-domain rule prevents Mintlify/Docusaurus link clouds from pulling in tracking pixels, doc-site CDNs, or third-party embeds as if they were canonical docs. From the surviving same-domain candidates, select the most relevant pages by searching for API-related terms in the URL path or title (e.g., `api`, `reference`, `quickstart`, `setup`, `config`, `getting-started`, `guide`, `sdk`, `methods`, `functions`). Exclude pages that are clearly non-API content (e.g., `blog`, `changelog`, `pricing`, `about`, `careers`).
+2. **Keep the subpages of the root's own site:** pass what discovery found to the helper on stdin, from `{project-root}`: pipe the sitemap in as below, or feed the map or crawl result (its JSON, or one URL per line) to the same command through a heredoc:
+
+   ```bash
+   curl -fsSL --max-time 30 "{url}/sitemap.xml" | uv run {detectDocsHelper} filter-urls --root "{url}" -
+   ```
+
+   It lists in `kept[]` the URLs on the root page's own site that may hold API content, each with the API words its path or title holds (`terms`), and in `sitemaps[]` the sitemaps a sitemap index names: filter each of them the same way (`uv run {detectDocsHelper} filter-urls --help` gives the rules). When it exits non-zero, leave that input out. Never fetch a URL the helper did not keep. From `kept[]`, choose the subpages most relevant to the skill's API: `terms` points at them.
 
 3. **Fetch top subpages (in parallel):** Fetch up to **10** of the most relevant subpages **concurrently** — subpage fetches are independent and network-bound, so wall-clock benefits substantially from parallel execution. Bound concurrency to **4 in flight** at a time to stay polite to documentation hosts (Mintlify/Docusaurus typically allow more, but conservatism here protects against unrecognized rate limits).
 
    The parallel pattern depends on the fetch tool:
 
    - **LLM-driven tools** (Firecrawl `firecrawl_scrape`, `WebFetch`, MCP fetch, browser tools): issue up to 4 tool calls **in a single message**. The agent runtime executes parallel tool calls concurrently; collect results from the batch before issuing the next set of up to 4. Repeat until all up-to-10 subpages have been attempted or rate limiting halts the batch.
-   - **Bash-driven tools** (`curl`, `wget`): use `xargs -P 4 -n 1` to fan out from a newline-separated subpage list. Example:
+   - **Bash-driven tools** (`curl`, `wget`): use `xargs -P 4` to fan out from a newline-separated subpage list, numbering the subpages as it goes. Example, for the `{n}`th `doc_urls` entry:
 
      ```bash
-     printf '%s\n' "${subpages[@]}" | xargs -P 4 -n 1 -I {} bash -c '
-       url="{}"
-       safe=$(echo -n "$url" | sha256sum | cut -c1-12)
-       curl -sSL --max-time 30 "$url" > "{staging}/subpage-$safe.md" \
-         || echo "fetch failed: $url" > "{staging}/subpage-$safe.md"
+     printf '%s\n' "${subpages[@]}" | awk '{ print NR, $0 }' | xargs -P 4 -L 1 sh -c '
+       f="{docs_staging}/subpage-{n}-$0.md"
+       curl -fsSL --max-time 30 "$1" -o "$f" || { rm -f "$f"; echo "fetch failed: $1" >&2; }
      '
      ```
 
    For each subpage (regardless of tool):
-   - Use the same web fetching tool as the root URL
+   - Use the same web fetching tool as the root URL, and save the page in `{docs_staging}` as `subpage-{n}-{k}.md`, `{k}` counting this root's subpages from 1, only when its fetch succeeded: a failed fetch leaves no file, as in the snippet
    - Store with the subpage URL as provenance: `[EXT:{subpage-url}]`
    - If a subpage fetch fails, skip it and continue with the rest of the batch — do not halt the whole stage
 
 4. **Rate limiting:** If rate limiting (HTTP 429) is encountered during subpage fetching, stop discovery for this root URL. Keep results collected so far. Log: "Subpage discovery stopped due to rate limiting." For the parallel-tool-call pattern, drop any not-yet-issued tool calls from subsequent batches; for the `xargs` pattern, interrupt the pipeline (set `--max-procs 0` is **not** a graceful stop — the simplest stop is to kill the xargs PID and let in-flight writers complete naturally).
 
-**If ALL URLs fail (including any subpage fetches):** Log warning: "No documentation could be fetched. Proceeding without T3 content." Skip to section 7 (auto-proceed).
+**If ALL URLs fail (including any subpage fetches):** Log warning: "No documentation could be fetched." `{docs_staging}` holds no page of this run: continue at §5's **Zero-content check**, which halts a `docs-only` brief and lets a source brief go on without T3 content.
 
 ### 4. Extract API Information from Fetched Content
 
@@ -137,60 +159,85 @@ Parse the successfully fetched markdown for:
 
 **No hallucination:** If information cannot be found in the fetched content, exclude it. Do not infer or fabricate API details.
 
-**Whole-language references — retain prose, do not shred (`whole_language_reference: true`):** For a whole-language reference the registry-sourced corpora (the guide/Book, the standard/library docs) ARE the product, not the compiler's internal exports. Reducing that prose to per-export signature items and then discarding it under the §5 "T3 never overrides T1" rule (the compiler's AST already owns names like `Vec`, `Option`, `HashMap`) would gut exactly the content the skill exists to teach. So for these briefs, skip §4a below for the registry corpora.
+**Whole-language references (`whole_language_reference: true`): retain the prose, do not shred it.** For a whole-language reference the registry-sourced corpora (the guide/Book, the standard/library docs) ARE the product, not the compiler's internal exports. So for these briefs, extract no per-export items from the registry corpora (`source: language-registry`): §4a below keeps their pages as the Language Guide.
 
 ### 4a. Retain the Language Guide (whole-language references only)
 
 **Skip this section entirely unless `whole_language_reference: true`.** When it is true, for each `doc_urls` entry whose `source` is `language-registry`:
 
-- Do not reduce its fetched markdown to per-export items. Instead retain the cleaned prose as a Language-Guide entry `{url, label, prose}`, where `prose` is the substantive body (narrative, idioms, usage examples, conceptual reference) lightly trimmed of navigation/boilerplate, each block cited `[EXT:{url}]`.
-- Collect these into a `language_guide[]` context artifact, in `doc_urls` order.
+- Do not reduce its fetched markdown to per-export items. Its pages stay in `{docs_staging}` as §3 saved them (`page-{n}.md` and its `subpage-{n}-{k}.md` files), and §5c keeps the folder: step 5 reads the prose from them and retains it as the skill's Language Guide, each block cited `[EXT:{url}]`.
+- List the entry in a `language_guide[]` index, in `doc_urls` order, as `{url, label, pages}`: `pages` names the files of `{docs_staging}` that hold its fetched pages, and is empty when the fetch failed (warn: step 5 surfaces the gap rather than emitting a thin guide silently).
+
+Write the index beside the extraction inventory, so step 5 finds the pages after a context compaction. Bind `{language_guide_json}` ← `{project-root}/_bmad-output/.skf-stage/{skill-name}.language-guide.json`, resolve `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` and, from `{project-root}`, run:
 
-This artifact is a **distinct** carrier — it is not merged into the extraction inventory and is not subject to the §5 conflict rule, so the canonical prose survives intact into step 5 (compile), which foregrounds it as the skill's Language Guide. Non-registry docs (README-detected, homepage, Pages, docs-folder) still flow through §4's normal per-export extraction and the §5 merge unchanged.
+```bash
+uv run {atomicWriteHelper} write --target "{language_guide_json}" <<'SKF_LANGUAGE_GUIDE'
+{"docs_folder": "{docs_staging}", "language_guide": [{"url": "...", "label": "...", "pages": ["page-1.md"]}]}
+SKF_LANGUAGE_GUIDE
+```
 
-**If a registry corpus could not be fetched** (network failure), record it in `language_guide[]` as `{url, label, prose: null}` and warn — step 5 surfaces the gap rather than emitting a thin guide silently.
+When it fails, or no path resolves, warn "The Language Guide was not saved: {its message}": step 5 then assembles without it. The guide is a **distinct** carrier: it is not merged into the extraction inventory and is not subject to the §5 conflict rule, so the canonical prose survives intact into step 5 (compile), which foregrounds it as the skill's Language Guide. Non-registry docs (README-detected, homepage, Pages, docs-folder) still flow through §4's normal per-export extraction and the §5 merge unchanged.
 
 ### 5. Build Doc-Fetch Inventory
 
 **Mode determines merge behavior:**
 
-- **`source_type: "docs-only"`** — The doc-fetch inventory IS the extraction inventory. It replaces the empty inventory from step 3, since there was no source code to extract from.
-- **`source_type: "source"` (supplemental mode)** — Merge T3 items into the existing extraction inventory from step 3.
+- **`source_type: "docs-only"`**: the doc-fetch inventory IS the extraction inventory. Its T3 items fill the empty inventory step 3 wrote, since there was no source code to extract from.
+- **`source_type: "source"` (supplemental mode)**: the T3 items join the exports step 3 extracted.
+
+Either way, merge them into `{extraction_inventory}`, the file step 3 §5 wrote, one object per item with its `[EXT:{url}]` citation and, when the item documents an export, its `export_name`. Resolve `{extractionInventoryHelper}` ← first existing path in `{extractionInventoryProbeOrder}` and, from `{project-root}`, run:
+
+```bash
+uv run {extractionInventoryHelper} add --inventory "{extraction_inventory}" --field t3_items <<'SKF_T3'
+[{"export_name": "...", "kind": "signature|type|config|example", "content": "...", "citation": "[EXT:{url}]"}]
+SKF_T3
+```
 
-**Conflict rule:** T3 items never override existing T1, T1-low, or T2 items for the same export. When an export already has a higher-confidence entry, the T3 item is discarded — T3 has the lowest priority.
+**Conflict rule:** T3 items never override existing T1, T1-low, or T2 items for the same export. The helper applies it: an item whose `export_name` names an export the inventory already holds is left out and listed in `dropped`. When it exits non-zero, fix the JSON and run it once more.
 
-**Language-Guide carve-out:** the `language_guide[]` artifact from §4a (whole-language references) is not part of the export inventory and is therefore not subject to this conflict rule — it carries no export key, so it cannot collide with a T1 compiler export and can never be pruned. It is passed separately into step 5, which renders it as the foregrounded Language Guide section. Only the per-export T3 items participate in the T1/T2/T3 merge.
+**Language-Guide carve-out:** the `language_guide[]` from §4a (whole-language references) is not part of the export inventory and is therefore not subject to this conflict rule: it carries no export key, so it cannot collide with a T1 compiler export and can never be pruned. Step 5 reads it through `{language_guide_json}` and renders it as the foregrounded Language Guide section. Only the per-export T3 items participate in the T1/T2/T3 merge.
 
-**Edge case — T1-zero supplemental mode:** If T1 extraction produced zero results and `doc_urls` are present in supplemental mode, T3 items should be used as the primary inventory since no T1 data exists to conflict with.
+**Edge case: T1-zero supplemental mode.** If T1 extraction produced zero results and `doc_urls` are present in supplemental mode, compile uses the T3 items as the primary inventory, since no T1 data exists to conflict with.
 
 **Aggregate totals for reporting:**
 - URLs fetched successfully vs. total
 - URLs that failed
 - T3 items extracted
 
+**Zero-content check.** Run `uv run {extractionInventoryHelper} summary --inventory "{extraction_inventory}"` from `{project-root}` and read its `counts`:
+
+- **`source_type: "docs-only"`, no URL or subpage fetched in this run, and `counts.items` is 0:** there is nothing to compile, and a docs-only skill has no other source. Stage and promote nothing: **HARD HALT** (exit code 3, `docs-unreachable`, phase `fetch-docs`; 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"`): "**No documentation could be fetched for `{skill-name}`, so there is nothing to compile.** Failed: {each `doc_urls` URL with its reason}. Check the network and that this environment has a web fetch tool, or fix `doc_urls` in the brief, then re-run create-skill."
+- **`source_type: "source"`, `counts.exports` is 0 (or equals `counts.not_public`) and every `doc_urls` fetch failed:** step 3 §6's zero-export check let this brief through because it declares `doc_urls`. Apply that check here: show its warning and offer **[C] Continue anyway** or **[R] Refine the brief**: stop here. **GATE [default: C]**: under `{headless_mode}`, log and record its `zero-exports` decision as step 3 §6 says, and continue. On [R], **HARD HALT** (exit code 6, `halted-for-brief-refinement`, phase `fetch-docs`; 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:** no public export was extracted (or, for a `public-api` brief, every export found is off the public surface: the `Off the public surface` warning names them) and no `doc_urls` page could be fetched. Fix `scope.include`, `target_version` or `doc_urls` in the brief (or re-run `skf-brief-skill`), then re-run `skf-create-skill`."
+- **Otherwise:** continue. When no page of this run was saved (every fetch failed, or no fetch tool), skip §5b and §5c, which have nothing to index or remove, and go on to §6: `{docs_staging}` stays as it was.
+
 ### 5b. Index into QMD (Deep Tier Only)
 
 **If tier is not Deep:** Skip this section silently.
 
 **If tier is Deep and at least one URL was fetched successfully:**
 
-1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/` — clear any previous contents first, so a corpus retained from an earlier docs-only run (step 5 below) does not mix with this run's pages.
-2. Index into QMD with atomic replace + rollback: if a `{skill-name}-docs` collection already exists, run `qmd collection remove {skill-name}-docs` first, then `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`. **If `qmd collection add` fails after a successful `remove`:** remove any matching `{skill-name}-docs` entry from `forge-tier.yaml` → `qmd_collections[]` to keep the registry consistent with QMD's actual state, warn in evidence-report, and skip the embed — docs enrichment degrades gracefully.
-3. Generate embeddings scoped to this collection (only if step 2 `add` succeeded): `qmd embed --collection {skill-name}-docs` (required for semantic `type:'vec'` and HyDE `type:'hyde'` sub-queries within the QMD `query` tool). If the installed `qmd` CLI does not accept `--collection`, gate the embed behind a freshness check: skip re-embedding if the existing `{skill-name}-docs` registry entry is within 24 hours, and log the skip in the evidence report to prevent unbounded batch-mode re-embedding.
-4. Register in forge-tier.yaml `qmd_collections` array — **acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` for the read-modify-write** (see the locking pattern documented in step 3b §4). Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`. If `flock` is unavailable, fall back to read-CAS-by-mtime (capture `st_mtime` before, re-check after; refuse to clobber if a concurrent run wrote in between).
-
-```yaml
-- name: "{skill-name}-docs"
-  type: "docs"
-  source_workflow: "create-skill"
-  skill_name: "{skill-name}"
-  created_at: "{current ISO date}"
-```
+1. The fetched pages are already in `{docs_staging}` (section 3), which this section indexes.
+2. Index into QMD with atomic replace + rollback: if a `{skill-name}-docs` collection already exists, run `qmd collection remove {skill-name}-docs` first, then `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`. Resolve `{forgeTierRwHelper}` from `{forgeTierRwProbeOrder}`: every registry change of this section goes through it, and it holds `{sidecar_path}/forge-tier.yaml.lock` for its one read-modify-write, so no step takes a lock of its own. **If `qmd collection add` fails after a successful `remove`:** remove the registry entry too, so the registry matches QMD's actual state, warn in evidence-report, and skip steps 3 and 4, since docs enrichment degrades gracefully:
+
+   ```bash
+   uv run {forgeTierRwHelper} remove-qmd-collection --target "{forgeTierConfig}" --name {skill-name}-docs
+   ```
 
-5. Clean up the staging directory after indexing — **only when `source_type` is `"source"`**: `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`. Note that this directory is the source path of the `{skill-name}-docs` collection registered in step 4; removing it is accepted for supplemental docs, whose T3 items already live in the extraction inventory. **When `source_type` is `"docs-only"`, keep the directory.** The fetched pages are the skill's only source corpus — there is no code tree — so deleting them would leave the just-registered collection with nothing to refresh from and nothing to verify citations against. Record the retained path in the evidence report.
+3. Generate embeddings scoped to this collection (only if step 2 `add` succeeded): `qmd embed --collection {skill-name}-docs` (required for semantic `type:'vec'` and HyDE `type:'hyde'` sub-queries within the QMD `query` tool). If the installed `qmd` CLI does not accept `--collection`, gate the embed behind a freshness check: read the registry with `uv run {forgeTierRwHelper} read --target "{forgeTierConfig}"`, skip re-embedding when the `{skill-name}-docs` entry in its `data.qmd_collections` was created within the last 24 hours, and log the skip in the evidence report to prevent unbounded batch-mode re-embedding.
+4. Register the collection in the `qmd_collections` array (only if step 2 `add` succeeded). The helper replaces the entry with the same `name` or appends it:
+
+   ```bash
+   uv run {forgeTierRwHelper} register-qmd-collection --target "{forgeTierConfig}" <<'SKF_REGISTRY_ENTRY'
+   {"name": "{skill-name}-docs", "type": "docs", "source_workflow": "create-skill", "skill_name": "{skill-name}", "created_at": "{current ISO date}"}
+   SKF_REGISTRY_ENTRY
+   ```
 
 **If QMD indexing fails:** Warn: "QMD indexing of fetched docs failed. T3 items are still in the extraction inventory — enrichment will proceed without QMD-indexed docs." Continue.
 
+### 5c. Keep or Remove the Fetched Pages
+
+Once the pages are extracted, and at Deep tier indexed by §5b, remove `{docs_staging}` **only when `source_type` is `"source"` and the brief is not a whole-language reference** (`whole_language_reference` false): `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`. A whole-language reference keeps the folder, since its Language Guide index (§4a) points step 5 at the pages in it. At Deep tier the folder is the source path of the `{skill-name}-docs` collection §5b registered; removing it is accepted for supplemental docs, whose T3 items already live in the extraction inventory. **When `source_type` is `"docs-only"`, keep the folder at every tier:** the fetched pages are the skill's only source corpus, since there is no code tree, so deleting them would leave nothing to verify citations against and, at Deep tier, the just-registered collection with nothing to refresh from. Record the kept path in the evidence report.
+
 ### 6. Report
 
 Display:
@@ -200,7 +247,7 @@ Display:
 **T3 items extracted:** {count}
 **Confidence:** All doc-fetched items are T3 — `[EXT:{url}]` citations applied.
 {If docs-only mode: '**Mode:** Docs-only — all skill content is T3. source_authority: community'}
-{If docs-only mode AND tier is Deep: '**Docs corpus retained:** `_bmad-output/{skill-name}-docs/`{if the `{skill-name}-docs` collection was registered in §5b: ' — source path of QMD collection `{skill-name}-docs`'}'}
+{If docs-only mode or a whole-language reference: '**Docs corpus kept:** `{docs_staging}`{if the `{skill-name}-docs` collection was registered in §5b: ', the source path of QMD collection `{skill-name}-docs`'}'}
 
 Proceeding to enrichment..."
 

package/src/skf-create-skill/references/sub/fetch-temporal.md

@@ -1,11 +1,19 @@
 ---
 nextStepFile: 'fetch-docs.md'
-# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
+forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
+# Resolve `{forgeTierRwHelper}` by probing `{forgeTierRwProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves.
-atomicWriteProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
-  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# path wins. §2 reads the registry through it and §4 changes the registry only
+# through it. If neither resolves, §2 finds no cached entry and §4 skips the
+# registry change with a warning: temporal enrichment 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'
+# If neither path exists, §1 skips the step: temporal enrichment never
+# halts the workflow.
+fetchTemporalProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-fetch-temporal.py'
+  - '{project-root}/src/shared/scripts/skf-fetch-temporal.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -14,47 +22,44 @@ atomicWriteProbeOrder:
 
 ## STEP GOAL:
 
-To fetch temporal context (issues, PRs, changelogs, release notes) from the source repository and index it into a QMD collection for Deep tier enrichment. This ensures step 4 has historical data to search when annotating extracted functions with T2 provenance.
+To fetch temporal context (issues, PRs, changelogs, release notes) from the source repository, keep the fetched files as the skill's temporal feeder, and index them into a QMD collection for Deep tier enrichment. This ensures step 4 has historical data to search when annotating extracted functions with T2 provenance, and that step 5c's doc-rot scan can read the same files.
 
 ## Rules
 
 - Deep tier only — Quick, Forge, and Forge+ tiers skip this step entirely and silently
 - GitHub repositories only — other source types degrade gracefully
 - Do not halt the workflow if fetching or indexing fails
-- Do not modify extraction data from step 3 — this step only creates QMD collections
+- Do not modify the extraction inventory step 3 wrote: this step only reads its `top_exports`, and writes the temporal feeder folder, the fetch folder that replaces it, and the QMD collection indexed from it
 
 ## MANDATORY SEQUENCE
 
 ### 1. Check Eligibility
 
-Evaluate the following conditions sequentially. **If ANY condition fails, skip silently to section 5 (auto-proceed) with no output:**
+Set `{temporal_feeder}` to null first, so that in a `--batch` run one brief's feeder never carries into the next. Then evaluate the following conditions sequentially. **If ANY condition fails, leave `{temporal_feeder}` null and skip silently to section 5 (auto-proceed) with no output:**
 
 1. **Tier is Deep:** If tier is Quick, Forge, or Forge+, skip silently.
-2. **Source is GitHub:** Verify `source_repo` is a GitHub URL (`https://github.com/...`) or `owner/repo` format. If the source is a local path, a non-GitHub URL, or any other format, attempt GitHub remote detection (section 1b) before skipping.
-3. **`gh` CLI is available:** Run `timeout 10s gh auth status` to verify the CLI is installed and authenticated (the short timeout protects against a misconfigured network or hung auth helper blocking the workflow). If it fails or times out, skip silently.
+2. **The source is a GitHub repository `gh` can read:** resolve `{fetchTemporalHelper}` from `{fetchTemporalProbeOrder}` and, from `{project-root}`, run:
 
-All three conditions must pass to proceed to section 2.
+   ```bash
+   uv run {fetchTemporalHelper} repo --source-repo "{source_repo}"
+   ```
 
-### 1b. GitHub Remote Detection for Local Sources
+   Skip silently when the command exits non-zero, when its `skip_reason` is not null, and when no candidate resolves. Otherwise bind `{temporal_repo}` ← its `repo`, and when its `via` is `origin`, log: "**Local source with GitHub remote detected:** {temporal_repo}. Fetching temporal context."
 
-**Only runs when condition 2 above fails because `source_repo` is a local path.**
+Both conditions must pass to proceed to section 2. Then bind `{temporal_feeder}` ← `{forge_data_folder}/{skill-name}/.skf-temporal`: the folder where this step keeps what it fetched (sections 3 and 4). Step 5c's doc-rot scan reads the files in it, and a null `{temporal_feeder}` tells step 5c that no temporal feeder was expected.
 
-Local repositories that are clones of GitHub repos contain temporal context (issues, PRs, releases) accessible via `gh`. Detect this automatically:
+### 2. Check Cache (Skip If Fresh)
 
-1. Check if the local path is a git repository: `git -C "{source_repo}" rev-parse --is-inside-work-tree`
-2. If not a git repo: skip silently to section 5 (current behavior).
-3. Extract the origin remote: `git -C "{source_repo}" remote get-url origin`
-4. If the remote URL contains `github.com`:
-   - Extract `owner/repo` from the remote URL (strip `.git` suffix, handle both HTTPS and SSH formats)
-   - Log: "**Local source with GitHub remote detected:** {owner}/{repo} — fetching temporal context."
-   - Use the extracted `owner/repo` for all `gh` API calls in sections 3-4. Continue to condition 3 (gh CLI check).
-5. If no remote, or remote is not GitHub: skip silently to section 5 (current behavior).
+Resolve `{forgeTierRwHelper}` from `{forgeTierRwProbeOrder}` and read the registry as JSON, from `{project-root}`:
 
-### 2. Check Cache (Skip If Fresh)
+```bash
+uv run {forgeTierRwHelper} read --target "{forgeTierConfig}"
+```
 
-Read `forge-tier.yaml` from the sidecar path.
+Bind `{registry_collections}` ← its `data.qmd_collections`: an empty list when `exists` is false, the list is missing, the command fails or no candidate resolves. Section 4 reads it again for its embed check.
 
-- Look for a `qmd_collections` entry where `skill_name` matches the current brief AND `type` is `"temporal"`.
+- Look for a `{registry_collections}` entry where `skill_name` matches the current brief AND `type` is `"temporal"`.
+- If `{temporal_feeder}` holds no `.md` file, continue to section 3 even when that entry is fresh: a cache hit must leave step 5c files to read, and an earlier SKF release deleted the folder once it was indexed.
 - If found AND `created_at` is within the last **7 days** (rationale: temporal context — issues, PRs, changelogs — rarely changes meaningfully on shorter horizons; a 7-day window balances freshness against re-fetch cost and GitHub rate limits): the temporal collection is fresh. Display:
 
 "**Temporal context: cached.** Collection `{skill-name}-temporal` is fresh ({days} days old). Skipping re-fetch."
@@ -65,175 +70,57 @@ Skip to section 5 (auto-proceed).
 
 ### 3. Fetch Temporal Context
 
-Create a staging directory: `_bmad-output/{skill-name}-temporal/`
-
-Resolve the `owner` and `repo` from `source_repo` (e.g., `acme/toolkit` from `https://github.com/acme/toolkit`).
-
-Execute the four fetches below **in parallel** — they are independent and the network round-trips dominate wall-clock. Background each, then `wait` for the batch. **If any individual fetch fails, log a warning and continue with the others.** The 4-concurrent fan-out is well under GitHub's authenticated REST rate limit (5000/hr); no bounded-concurrency guard is needed for this set.
+Fetch through the helper, from `{project-root}`. `--exports` names the extraction inventory step 3 §5 wrote, `{extraction_inventory}`: the helper reads its `top_exports` for the targeted issue searches, and an empty list (docs-only mode, or a source extraction with no public exports) runs none:
 
 ```bash
-mkdir -p {staging}
-# 1. Issues (last 100)
-( gh issue list -R {owner}/{repo} --state all --limit 100 \
-    --json number,title,state,labels,createdAt,closedAt,body \
-    | jq -r '...' > {staging}/issues.md ) &
-# 2. Merged PRs (last 100)
-( gh pr list -R {owner}/{repo} --state merged --limit 100 \
-    --json number,title,mergedAt,labels,body \
-    | jq -r '...' > {staging}/prs.md ) &
-# 3. Release tags only (the per-tag fetch loop runs sequentially below to
-#    preserve append-immediately crash-resume semantics for releases.md)
-( gh release list -R {owner}/{repo} --limit 10 \
-    --json tagName,name,publishedAt > {staging}/.release-tags.json ) &
-# 4. Changelog (404 is silent skip — note `set +e` so the subshell doesn't
-#    propagate `gh api`'s non-zero exit on missing file)
-( set +e
-  gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.content' \
-    | base64 -d > {staging}/changelog.md 2>/dev/null
-  [ -s {staging}/changelog.md ] || rm -f {staging}/changelog.md ) &
-wait
+uv run {fetchTemporalHelper} fetch --repo "{temporal_repo}" --feeder "{temporal_feeder}" --exports "{extraction_inventory}"
 ```
 
-Per-call rationale:
-
-1. **Issues (last 100):** 100 is `gh issue list`'s default max-per-page; one paginated call captures recent activity without extra round trips or rate-limit pressure. Output → `{staging}/issues.md` formatted as a markdown document with one section per issue.
-
-2. **Merged PRs (last 100):** Same 100-per-page convention as issues — captures the most recent merges in one API call. Output → `{staging}/prs.md`.
-
-3. **Release tags + per-release fetches (last 10):** Release notes accumulate slowly relative to issues/PRs; the most recent 10 tags cover roughly the last 6-18 months of changelog-relevant history for typical OSS projects, which is enough context for T2-past annotations without fanning out to dozens of `gh release view` calls.
-
-   **Note:** `gh release list --json` does **not** support the `body` field. The parallel block above fetches tags only (Step 1). After `wait`, run **Step 2 sequentially** to preserve the append-immediately crash-resume contract:
-
-   If `{staging}/.release-tags.json` is empty (no releases), skip Step 2 and omit the releases section entirely. Otherwise:
-
-   ```bash
-   # Sequential per-tag loop. Iterate the JSON tag array verbatim so a
-   # crash mid-loop leaves a partial-but-well-formed releases.md on disk.
-   echo "# Releases (partial if interrupted)" > {staging}/releases.md
-   ERR_FILE="{staging}/.gh-release-err"  # per-run stderr capture inside staging
-   jq -r '.[].tagName' {staging}/.release-tags.json | while IFS= read -r tag; do
-     if gh release view "$tag" -R {owner}/{repo} \
-          --json tagName,name,publishedAt,body 2>"$ERR_FILE"; then
-       jq -r '...' >> {staging}/releases.md  # one ## {tag} block per release
-     else
-       echo "## $tag — fetch failed: $(cat "$ERR_FILE")" \
-         >> {staging}/releases.md
-     fi
-   done
-   rm -f "$ERR_FILE"
-   ```
-
-   Failed individual fetches get a one-line placeholder; the loop continues with remaining tags. If a rate limit (HTTP 429) is hit, stop the release loop, keep the partial `releases.md` file in place (do not delete it), and log: "Release fetch stopped at tag {N}/{total} due to rate limiting — partial releases.md retained."
-
-   **Why sequential here when the rest is parallel:** the append-per-release pattern guarantees that a mid-loop abort (rate limit, network drop, user interrupt) leaves a partial but well-formed `releases.md` with every release fetched so far. Parallel writers appending to the same file would need file locking and per-writer ordering — the simpler sequential loop is robust for free, and 10 release fetches contribute only ~5-10s of the total wall-clock.
-
-4. **Changelog:** `CHANGELOG.md` or `RELEASES.md` at the repository root. The parallel block above writes to `{staging}/changelog.md` only when the file exists; non-existence (404 from `gh api`) leaves no file behind.
+It fetches into a fresh folder beside `{temporal_feeder}` and replaces the feeder with it only when the fetch returned something (`uv run {fetchTemporalHelper} --help` describes the files it writes and the swap).
 
-#### 3b. Targeted Function Searches (Uses Extraction Inventory)
+Show each of its `warnings`. Then:
 
-After the generic fetches above, perform **targeted searches** using the top-level public API function names from `extraction_inventory.top_exports[]`. This produces high-signal results that generic list fetches miss.
-
-**Short-circuit on empty `top_exports`:** If `extraction_inventory.top_exports` is missing or `== []` (docs-only mode, or a source extraction that produced zero public exports), skip this sub-section entirely with a one-line log: "No exports in inventory — skipping targeted function searches." The generic fetches from §3 remain in place and continue to provide baseline temporal context.
-
-**Limit:** Search the top **10 function names** maximum to control API call volume and avoid `gh` rate limiting. (rationale: 10 targeted searches + generic fetches from §3 stays well under GitHub's unauthenticated search rate limit of 10 requests/minute and authenticated 30/minute; matches the `top_exports[]` size emitted by step 3 §5 so every tracked export gets one search.)
-
-For each function name in `top_exports[]` (up to 10), **sanitize first**: strip every character that is not in `[A-Za-z0-9_]` from `function_name` to produce `safe_name`. This prevents shell injection and `gh` query parser errors when an export name contains punctuation (e.g., `<T>`, `.method`, `::namespace`, quotes). If `safe_name` is empty after sanitization (the original was entirely punctuation — rare but possible for symbol exports), fall back to piping the original name through stdin via `--query-from-file -`-style indirection if your `gh` version supports it; otherwise skip that one entry with a log line — never substitute the unsanitized name back into the shell command.
-
-**Parallel fan-out (bounded concurrency = 5):** sanitized searches are independent and benefit from parallelism. Use `xargs -P 5` so at most 5 `gh search` calls are in flight at once — this stays well under GitHub's authenticated search rate limit (30/min) while saving ~5-8s of wall-clock on a top-10 export list compared to fully sequential.
-
-```bash
-# 1. Sanitize and write one safe_name per line; skip empties.
-#    Python is the canonical sanitizer because awk/sed regex semantics
-#    vary across platforms.
-jq -r '.top_exports[]' {extraction_inventory.json} \
-  | python3 -c 'import sys,re
-for line in sys.stdin:
-  s = re.sub(r"[^A-Za-z0-9_]", "", line.strip())
-  if s: print(s)' > {staging}/.safe-names.txt
-
-# 2. Fan out to gh search, 5 in flight. Each writer emits a self-contained
-#    section to its own per-name file; we concatenate after the wait.
-# --limit 5: top-5 issues per function keeps signal-to-noise high and caps
-#    total response size across 10 fan-outs at 50 issues.
-mkdir -p {staging}/targeted
-cat {staging}/.safe-names.txt | xargs -P 5 -I {} bash -c '
-  gh search issues --repo {owner}/{repo} "{}" --limit 5 \
-      --json number,title,state,body 2>/dev/null \
-    | jq -r ". | \"## {}\\n\" + (...)" > {staging}/targeted/{}.md \
-  || echo "## {} — fetch failed" > {staging}/targeted/{}.md
-'
-
-# 3. Concatenate in stable order (alpha by safe_name) into the single
-#    aggregated file the rest of the workflow expects.
-sort {staging}/.safe-names.txt | while IFS= read -r name; do
-  cat "{staging}/targeted/$name.md"
-done > {staging}/targeted-issues.md
-```
-
-Aggregate all targeted search results into a single file: `{staging}/targeted-issues.md`. The per-name temp directory `{staging}/targeted/` can be removed after concat — it exists only to give each parallel writer an isolated output stream.
-
-**If `gh search` is unavailable** (older `gh` CLI versions): skip targeted searches silently. The generic fetches from section 3 still provide baseline temporal context.
-
-**If rate limiting occurs** (HTTP 429 or similar): stop targeted searches immediately, keep results collected so far. Log: "Targeted search stopped at function {N}/{total} due to rate limiting."
-
-**After all fetching,** verify at least one file was written to the staging directory. If the staging directory is empty (all fetches failed), log a warning and skip to section 5.
+- **Exit 0** (`status: "replaced"`): `{temporal_feeder}` now holds this fetch, and `files` lists it. Continue to section 4.
+- **Exit 3** (`status: "kept"`: no fetch returned anything): log a warning and skip to section 5. `{temporal_feeder}` stays bound and keeps what the last good fetch left in it: step 5c scans those files, or reports the missing feeder in the evidence report when there are none.
+- **Exit 1 or 2:** as for exit 3, with the helper's error (its stderr) in the warning.
 
 ### 4. Index Into QMD & Register
 
-**Index the staging directory:**
+**Index `{temporal_feeder}`:**
 
-If a `{skill-name}-temporal` collection already exists, remove and recreate for atomic replace. **Wrap the remove + add pair with rollback on `add` failure** — a `remove` that succeeds followed by an `add` that fails must not leave the registry claiming a collection that no longer exists in QMD:
+If a `{skill-name}-temporal` collection already exists, remove and recreate for atomic replace. **Wrap the remove + add pair with rollback on `add` failure:** a `remove` that succeeds followed by an `add` that fails must not leave the registry claiming a collection that no longer exists in QMD. The registry changes below go through `{forgeTierRwHelper}` (resolved in section 2), which holds `{sidecar_path}/forge-tier.yaml.lock` for its one read-modify-write, so no step takes a lock of its own:
 
 ```bash
 qmd collection remove {skill-name}-temporal
-if ! qmd collection add {project-root}/_bmad-output/{skill-name}-temporal/ --name {skill-name}-temporal --mask "*.md"; then
-  # add failed after remove succeeded — the collection is gone from QMD. Clean the registry too.
-  # Remove any {skill-name}-temporal entry from forge-tier.yaml qmd_collections[].
-  # Warn the user, do not fail the workflow (temporal enrichment degrades gracefully).
-  echo "WARN: qmd add failed after remove — registry entry for {skill-name}-temporal removed to keep forge-tier.yaml consistent with QMD state."
-  # [skip the embed step]
+if ! qmd collection add "{temporal_feeder}" --name {skill-name}-temporal --mask "*.md"; then
+  # add failed after remove succeeded: the collection is gone from QMD, so its registry entry goes too.
+  uv run {forgeTierRwHelper} remove-qmd-collection --target "{forgeTierConfig}" --name {skill-name}-temporal
+  echo "WARN: qmd add failed after remove; registry entry for {skill-name}-temporal removed to keep forge-tier.yaml consistent with QMD state."
 else
   qmd embed --collection {skill-name}-temporal
 fi
 ```
 
-**Rollback rule:** if the `qmd collection add` step fails (non-zero exit, network error, parse error) after the prior `remove` succeeded, remove the canonical registry entry in `forge-tier.yaml` to match QMD's actual state. A dangling registry entry that points at a non-existent QMD collection poisons subsequent cache-hit checks in §2. Emit a warning in evidence-report and skip the embed — enrichment degrades to no-QMD for this run.
+**Rollback rule:** if the `qmd collection add` step fails (non-zero exit, network error, parse error) after the prior `remove` succeeded, the `remove-qmd-collection` call above removes the registry entry, to match QMD's actual state. A dangling registry entry that points at a non-existent QMD collection poisons subsequent cache-hit checks in §2. Emit a warning in evidence-report and skip the embed and the registration below: enrichment degrades to no-QMD for this run.
 
-**Scope the embed:** Always pass `--collection {skill-name}-temporal` to `qmd embed`. An unscoped `qmd embed` re-embeds every collection in the QMD store, which can take minutes per run in batch mode and generates wasteful GPU/API cost. If the installed `qmd` CLI does not accept `--collection` (older upstream versions), gate the embed behind a per-skill check: if a previous `{skill-name}-temporal` entry already exists in `qmd_collections` and its `created_at` is within 24 hours, skip the embed entirely and warn "qmd embed skipped — upstream qmd lacks --collection scope; re-embedding all collections would be wasteful in batch mode". Log the skip in the evidence report.
+**Scope the embed:** Always pass `--collection {skill-name}-temporal` to `qmd embed`. An unscoped `qmd embed` re-embeds every collection in the QMD store, which can take minutes per run in batch mode and generates wasteful GPU/API cost. If the installed `qmd` CLI does not accept `--collection` (older upstream versions), gate the embed behind a per-skill check: if the `{skill-name}-temporal` entry section 2 found in `{registry_collections}` has a `created_at` within 24 hours, skip the embed entirely and warn "qmd embed skipped: upstream qmd lacks --collection scope; re-embedding all collections would be wasteful in batch mode". Log the skip in the evidence report.
 
 **Note:** `qmd embed` generates vector embeddings required for semantic (`type:'vec'`) and HyDE (`type:'hyde'`) sub-queries inside the QMD `query` tool. Without embeddings, only BM25 (`type:'lex'`) keyword search works. Run `qmd embed` after every `qmd collection add`.
 
-**Update the registry** in `forge-tier.yaml` under a file lock to prevent concurrent batch runs from clobbering each other's entries:
-
-1. Acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` (create the lock file if absent). Use `flock -x {lockfile} -c "..."` or an equivalent `fcntl.flock(LOCK_EX)` guard.
-2. Read the current `forge-tier.yaml`, capturing its `st_mtime` as `mtime_before`.
-3. Perform the read-modify-write below.
-4. Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`.
-5. Release the flock.
-
-**Fallback when `flock` is unavailable:** re-stat the file after the write; if the on-disk `st_mtime` is newer than `mtime_before` by more than this run's own write timestamp, halt with "forge-tier.yaml modified mid-update by another process — refusing to clobber. Re-run after the other run completes." This read-CAS-by-mtime is the belt-and-braces safety net for environments without `flock`.
-
-If an entry with `name: "{skill-name}-temporal"` already exists in `qmd_collections`, replace it. Otherwise, append:
-
-```yaml
-  - name: "{skill-name}-temporal"
-    type: "temporal"
-    source_workflow: "create-skill"
-    skill_name: "{skill-name}"
-    created_at: "{current ISO date}"
-```
-
-**Clean up** the staging directory after successful indexing:
+**Register the collection** only when `qmd collection add` succeeded. The helper replaces the entry with `name: "{skill-name}-temporal"` or appends it, and its lock keeps concurrent batch runs from losing each other's entries:
 
 ```bash
-rm -rf {project-root}/_bmad-output/{skill-name}-temporal/
+uv run {forgeTierRwHelper} register-qmd-collection --target "{forgeTierConfig}" <<'SKF_REGISTRY_ENTRY'
+{"name": "{skill-name}-temporal", "type": "temporal", "source_workflow": "create-skill", "skill_name": "{skill-name}", "created_at": "{current ISO date}"}
+SKF_REGISTRY_ENTRY
 ```
 
+**Keep `{temporal_feeder}`.** It is the source path of the `{skill-name}-temporal` collection and the temporal feeder step 5c's doc-rot scan reads, on this run and on every cache hit until a later fetch replaces it (section 3), so this step never deletes it. Its `.skf-` name, like the fetch folder's, marks it as SKF output to SKF's ownership checks, so it stays with the skill's forge folder: a purge of the whole skill deletes it and a rename moves it.
+
 **Error handling:**
 
-- If QMD indexing fails: log the error, note that temporal enrichment will be unavailable. Do not fail the workflow.
-- If registry update fails: log the error, continue. The collection may exist in QMD even if the registry entry failed.
-- If cleanup fails: log a warning and continue.
+- If QMD indexing fails: log the error, note that temporal enrichment will be unavailable. Do not fail the workflow. The files stay in `{temporal_feeder}` for step 5c.
+- If a registry command fails, or `{forgeTierRwHelper}` does not resolve: log the error, continue. The collection may exist in QMD even if the registry entry failed.
 
 Display brief confirmation: