bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-audit-skill/references/step-doc-drift.md

@@ -1,177 +0,0 @@
----
-nextStepFile: 'report.md'
-outputFile: '{forge_version}/drift-report-{timestamp}.md'
-# Resolve `{compareDocHashesHelper}` by probing `{compareDocHashesProbeOrder}`
-# in order (installed SKF module path first, src/ dev-checkout fallback); first
-# existing path wins. When neither resolves (uv/python absent), §2 falls back to
-# skipping the doc-drift check with a notice — see the graceful-failure rule.
-compareDocHashesProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
-  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
----
-
-<!-- Config: communicate in {communication_language}. -->
-
-# Step 5a: Documentation Drift
-
-## STEP GOAL:
-
-Compare documentation content hashes stored at compile time (in `doc_sources` within metadata.json) against the current upstream state. Produce a drift section that reports which tracked docs have changed, which are unreachable, and which were never hashed. This step is informational — doc drift does not affect the source code drift score.
-
-## Rules
-
-- Auto-proceed step — no user interaction
-- Graceful failure — if doc fetching fails for any URL, mark as `fetch_failed`, do not block the audit
-- Do not classify severity — doc drift is informational alongside source drift
-- If no `doc_sources` in metadata, skip with notice and auto-proceed
-- Never abort the audit pipeline on any failure in this step
-
-## MANDATORY SEQUENCE
-
-### 1. Check for doc_sources
-
-Check the skill metadata loaded at init (step 1 §3 — Load Skill Artifacts) for a `doc_sources` array.
-
-**If `doc_sources` is absent or metadata lacks the field:**
-
-Append to {outputFile}:
-
-```markdown
-## Documentation Drift
-
-No doc_sources recorded — skip doc drift check. This skill was compiled before doc tracking was available. Recompile with the current CS pipeline to enable doc drift detection.
-```
-
-Set `doc_drift_summary = { skipped_entirely: true }` in workflow context. Update {outputFile} frontmatter: append `'doc-drift'` to `stepsCompleted`. Auto-proceed to {nextStepFile}.
-
-**If `doc_sources` is present but an empty array:**
-
-Append to {outputFile}:
-
-```markdown
-## Documentation Drift
-
-No documentation sources tracked. The `doc_sources` array is empty — no drift check to perform.
-```
-
-Set `doc_drift_summary = { total_tracked: 0, skipped_entirely: false }` in workflow context. Update {outputFile} frontmatter: append `'doc-drift'` to `stepsCompleted`. Auto-proceed to {nextStepFile}.
-
-**If `doc_sources` is present and non-empty:** Continue to §2.
-
-### 2. Fetch and Hash Each Tracked Doc
-
-Fetching each URL, hashing the response bytes, comparing against the stored `content_hash`, and categorizing the outcome is deterministic work — and the model cannot compute a `sha256:{hexdigest}` of fetched bytes natively (it must shell out). Delegate the whole fetch/hash/compare pass to the shared script, which hashes byte-symmetrically with how `doc_sources` hashes were written at compile time and fetches independently of whether a WebFetch tool is wired.
-
-**Resolve `{compareDocHashesHelper}`** from `{compareDocHashesProbeOrder}`; first existing path wins.
-
-Run one deterministic comparison subprocess over the skill's `doc_sources`. The script reads the `doc_sources` array straight out of the skill's `metadata.json` (or accepts a bare `doc_sources` array, or `-` for stdin):
-
-```bash
-uv run {compareDocHashesHelper} compare-hashes {skill_path}/metadata.json
-```
-
-For each entry, the script:
-- **`content_hash` is `null`** → records it under `skipped_null_hash` and does **not** fetch the URL (there is no baseline to compare against).
-- **`content_hash` is non-null** → HTTP GETs the URL (15s timeout, same User-Agent as the compile side), computes `sha256:{hexdigest}` of the response body bytes, and compares against the stored `content_hash` (prefix-normalized so a bare-hex writer form still matches).
-  - Hashes match → `unchanged`.
-  - Hashes differ → `changed`, carrying `old_hash` and `new_hash`.
-  - Network error, timeout, or non-200 status → `fetch_failed`, carrying the failure `reason`. Not reported as drift.
-
-Parse the emitted JSON:
-
-```json
-{
-  "changed":           [{"url": "...", "old_hash": "sha256:...", "new_hash": "sha256:..."}],
-  "unchanged":         [{"url": "..."}],
-  "fetch_failed":      [{"url": "...", "old_hash": "sha256:...", "reason": "..."}],
-  "skipped_null_hash": [{"url": "..."}],
-  "stats": {"total_tracked": N, "changed": N, "unchanged": N, "fetch_failed": N, "skipped_null_hash": N}
-}
-```
-
-The script exits 0 on any well-formed input (even when everything drifted) and exits 2 only on malformed args/JSON — it never blocks this informational audit.
-
-If `uv`/`python` is unavailable or the script cannot be resolved — i.e. URL fetching is unavailable in the current environment — skip the doc drift check entirely with:
-
-```markdown
-## Documentation Drift
-
-Doc drift check skipped — URL fetching unavailable in current environment.
-```
-
-Set `doc_drift_summary = { skipped_entirely: true }` and auto-proceed.
-
-### 3. Build Drift Findings
-
-Read the categories and totals directly from the script's JSON — no manual counting. The four buckets are already computed:
-- **changed:** entries where the stored `content_hash` differs from the newly computed hash (`changed[]`)
-- **unchanged:** entries where the hashes match (`unchanged[]`)
-- **fetch_failed:** entries where the URL could not be reached (`fetch_failed[]`)
-- **skipped_null_hash:** entries where `content_hash` was `null` (`skipped_null_hash[]`)
-
-Take the totals straight from `stats` (do not recount):
-- `total_tracked` = `stats.total_tracked`
-- `changed` = `stats.changed`
-- `unchanged` = `stats.unchanged`
-- `fetch_failed` = `stats.fetch_failed`
-- `skipped_null_hash` = `stats.skipped_null_hash`
-
-### 4. Append to Drift Report
-
-Append the `## Documentation Drift` section to {outputFile}.
-
-**When drift detected:**
-
-```markdown
-## Documentation Drift
-
-| URL | Old Hash | New Hash | Detected At |
-|-----|----------|----------|-------------|
-| {url} | `{old_hash}` | `{new_hash}` | {ISO-8601 timestamp} |
-
-**{changed} of {total_tracked} tracked documentation source(s) have changed since compile.**
-```
-
-Include rows for ALL entries, in order:
-- Drifted entries: show old and new hash
-- Unchanged entries: omit from table (only drifted entries appear)
-- Fetch-failed entries: `| {url} | \`{old_hash}\` | _(fetch failed: {reason})_ | {timestamp} |`
-- Null-hash entries: `| {url} | _(not recorded)_ | — | — |`
-
-Fetch-failed entries are clearly marked and excluded from the drift count.
-
-**When no drift detected:**
-
-```markdown
-## Documentation Drift
-
-No documentation drift detected. All {total_tracked} tracked documentation source(s) match their compile-time hashes.
-```
-
-If some entries were fetch_failed or skipped_null_hash, append a note after the main message listing those entries.
-
-### 5. Store Context and Auto-Proceed
-
-Store `doc_drift_summary` in workflow context for report.md to reference:
-
-```
-doc_drift_summary = {
-  total_tracked: N,
-  changed: N,
-  unchanged: N,
-  fetch_failed: N,
-  skipped_null_hash: N,
-  skipped_entirely: false
-}
-```
-
-Update {outputFile} frontmatter:
-- Append `'doc-drift'` to `stepsCompleted`
-
-Display: "**Documentation drift check complete. {changed} of {total_tracked} source(s) drifted. Proceeding to report generation...**"
-
-Load, read the full file, then execute {nextStepFile}.
-
-## CRITICAL STEP COMPLETION NOTE
-
-Only when the ## Documentation Drift section has been appended to {outputFile} and workflow context updated do you then load and read fully `{nextStepFile}` to begin final report generation.

