bmad-module-skill-forge 0.10.0 → 1.0.0-rc.3

package/src/skf-test-skill/steps-c/step-06-report.md

@@ -0,0 +1,290 @@
+---
+nextStepFile: './step-07-health-check.md'
+
+outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
+scoringRulesFile: 'references/scoring-rules.md'
+outputFormatsFile: 'assets/output-section-formats.md'
+# outputContractSchema and healthCheck resolve relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative to
+# this step file. Both paths are probed in order; HALT if neither exists.
+outputContractSchema: 'shared/references/output-contract-schema.md'
+healthCheckProbeOrder:
+  - '{project-root}/_bmad/skf/shared/health-check.md'
+  - '{project-root}/src/shared/health-check.md'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+---
+
+# Step 6: Gap Report
+
+## STEP GOAL:
+
+Generate a detailed gap report listing every issue found during coverage and coherence analysis, assign severity to each gap, provide specific actionable remediation suggestions, and finalize the test report document. This is the final step — no next step file.
+
+## Rules
+
+- Focus on gap enumeration, severity classification, and remediation — do not recalculate scores
+- Remediation suggestions reference specific files, exports, and line numbers
+- Gaps are ordered by severity (Critical > High > Medium > Low > Info)
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Collect All Issues
+
+Read `{outputFile}` and extract every issue found across all analysis sections:
+
+**From Coverage Analysis (step 03):**
+- Missing documentation (exports in source but not in SKILL.md)
+- Signature mismatches (documented signature differs from source)
+- Stale documentation (documented but no longer in source)
+- Type coverage gaps (undocumented types/interfaces)
+
+**From Coherence Analysis (step 04):**
+- Broken references (file paths, skill references, type imports that don't resolve)
+- Incomplete integration patterns (contextual mode)
+- Structural issues (naive mode — missing sections, broken examples)
+
+**From External Validation (step 04b):**
+- skill-check diagnostics (unresolved errors and warnings)
+- tessl judge suggestions (content quality and actionability improvements)
+
+### 2. Load Severity Rules
+
+Load `{scoringRulesFile}` for gap severity classification:
+
+| Severity | Criteria |
+|----------|----------|
+| **Critical** | Missing exported function/class documentation |
+| **High** | Signature mismatch between source and SKILL.md |
+| **Medium** | Missing type or interface documentation |
+| **Medium** | Migration section present/absent mismatch with T2-future annotation data (Deep tier) |
+| **Medium** | Script/asset directory exists but no Scripts & Assets section in SKILL.md |
+| **Medium** | Scripts & Assets section references file not found in scripts/ or assets/ directory |
+| **Low** | Script/asset file present without provenance entry in provenance-map.json file_entries |
+| **Low** | Missing optional metadata or examples |
+| **Low** | Description trigger optimization recommended (third-person voice, negative triggers, or keyword coverage gaps) |
+| **Info** | Style suggestions, non-blocking observations |
+| **Info** | Discovery testing not performed — realistic prompt testing recommended before export |
+
+### 3. Classify and Order Gaps
+
+Load `{outputFormatsFile}` for gap entry format and remediation quality rules.
+
+For each issue, assign severity from `{scoringRulesFile}` and generate a specific remediation following the quality rules in `{outputFormatsFile}`. Order gaps by severity: Critical → High → Medium → Low → Info.
+
+### 4. Generate Remediation Summary and Append Gap Report
+
+Load the Gap Report section format from `{outputFormatsFile}`. Count gaps by severity, estimate effort per the guidelines in `{outputFormatsFile}`, and append the complete **Gap Report** section to `{outputFile}`.
+
+If no gaps found, append a clean pass message recommending **export-skill** workflow.
+
+### 4b. Discovery Testing (MANDATORY — H4)
+
+After gap enumeration, perform minimum-viable discovery testing. This is a **Medium-weight** check contributing to the Discovery Quality subsection — no longer advisory boilerplate.
+
+**4b.0 Precondition — catalog size check:**
+
+Count the skills in `{skillsOutputFolder}`: `ls -1d {skillsOutputFolder}/*/ 2>/dev/null | wc -l` (directories only — each skill package lives at `{skillsOutputFolder}/<skill-name>/`).
+
+- If `catalog_size < 2`: **skip §4b.1–§4b.3**. Record an Info-severity note in the Discovery Quality subsection: `discovery — skipped: catalog size N={catalog_size}, requires ≥2 candidates for meaningful routing`. The routing test is vacuous with one candidate (any prompt returns the sole skill); reporting `3/3 PASS` under those conditions inflates the Discovery score and masks genuinely bad description triggers. Proceed to §4b.4 (description optimization) if tessl/skill-check flagged description issues; otherwise skip to §4c.
+- If `catalog_size >= 2`: continue with §4b.1 as written.
+
+Optional escape hatch: the workflow accepts `--discovery-catalog=all` to broaden the candidate pool to `.claude/skills/` or `_bmad/agents/` for single-skill repos where the repo-local catalog is trivially too small. When the flag is set, rebuild `catalog_size` from the broader pool before the precondition check.
+
+**4b.1 Extract realistic prompts from the skill under test:**
+
+Parse SKILL.md for the three most "organic" prompts found in its `description`, `Triggers`, or example sections. Prefer prompts that:
+- Use conversational phrasing (contractions, casual language, implicit context)
+- Omit the skill name or explicit command invocation
+- Reflect how a user would actually ask for this capability
+
+If SKILL.md does not contain enough organic examples, synthesize 3 from the skill's exports/capability summary using the patterns from §4b.4 below.
+
+**4b.2 Spawn a discovery subagent:**
+
+For each of the 3 prompts, spawn an isolated subagent with NO prior context about which skill is under test. Provide only:
+1. A compact list of ALL skills available in `{skillsOutputFolder}` (name + description line from each skill's SKILL.md frontmatter)
+2. The prompt text
+
+Instruction to the subagent:
+
+> "You are an agent selecting the best skill to handle a user request. Here is the catalog: {catalog}. The user says: '{prompt}'. Return JSON: `{\"selected_skill\": \"<name>\", \"confidence\": \"<high|medium|low>\", \"reasoning\": \"<one sentence>\"}`. If no skill fits, return `{\"selected_skill\": null, ...}`. Return ONLY JSON."
+
+**4b.3 Evaluate discovery results:**
+
+Parse the 3 responses. Schema-validate (required: `selected_skill`, `confidence`, `reasoning`). On any parse/schema failure, record the prompt as `discovery_result: error` and continue.
+
+For each prompt, PASS = `selected_skill == skill_name` (the skill under test), FAIL otherwise.
+
+- **3 of 3 PASS** → discovery check PASS (Info severity note, no gap)
+- **2 of 3 PASS** → discovery check WARN → **Medium**-severity gap: `discovery — 1/3 realistic prompts misrouted`
+- **≤1 of 3 PASS** → discovery check FAIL → **High**-severity gap: `discovery — {N}/3 realistic prompts misrouted; description triggers are not pulling the skill`
+
+Append the prompts, selected skills, and outcomes as a table in the Discovery Quality subsection.
+
+**4b.4 Description optimization (secondary):** If tessl `description_score` (from step 04b) is below 90%, or skill-check flagged description issues, add remediation hints to the Discovery Quality subsection:
+- Third-person voice check
+- Explicit trigger keywords matching real user phrasing
+- Negative triggers ("NOT for: ...") to prevent false positives
+- Alternative skill references for excluded use cases
+
+Realistic prompt patterns for synthesis (§4b.1 fallback):
+- Vague: "can you help me with this {artifact} my boss sent"
+- Implicit: "why did {metric} drop last {period}"
+- Abbreviated: "run the {keyword} thing on this data"
+
+### 4c. Result Contract (atomic write — B4)
+
+**Resolve `{atomicWriteHelper}`:** probe `{atomicWriteProbeOrder}`. HALT if neither candidate exists — the contract is a downstream-consumer protocol and must never be written non-atomically.
+
+Write the result contract per `{outputContractSchema}`:
+- Per-run record: `{forge_version}/skf-test-skill-result-{run_id}.json` (the `{run_id}` set in step-01 §6a — already carries UTC timestamp + PID + random suffix, so no same-second collision).
+- Latest copy: `{forge_version}/skf-test-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink).
+
+Both writes MUST go through the atomic writer so partial writes are never observable:
+
+```bash
+# Build the JSON payload in memory, then:
+cat payload.json | python3 {atomicWriteHelper} write --target {forge_version}/skf-test-skill-result-{run_id}.json
+cat payload.json | python3 {atomicWriteHelper} write --target {forge_version}/skf-test-skill-result-latest.json
+```
+
+Payload contents:
+- `outputs[]` — include the test report path at `{outputFile}` with its `{run_id}` suffix
+- `summary` — `score`, `threshold`, `result` (`"PASS"`, `"PASS_WITH_DRIFT"`, `"FAIL"`, or **`"INCONCLUSIVE"`**), `testMode` (naive/contextual), `activeCategories[]`, `inconclusiveReasons[]` (when present). `PASS_WITH_DRIFT` is set when the workflow observed workspace drift and the user passed `--allow-workspace-drift` — see step-05 §5 (M5). Downstream consumers MUST treat `PASS_WITH_DRIFT` as a non-exportable result: re-run against the pinned commit before export.
+- `runId` — the workflow's `{run_id}` for downstream correlation
+- `healthCheckDispatched` — boolean, set by §7 after the dispatch decision
+
+The `{forge_version}/.test-skill.lock` acquired in step-01 §6b remains held until the end of this step — it guards against concurrent latest-file overwrites.
+
+### 5. Finalize Output Document — Enforce Step Completeness
+
+**Per S6 (incremental step tracking):** read `stepsCompleted` from the output frontmatter. The expected set is the canonical chain:
+
+```
+['step-01-init',
+ 'step-02-detect-mode',
+ 'step-03-coverage-check',
+ 'step-04-coherence-check',
+ 'step-04b-external-validators',
+ 'step-05-score',
+ 'step-06-report']
+```
+
+If any expected entry is missing, HALT with "step completeness violation — missing {list}; workflow state is inconsistent, do not finalize the report". Only append `'step-06-report'` and write back after the check passes.
+
+**M4 — Section anchor presence check (companion to stepsCompleted).** The
+report template ships six canonical H2 anchors — one per populating step. An
+off-sequence run (e.g. a step wrote its section into the wrong anchor, or a
+subagent truncated the file) can leave `stepsCompleted` intact while a section
+is missing. `grep -n` each anchor below against `{outputFile}`; each MUST
+return ≥1 match:
+
+```
+^## Test Summary$
+^## Coverage Analysis$
+^## Coherence Analysis$
+^## External Validation$
+^## Completeness Score$
+^## Gap Report$
+```
+
+On any miss, HALT with "report anchor missing: {anchor} — section was not
+appended by its owning step". Do NOT append `'step-06-report'` and do NOT
+write the result contract. The template in `templates/test-report-template.md`
+declares these anchors as TBD placeholders; a miss means a step silently
+skipped its append.
+
+**INCONCLUSIVE as gate:** if `testResult == 'inconclusive'` (from step-05), the report final presentation (§6) and result contract (§4c) have already been written with that verdict. Do NOT auto-map INCONCLUSIVE to PASS or FAIL. Recommend `manual-review`. The step must still complete (health-check runs unconditionally) — INCONCLUSIVE is a report-time signal, not a workflow abort.
+
+### 6. Present Final Report
+
+"**Test complete for {skill_name}.**
+
+---
+
+**Result:** **{PASS|PASS_WITH_DRIFT|FAIL|INCONCLUSIVE}** — **{score}%** (threshold: {threshold}%)
+
+**Gaps Found:** {total_gaps}
+- Critical: {N}
+- High: {N}
+- Medium: {N}
+- Low: {N}
+- Info: {N}
+
+**Report saved to:** `{outputFile}`
+
+---
+
+**Recommended next step:**
+
+{IF PASS:}
+**export-skill** — This skill is ready for export. Run the export-skill workflow to package it for distribution.
+
+{IF PASS_WITH_DRIFT:}
+**update-skill** — The skill scored above threshold, but `--allow-workspace-drift` was in effect: the test ran against workspace HEAD, not `metadata.source_commit`. A conditional PASS is not trustworthy enough to export. Re-sync the source tree to the pinned commit (or re-extract against current HEAD) and re-run test-skill without the drift override before exporting.
+
+{IF FAIL:}
+**update-skill** — This skill needs remediation. Review the gap report above and run the update-skill workflow to address the {N} blocking issues (Critical + High).
+
+{IF INCONCLUSIVE:}
+**manual-review** — The evidence base was too thin to grade automatically. See `inconclusiveReasons` in the Completeness Score section. Typical fixes: upgrade forge tier, enable external validators, or re-extract with a wider scope. Do NOT export.
+
+---
+
+**See Discovery Quality section in the report for description optimization and realistic prompt testing recommendations.**
+
+**Test report finalized.**"
+
+### 6b. Headless Exit Status (S7)
+
+If `{headless_mode}`:
+- `testResult: 'pass'` → `exit 0`
+- `testResult: 'pass-with-drift'` → `exit 4` (distinct from clean pass — orchestrators MUST route to re-test-against-pinned-commit queues and refuse export; never exit 0 under drift override)
+- `testResult: 'fail'` → `exit 2` (after the result contract has been written in §4c — never before)
+- `testResult: 'inconclusive'` → `exit 3` (distinct from fail so orchestrators can route to manual-review queues)
+
+Non-headless mode always drops to the menu in §7.
+
+### 7. Health-Check Dispatch + MENU OPTIONS
+
+Resolve `{healthCheckFile}` per H2: probe `{healthCheckProbeOrder}` in order. **HALT** if neither candidate exists — the health-check is the true terminal step; without it the workflow cannot complete honestly:
+
+```
+Error: cannot locate shared/health-check.md at either of:
+  - {project-root}/_bmad/skf/shared/health-check.md
+  - {project-root}/src/shared/health-check.md
+
+test-skill delegates its terminal step to the shared health-check. Install
+the SKF module or run from a development checkout with src/ present.
+```
+
+Before displaying the menu, write the dispatch decision into the output report frontmatter (so the artifact records whether the health-check ran):
+
+- `health_check_dispatched: true` — when the C menu choice will be taken (headless, or user will select C)
+- `health_check_dispatched: false` — should be rare (only if operator explicitly skips, e.g. future flag)
+
+Also mirror the boolean into the `healthCheckDispatched` field of the result contract written in §4c (re-write atomically via `{atomicWriteHelper}` if the dispatch decision is made after the initial contract write).
+
+Display: "**Test complete.** [C] Finish"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past report menu"; set `health_check_dispatched: true` in frontmatter before chaining
+- C triggers the health check, which is the true workflow exit
+- User may ask questions about the report before finishing
+
+## CRITICAL STEP COMPLETION NOTE
+
+When the user selects C, this step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the test-skill workflow is fully done. The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
+

package/src/skf-test-skill/steps-c/step-07-health-check.md

@@ -0,0 +1,25 @@
+---
+# `{nextStepFile}` is resolved by probing both candidate roots in order.
+# HALT if neither exists — step-06 §7 should have caught this already, but
+# this step re-asserts the invariant at dispatch time.
+nextStepFileProbeOrder:
+  - '{project-root}/_bmad/skf/shared/health-check.md'
+  - '{project-root}/src/shared/health-check.md'
+---
+
+# Step 7: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check. This is the terminal step of test-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- Delegate directly to the resolved health-check path with no additional commentary
+- Do not attempt any other action between loading this step and executing the resolved file
+
+## MANDATORY SEQUENCE
+
+1. Probe `{nextStepFileProbeOrder}` in order. Use the FIRST path that exists as `{nextStepFile}`. HALT with the diagnostic from step-06 §7 if neither exists.
+2. Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-test-skill/templates/test-report-template.md

@@ -0,0 +1,58 @@
+---
+workflowType: 'test-skill'
+skillName: ''
+skillDir: ''
+runId: ''
+testMode: ''
+forgeTier: ''
+testResult: ''
+score: ''
+threshold: ''
+analysisConfidence: ''
+toolingStatus: ''
+workspaceDrift: ''
+health_check_dispatched: false
+testDate: ''
+stepsCompleted: []
+nextWorkflow: ''
+---
+
+# Test Report: {{skillName}}
+
+<!--
+Section order is LOAD-BEARING: step-05 §5 enforces it, step-06 §5 verifies
+stepsCompleted against the canonical chain. Do not reorder or delete anchors.
+
+Anchor / Step mapping:
+  Test Summary       → step-02-detect-mode
+  Coverage Analysis  → step-03-coverage-check
+  Coherence Analysis → step-04-coherence-check
+  External Validation→ step-04b-external-validators
+  Completeness Score → step-05-score
+  Gap Report         → step-06-report (includes Discovery Quality subsection)
+-->
+
+## Test Summary
+
+<!-- Populated by step-02-detect-mode §3 -->
+
+## Coverage Analysis
+
+<!-- Populated by step-03-coverage-check §5 -->
+
+## Coherence Analysis
+
+<!-- Populated by step-04-coherence-check §6 (naive or contextual variant) -->
+
+## External Validation
+
+<!-- Populated by step-04b-external-validators §5 -->
+
+## Completeness Score
+
+<!-- Populated by step-05-score §6 -->
+
+## Gap Report
+
+<!-- Populated by step-06-report §3-§4b (includes Discovery Quality subsection) -->
+

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

@@ -0,0 +1,58 @@
+---
+name: skf-update-skill
+description: Smart regeneration preserving [MANUAL] sections after source changes. Use when the user requests to "update a skill" or "regenerate a skill."
+---
+
+# Update Skill
+
+## Overview
+
+Surgically updates existing skills when source code changes, preserving all [MANUAL] developer content while re-extracting only affected exports with full provenance tracking. Only changed exports are re-extracted — unchanged content is never touched. Every regenerated instruction must trace to code with file:line citations. Stack skills (`skill_type: "stack"` in metadata.json) are not supported by surgical update — use `skf-create-stack-skill` to re-compose from updated constituents. If a stack skill is provided, this workflow exits with a redirect message.
+
+## Role
+
+You are a precision code analyst operating in Ferris Surgeon mode. This is a surgical operation, not an exploratory session. You bring AST-backed structural analysis and provenance-driven change detection expertise, while the source code provides the ground truth.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Never hallucinate — every statement must have AST provenance
+- [MANUAL] sections survive regeneration with zero content loss
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Initialize & Load | steps-c/step-01-init.md | No (confirm) |
+| 2 | Detect Changes | steps-c/step-02-detect-changes.md | Yes |
+| 3 | Re-Extract | steps-c/step-03-re-extract.md | Yes |
+| 4 | Merge | steps-c/step-04-merge.md | Yes |
+| 5 | Validate | steps-c/step-05-validate.md | Yes |
+| 6 | Write | steps-c/step-06-write.md | Yes |
+| 7 | Report | steps-c/step-07-report.md | Yes |
+| 8 | Workflow Health Check | steps-c/step-08-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | skill_name [required] |
+| **Gates** | step-01: Confirm Gate [C] | step-04: Confirm Gate [C if clean merge, HALT if conflicts] |
+| **Outputs** | Updated SKILL.md, updated provenance-map.json, evidence-report.md |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/{workflows/update-skill/data → skf-update-skill/references}/manual-section-rules.md

@@ -27,12 +27,12 @@ It must be preserved during any update operation.
 
 ### Conflict Types
 
-| Conflict | Severity | Resolution |
-|----------|----------|------------|
-| Regenerated content overlaps [MANUAL] position | HIGH | Present both versions, user chooses |
-| Parent section deleted | WARNING | Flag orphaned [MANUAL], user decides keep/remove |
-| [MANUAL] references deleted export | MEDIUM | Flag stale reference, suggest update |
-| New export inserted adjacent to [MANUAL] | LOW | Auto-resolve: place new content before [MANUAL] block |
+| Conflict                                       | Severity | Resolution                                            |
+|------------------------------------------------|----------|-------------------------------------------------------|
+| Regenerated content overlaps [MANUAL] position | HIGH     | Present both versions, user chooses                   |
+| Parent section deleted                         | WARNING  | Flag orphaned [MANUAL], user decides keep/remove      |
+| [MANUAL] references deleted export             | MEDIUM   | Flag stale reference, suggest update                  |
+| New export inserted adjacent to [MANUAL]       | LOW      | Auto-resolve: place new content before [MANUAL] block |
 
 ### Preservation Algorithm
 

package/src/{workflows/update-skill/data → skf-update-skill/references}/merge-conflict-rules.md

@@ -55,8 +55,8 @@ For stack skills with multi-file outputs:
 
 ## Conflict Resolution Strategies
 
-| Strategy | When | Action |
-|----------|------|--------|
-| Auto-resolve | No [MANUAL] conflicts, clean merge | Proceed without user input |
-| User-resolve | [MANUAL] conflicts detected | Halt, present conflicts, require decision |
-| Abort | Critical structural incompatibility | Stop workflow, recommend full re-creation |
+| Strategy     | When                                | Action                                    |
+|--------------|-------------------------------------|-------------------------------------------|
+| Auto-resolve | No [MANUAL] conflicts, clean merge  | Proceed without user input                |
+| User-resolve | [MANUAL] conflicts detected         | Halt, present conflicts, require decision |
+| Abort        | Critical structural incompatibility | Stop workflow, recommend full re-creation |

package/src/skf-update-skill/references/remote-source-resolution.md

@@ -0,0 +1,94 @@
+# Remote Source Resolution (Forge/Deep Tier)
+
+If `source_root` is a local path: proceed with the tier-appropriate strategy as normal.
+
+If `source_root` (from metadata.json) is a remote URL (GitHub URL or owner/repo format) AND tier is Forge or Deep:
+
+1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
+
+2. **Resolve source ref:** Read `source_ref` from the existing `metadata.json`. If the user provided a new `target_version`, resolve its tag first (using the Tag Resolution algorithm in `create-skill/references/source-resolution-protocols.md`).
+
+   **Note — implicit tag resolution is NOT re-run on update:** `create-skill`'s Implicit Tag Resolution path (which treats `brief.version` as an implicit `target_version` for remote sources) runs only at create time. On update, `skf-update-skill` faithfully re-uses the `source_ref` that was stored in `metadata.json` by the original create — even if that ref is `HEAD` and the brief now has a `version` that would resolve to a tag. This preserves the invariant that an update reflects source drift on the same ref the skill was originally built against, not a re-pinning to a different commit. If the intent is to re-pin an older HEAD-based skill to a tag derived from `brief.version`, re-run `skf-create-skill` (which applies implicit resolution) rather than `skf-update-skill`. Explicit re-pinning via a new `target_version` on update remains supported and takes priority over the stored `source_ref`.
+
+3. **Workspace check:** Compute the workspace path using the same algorithm as `create-skill/references/source-resolution-protocols.md` (parse URL → `{workspace_root}/repos/{host}/{owner}/{repo}/`).
+
+   **If workspace repo exists (`{workspace_repo_path}/.git/` present):**
+
+   Fetch and checkout the requested ref. For update-skill, `changed_files_from_manifest` scoping happens at extraction time via file-level filtering — the workspace has a full checkout.
+
+   ```
+   git -C "{workspace_repo_path}" fetch origin {source_ref}
+   ```
+
+   Check if checkout is needed — skip if the requested ref is already checked out:
+
+   ```
+   current_head = git -C "{workspace_repo_path}" rev-parse HEAD
+   fetched_head = git -C "{workspace_repo_path}" rev-parse FETCH_HEAD
+   ```
+
+   If `current_head != fetched_head`:
+   ```
+   git -C "{workspace_repo_path}" -c advice.detachedHead=false checkout FETCH_HEAD
+   ```
+
+   Set `remote_clone_path = {workspace_repo_path}`, `remote_clone_type = "workspace"`.
+
+   **If workspace repo does NOT exist:**
+
+   Clone into workspace. Create the parent directory first:
+
+   ```
+   mkdir -p "{workspace_root}/repos/{host}/{owner}/"
+   ```
+
+   Clone with the appropriate branch flag — `--branch` is only valid for real branch/tag names, not for `HEAD`:
+
+   ```
+   # If source_ref is a real branch or tag (not HEAD/null/"local"):
+   git clone --depth 1 --branch {source_ref} --single-branch "{source_repo}" "{workspace_repo_path}"
+
+   # If source_ref is HEAD or not set (default branch):
+   git clone --depth 1 --single-branch "{source_repo}" "{workspace_repo_path}"
+   ```
+
+   Set `remote_clone_path = {workspace_repo_path}`, `remote_clone_type = "workspace"`.
+
+   **On any workspace failure:** Fall back to ephemeral clone:
+   ```
+   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
+
+   # If source_ref is a real branch or tag (not HEAD/null/"local"):
+   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none "{source_root}" "{temp_path}"
+
+   # If source_ref is HEAD or not set (default branch):
+   git clone --depth 1 --single-branch --filter=blob:none "{source_root}" "{temp_path}"
+   ```
+   Set `remote_clone_path = {temp_path}`, `remote_clone_type = "ephemeral"`.
+
+4. **If clone/fetch succeeds:** Set `source_root = {remote_clone_path}` — this updates the working source path for all subsequent operations. Apply `changed_files_from_manifest` as file-level filters at extraction time. Proceed with the **Forge tier** extraction strategy below.
+
+5. **If all cloning fails (workspace AND ephemeral):**
+
+   Warning message: "Clone of `{source_root}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and re-run [CS] Create Skill with the local path, then re-run this update."
+
+   Override the extraction strategy to Quick tier for this run. Note the degradation reason in context for the evidence report.
+
+## Remote Clone Cleanup
+
+After extraction is complete for all files in scope (whether successful or partially failed), before presenting the extraction summary:
+
+- **If `remote_clone_type == "ephemeral"`:** Reset the working directory first (`cd "{project-root}"` using the absolute path captured at workflow start), then delete the `{temp_path}` directory (`rm -rf "{temp_path}"`). Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed.
+- **If `remote_clone_type == "workspace"`:** No cleanup. The workspace checkout persists for future forges and updates.
+
+## Version Reconciliation
+
+After the source path is accessible, check whether the source version has changed since the original skill was created. Look for the version file matching the detected language (e.g., `pyproject.toml`, `package.json`, `Cargo.toml`). If the source version differs from the current `metadata.json` version, record `source_version_detected` in context for step-06 to use when updating `metadata.json`. No warning needed here — step-06 handles the version update.
+
+## AST Tool Unavailability (Local Source)
+
+If AST tool is unavailable at Forge/Deep tier with local source:
+
+Warning message: "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."
+
+Degrade to Quick tier extraction. Note the degradation reason in context for the evidence report.