package/src/skf-brief-skill/references/headless-source-authority-detection.md

@@ -1,26 +0,0 @@
-# Headless Source-Authority Detection
-
-Loaded by step 1 §8 only when **all three** preconditions hold:
-
-1. `{headless_mode}` is true
-2. `source_authority` is absent from the validator's `normalized` output (the validator intentionally leaves it absent so detection can run here — when it was supplied in args, the supplied value wins and detection does not run)
-3. `source_type=source` AND `target_repo` is a GitHub URL
-
-When any precondition is unmet, skip this entire procedure: docs-only forces `community` in §3.2; local-path targets default to `community` directly; non-GitHub source URLs are not classifiable from `gh api user` and also default to `community`.
-
-## Procedure
-
-Probe the operator's GitHub login:
-
-```bash
-gh api user --jq .login
-```
-
-Compare the result to the `owner` segment of `target_repo` (URL pattern `https://github.com/<owner>/<repo>`) — **lower-case both values before comparing**. GitHub owner matching is case-insensitive but the API preserves case in responses, so a literal-string comparison would miss the match.
-
-| Outcome | Set | Rationale |
-|---------|-----|-----------|
-| login matches owner (case-insensitive) | `source_authority: "official"` | The operator is the repo's GitHub owner |
-| login does not match | `source_authority: "community"` | The operator is a downstream consumer |
-| `gh api user` errors (unauthenticated, network failure, missing binary) | `source_authority: "community"` (fallback) | Log `"warn: source-authority detection skipped — gh api user failed"` |
-| Local-path target | `source_authority: "community"` (no probe) | Comparison does not apply |

package/src/skf-campaign/manifest.yaml

@@ -1,15 +0,0 @@
-code: CA
-name: skf-campaign
-description: "Campaign orchestration — multi-library skill production with dependency tracking"
-version: "2.0.0"
-trigger: campaign
-parent_module: skf
-
-# Canonical internal filenames for the campaign workspace. Fixed contract (the
-# step chain references these names directly and test-skf-campaign-state guards
-# them against drift) — NOT an operator-override surface; customize.toml is the
-# only customization mechanism.
-config:
-  state_file: "_campaign-state.yaml"
-  backup_file: "_campaign-state.yaml.bak"
-  directive_file: "_campaign-directive.md"

package/src/skf-create-skill/assets/tessl-dismissal-rules.md

@@ -1,106 +0,0 @@
-# tessl Dismissal Rules
-
-This file is the **single source of truth** for tessl review findings that Skill Forge expects and must dismiss. Step-06 §6 loads this file, parses the `tessl skill review` JSON output, and cross-references each finding against the rules below. Matches are dismissed with their rationale logged to the evidence report; non-matches surface to the user via §6b. Never embed dismissal logic in step files — update the rules here first and reference them from step 6.
-
----
-
-## Score Thresholds
-
-When parsing tessl output, check these fields against the thresholds below. Violations trigger warnings or errors as specified.
-
-| Field | Threshold | Severity on violation | Rationale |
-|---|---|---|---|
-| `review_score` (overall) | `>= 60` | warn | Two-tier SKF skills trade some conciseness score for progressive disclosure. 60 is the floor below which something is genuinely wrong. |
-| `description_field` validator finding | none expected | **error — recover, then halt** | The **deterministic** `description_field` validator surfaces as a `findings[]` entry (not as the judge percentage). It parses the frontmatter `description` as a raw string and rejects angle-bracket / XML-tag content. step 5 §2a unconditionally replaces `<` with `{` and `>` with `}` before validation, so a `description_field` finding means the sanitizer was bypassed — a downstream tool rewrote the description. Attempt recovery per rule `description-xml-tags-guarded-upstream` (re-apply the §2a substitution in place on the staging SKILL.md frontmatter and re-run tessl). Halt only if recovery fails. |
-| `description_score` (LLM judge %) | `>= 60` | warn | The judge's 0–100 discoverability score, composed of `trigger_term_quality`, `specificity`, `completeness`, and `distinctiveness` sub-scores. A value below 100 while the deterministic `description_field` validator PASSES is a soft discoverability hint (e.g. jargon density), **not** a sanitizer bypass — record a warning and continue. Never halt on the judge percentage alone; the authored brief is the source of truth for the description. |
-| `content_score` | `>= 60` | warn | Two-tier design deliberately duplicates key API data across Tier 1 and Tier 2. Conciseness scorer penalizes this. 60 is the acceptable floor. |
-
-**Recovery is gated on the deterministic validator, not the judge percentage.** If tessl emits a `findings[]` entry with rule ID `description_field` (angle-bracket / XML-tag rejection), **attempt recovery first** per rule `description-xml-tags-guarded-upstream` below: re-apply step 5 §2a's `<` → `{` / `>` → `}` substitution in place on the staging SKILL.md frontmatter `description`, then re-run `npx -y tessl skill review <staging-skill-dir>` once. If the re-run clears the `description_field` finding, log `description-recovery: applied ({count} substitutions)` in the evidence report and proceed to normal suggestion handling. If recovery fails, halt with: "Description sanitization recovery failed — step 5 §2a's `<`/`>` → `{`/`}` replacement did not resolve the tessl finding. Investigate the staging SKILL.md frontmatter for non-angle-bracket content that tessl is still rejecting, and patch §2a accordingly. Do not edit the description manually." Do not proceed to §6b user prompt on an unrecovered failure.
-
-A `description_score` (LLM judge %) below 100 **without** an accompanying `description_field` finding is **not** a recovery trigger and **not** a halt condition: record `description_judge_score: {n}% (deterministic description_field validator PASSED)` as a warning in the evidence report and continue to suggestion handling. The recover-then-halt path is reserved for the deterministic validator.
-
----
-
-## Suggestion Dismissal Rules
-
-Each rule below describes a tessl suggestion that Skill Forge expects and dismisses automatically. For each `judge_suggestion` in tessl output, check it against these rules in order. If any rule matches, record the dismissal in the evidence report (`rule_id`, `rationale`) and do not apply the suggestion. If no rule matches, the suggestion is novel and must surface to the user in §6b.
-
-### Rule: `remove-manual-markers`
-
-- **Scorer:** any
-- **Match criteria (any of):**
-  - Suggestion text contains `[MANUAL]` AND one of: `remove`, `delete`, `strip`, `clean up`
-  - Suggestion text contains `manual marker` AND one of: `remove`, `delete`, `unnecessary`
-- **Rationale:** `<!-- [MANUAL] -->` markers delineate author-added content that `skf-update-skill` preserves during merge operations. Removing them would cause update-skill to overwrite author edits on the next run. The markers are a load-bearing contract between create-skill, test-skill, and update-skill.
-- **Action:** dismiss.
-
-### Rule: `move-full-api-reference`
-
-- **Scorer:** any
-- **Match criteria (all of):**
-  - Suggestion text mentions `Full API Reference` OR a `## Full ...` section heading
-  - Suggestion text contains one of: `move`, `relocate`, `extract`, `split out`, `separate file`, `external file`
-- **Rationale:** The two-tier design (Tier 1 inline + Tier 2 inline) keeps Tier 2 sections inline by default. `skill-check split-body` relocates Tier 2 to `references/` only when the body exceeds size limits — see step 6 §4. Preemptive relocation destroys the standalone SKILL.md that the cited 100% task accuracy (vs. 79% for on-demand retrieval) depends on.
-- **Action:** dismiss.
-
-### Rule: `consolidate-duplicate-parameters`
-
-- **Scorer:** `conciseness` or any
-- **Match criteria (any of):**
-  - Suggestion mentions `duplicate parameter`, `redundant parameter`, `consolidate parameter`
-  - Suggestion mentions both `Key API` / `Key API Summary` AND `Full API Reference` and suggests merging them
-- **Rationale:** Tier 1 Key API Summary intentionally lists only key parameters for standalone discoverability. Tier 2 Full API Reference provides complete parameter tables, types, defaults, and edge cases. This is progressive disclosure, not duplication. Consolidating would force agents to scroll to Tier 2 for the most common function calls, defeating Tier 1's purpose and breaking the split-body Tier 1 preservation contract in step 6 §4.
-- **Action:** dismiss.
-
-### Rule: `conciseness-redundancy-between-tiers`
-
-- **Scorer:** `conciseness`
-- **Match criteria (all of):**
-  - Scorer is `conciseness`
-  - Suggestion or score rationale references redundancy between Tier 1 and Tier 2 sections (typically `Key API` ↔ `Full API` or `Quick Start` ↔ `Full Reference`)
-- **Expected score:** 2/3 is normal. 3/3 is only achievable by collapsing the two-tier design.
-- **Rationale:** Progressive disclosure is the intentional SKF design. The conciseness scorer has no concept of Tier 1 / Tier 2 and flags the structure as redundancy. Collapsing the two tiers would eliminate standalone discoverability and break split-body behavior.
-- **Action:** dismiss. Do not attempt to raise the score above 2/3.
-
-### Rule: `provenance-citations-required`
-
-- **Scorer:** `conciseness`, `actionability`, or any
-- **Match criteria (any of):**
-  - Suggestion text references `[SRC:`, `[AST:`, `[QMD:`, or `[EXT:` annotations AND one of: `remove`, `strip`, `omit`, `drop`
-  - Suggestion mentions `provenance annotations`, `source citations`, or `source markers` AND one of: `remove`, `unnecessary`, `token bloat`, `token cost`
-- **Expected score:** `conciseness` 1/3 is normal while inline provenance annotations are present. Raising it would require stripping the annotations.
-- **Rationale:** SKF's zero-hallucination policy requires every claim in SKILL.md to carry a provenance citation — see the "Signature fidelity" rule in `assets/compile-assembly-rules.md` and the "Provenance Citation Format" table in `assets/skill-sections.md`. Removing them would break the provenance audit trail and the trust contract that lets `skf-update-skill` detect source drift and `skf-audit-skill` verify claims against source.
-- **Action:** dismiss.
-
-### Rule: `description-xml-tags-guarded-upstream`
-
-- **Scorer:** `description_field` (deterministic validator)
-- **Match criteria (any of):**
-  - Finding rule ID is `description_field` AND message mentions `XML tag`, `must not contain`, or angle-bracket-related text
-- **Expected occurrence:** zero. step 5 §2a unconditionally replaces `<` with `{` and `>` with `}` in the frontmatter description before SKILL.md is written.
-- **Action:** **Attempt recovery, then halt if recovery fails.** This is not a dismissal — the finding represents a real sanitizer bypass that step 6 must resolve before proceeding.
-  1. **Re-apply §2a in place.** Read the current `description` from the on-disk staging SKILL.md frontmatter, replace every `<` with `{` and every `>` with `}`, and write the result back to the frontmatter. Re-sync the in-context copy to match. Count the substitutions; if zero, the description is already clean and the tessl finding points at something other than angle brackets — skip to the halt branch below.
-  2. **Re-run tessl once.** Execute `npx -y tessl skill review <staging-skill-dir>` a second time and re-parse the JSON output.
-  3. **On success** (the `description_field` finding is absent from the re-run): log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions", then continue §6 with the recovered review result (proceed to normal suggestion handling against the rules below). The rerun's `judge_suggestions[]` replaces the original. A residual judge `description_score < 100` on the re-run is a warning, not a failure — recovery success is keyed on the deterministic finding clearing, not on the judge percentage reaching 100.
-  4. **On failure** (the `description_field` finding persists after re-sanitization): halt with: "Description sanitization recovery failed — step 5 §2a's `<`/`>` → `{`/`}` replacement did not resolve the tessl finding. Investigate the staging SKILL.md frontmatter for non-angle-bracket content that tessl is still rejecting, and patch §2a accordingly. Do not edit the description manually."
-
-The recovery path makes the skill shippable when a downstream tool (`skill-check --fix`, `split-body`, or a future validator) re-introduces angle brackets into the description after §2a has run. The Description Guard Protocol in step 6 §0 is the first line of defense against such rewrites; this rule is the second line, active when the guard also missed.
-
----
-
-## How Step-06 §6 Uses This File
-
-1. Load this file completely at the start of §6.
-2. Run `npx -y tessl skill review <staging-skill-dir>` and parse JSON output.
-3. Check score thresholds. For a deterministic `description_field` finding (angle-bracket / XML-tag rejection): follow the recovery-then-halt path described in the threshold table above and the `description-xml-tags-guarded-upstream` rule below — re-apply §2a in place, re-run tessl once, and continue on recovery success (finding cleared) or halt on recovery failure. A judge `description_score` below 100 while the `description_field` validator passes is a warning, not a halt. For other warns: continue, log warnings to evidence report.
-4. For each `judge_suggestions[]` entry in the output:
-   a. Iterate the rules above in order.
-   b. If a rule's match criteria are satisfied, record `{rule_id, rationale, suggestion_text}` in the evidence report under "Dismissed tessl suggestions" and move to the next suggestion.
-   c. If no rule matches, add the suggestion to the "Novel tessl suggestions" list that §6b surfaces to the user.
-5. Proceed to §6b if any novel suggestions exist, or auto-proceed if all suggestions were dismissed.
-
----
-
-## Evolving This List
-
-When tessl changes or an SKF design decision shifts, add a new rule section above (`Rule:` / `Scorer:` / `Match criteria` / `Rationale` / `Action`), link each rationale to the concrete SKF design principle it protects (two-tier design, MANUAL markers, sanitization, split-body preservation — a rationale without such a link is a smell), and keep score thresholds at or above current production floors — never lower them to suppress real regressions.

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

@@ -1,74 +0,0 @@
----
-nextStepFile: 'sub/ccc-discover.md'
----
-
-<!-- Config: communicate in {communication_language}. -->
-
-# Step 2: Ecosystem Check
-
-## STEP GOAL:
-
-To search the agentskills.io ecosystem for an existing official skill matching the brief, advise the user if one is found, and allow them to decide whether to proceed with compilation or install the existing skill.
-
-## Rules
-
-- Focus only on ecosystem search and presenting findings — do not begin extraction
-- Do not halt the workflow if the ecosystem check fails or times out (5-second timeout)
-- If a match is found, present it factually — let the user decide
-
-## MANDATORY SEQUENCE
-
-### 1. Check Ecosystem for Existing Skill
-
-**Note:** Ecosystem lookup requires the agentskills.io registry API, which is not yet available. The `skill-check` CLI validates local skills but does not query a remote registry.
-
-**If agentskills.io registry API is available:**
-
-Query the ecosystem using the skill name from the brief:
-- Call the registry API with brief.name — check if an official skill already exists
-- Enforce 5-second timeout — if the query does not return within 5 seconds, treat as no match. Rationale: ecosystem check is an opportunistic advisory; a slow or degraded registry must not stall the compilation pipeline, and 5s is well beyond any healthy registry's p99 latency.
-- Cache results for 24 hours (if re-running same skill). Rationale: the agentskills.io registry publishes new official skills in daily batches; a 24-hour TTL balances freshness against redundant network calls during iterative brief refinement.
-
-**If registry API is not available (current default):**
-
-Skip completely and silently. Do not output any message about API unavailability or the ecosystem check being skipped. Emit zero text to the console. Proceed exactly as if no match was found.
-
-### 2. Evaluate Results
-
-**If match found (official skill exists):**
-
-Present the finding to the user:
-
-"**Ecosystem match found.**
-
-**Existing skill:** {matched_skill_name} v{matched_version}
-**Source:** {matched_source}
-**Authority:** {official/community}
-**Compatibility:** {compatibility_notes}
-
-An existing skill already covers this source. You can:
-- **[P] Proceed** — compile your own version anyway (useful for customization or different scope)
-- **[I] Install** — install the existing skill instead of compiling
-- **[A] Abort** — cancel this compilation"
-
-**If no match found:**
-
-Auto-proceed silently to next step. Do not display any message about the ecosystem check — absence of a match is the expected case.
-
-**If timeout or error:**
-
-Auto-proceed silently. Log a note in context: "Ecosystem check skipped (timeout/error) — proceeding with compilation."
-
-### 3. Gate — Ecosystem Match (conditional)
-
-This gate fires only when §2 found a match; on no match, timeout, or unavailable tool the step already auto-proceeded to `{nextStepFile}` with no menu.
-
-**GATE [default: P]** — under `{headless_mode}` with a match, auto-proceed as [P], log "headless: ecosystem match found, auto-proceeding", and append `{step: "ecosystem-check", gate: "ecosystem-match", decision: "P", rationale: "headless mode — match found, auto-proceed with user's own compilation", timestamp: {ISO}}` to `headless_decisions[]` and, the moment it lands, append the same object as a JSON line to the durable audit sink `{sidecar_path}/auto-decisions.jsonl` (the on-landing append established at step 1 §3) — the sink feeds the evidence-report `## Auto-Decisions` table at step 5 §7 and step 6 §8.
-
-Interactively, halt and wait for the user's choice on the §2 menu:
-
-- **P** — proceed despite the existing skill; load `{nextStepFile}`, read it fully, then execute it.
-- **I** — display "Install the existing skill using: `[SF] Setup Forge → install {matched_skill_name}`", then halt (no extraction).
-- **A** — display "Compilation aborted. Return to Ferris menu to select another action.", then halt.
-- Any other question — answer it, then redisplay the menu.
-

package/src/skf-drop-skill/references/headless-contract.md

@@ -1,18 +0,0 @@
-# Headless Result Envelope
-
-The single-line JSON contract every headless run of skf-drop-skill emits. It stands alone: the stages that emit it load this file directly, so an error path never depends on any other file staying in context under compaction.
-
-When `{headless_mode}` is true, step 3 emits this envelope on **stdout** before chaining to step 4; every HARD HALT emits the same shape on **stderr** with `status: "error"`:
-
-```
-SKF_DROP_SKILL_RESULT_JSON: {"status":"success|error|dry-run","skill":"…|null","drop_mode":"…|null","versions_affected":[],"files_deleted":[],"manifest_updated":false,"exit_code":0,"halt_reason":null}
-```
-
-Field rules:
-
-- `status` — `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited at the confirmation gate before any mutation, `"error"` on any HALT.
-- `halt_reason` — `null` on success/dry-run; otherwise one of `"input-missing"`, `"input-invalid"`, `"manifest-corrupt"`, `"nothing-to-drop"`, `"active-version-guard-refused"`, `"headless-purge-forbidden"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"delete-failed"`, `"write-failed"`, `"user-cancelled"`.
-- `exit_code` — the stable numeric code the emitting HALT specifies (`0` on success/dry-run).
-- `skill` / `drop_mode` / `versions_affected` / `files_deleted` / `manifest_updated` — the discriminating values the emit site supplies; any key not yet resolved at that point takes the default shown in the template (`null`, `[]`, or `false`).
-
-Each emit site supplies its own `exit_code`, `halt_reason`, and whichever discriminating fields are known at that point; all other keys default as shown.

package/src/skf-update-skill/references/merge-conflict-rules.md

@@ -1,15 +0,0 @@
----
-type: static-reference
----
-
-# Merge Conflict Rules
-
-> Change-category actions and the merge priority order (deleted → moved → renamed → modified → new, plus the gap-driven priorities) are specified authoritatively in `merge.md` §3. This reference carries only the one thing §3 does not: the conflict-resolution strategy table below.
-
-## 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 |

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

@@ -1,98 +0,0 @@
----
-type: static-reference
----
-
-# 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 6 to use when updating `metadata.json`. No warning needed here — step 6 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.