bmad-module-skill-forge 0.8.4 → 0.9.0

package/src/workflows/drop-skill/steps-c/step-03-report.md

@@ -0,0 +1,135 @@
+---
+name: 'step-03-report'
+description: 'Report drop operation results'
+---
+
+# Step 3: Report Drop Results
+
+## STEP GOAL:
+
+Present a clear, final summary of what the drop workflow changed — manifest state, platform context files, deleted directories, disk freed, and remaining versions — so the user can verify the outcome and know whether any manual follow-up is required.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER modify any files in this step — report only
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, summarizing what step-02 already executed
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are Ferris in Management mode — summarizing a destructive operation with precision
+- ✅ Be explicit about what changed and what did not — no glossing over partial failures
+- ✅ Surface recovery guidance when any stage in step-02 reported an error
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on reporting the results stored in context by step-02
+- 🚫 FORBIDDEN to re-execute any part of the drop
+- 🚫 FORBIDDEN to hide verification errors or failed platform rebuilds
+- 💬 Present the final state clearly, including remaining versions for the affected skill
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Render the report using the context values set in step-02 (`target_skill`, `target_versions`, `drop_mode`, `is_skill_level`, `files_deleted`, `disk_freed`, `manifest_updated`, `platform_files_updated`, `platform_files_failed`, `verification_errors`)
+- 📖 For the "remaining versions" section, re-read `{skills_output_folder}/.export-manifest.json` (already updated by step-02) to show the current state
+- 💬 Include the reversibility note only when `drop_mode == "deprecate"`
+
+## CONTEXT BOUNDARIES:
+
+- Available: All decision and result values stored in context by step-01 and step-02, plus the updated export manifest on disk
+- Focus: Rendering the final report
+- Limits: No file writes, no deletions, no further execution
+- Dependencies: Step-02 must have completed (or attempted all stages) and stored its results
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Determine Remaining Versions
+
+**If `is_skill_level == true`:**
+
+Set `remaining_versions_display = "(skill fully removed)"`.
+
+**If `is_skill_level == false`:**
+
+Read `{skills_output_folder}/.export-manifest.json` and look up `exports.{target_skill}.versions`. Build a human-readable list of every remaining version with its status, with the active one marked:
+
+```
+  - 0.1.0 (deprecated)
+  - 0.5.0 (archived)
+  - 0.6.0 (active) *
+```
+
+### 2. Render the Report
+
+Display the following block, filling in values from context:
+
+```
+**Drop operation complete.**
+
+Operation:     {Deprecate | Purge}
+Skill:         {target_skill}
+Version(s):    {comma-separated target_versions or "ALL"}
+
+Changes:
+- Manifest updated:      {yes | no}
+- Platform files rebuilt: {list from platform_files_updated, or "(none)"}
+{if platform_files_failed is non-empty:}
+- Platform files FAILED: {list from platform_files_failed}
+{if drop_mode == "purge":}
+- Files deleted:         {list from files_deleted, or "(none — nothing on disk)"}
+- Disk space freed:      {disk_freed}
+
+Remaining versions for {target_skill}:
+{remaining_versions_display}
+
+{if drop_mode == "deprecate":}
+**Note:** Files remain on disk. This operation is reversible by manually editing
+`{skills_output_folder}/.export-manifest.json` and changing the version's `status`
+field back to `"active"` or `"archived"`, then re-running `[EX] Export Skill` to
+restore the managed section entry.
+
+{if verification_errors is non-empty:}
+**Verification warnings:**
+{list each verification error}
+These require manual review — see the error-handling guidance in step-02.
+```
+
+### 3. Close the Workflow
+
+After rendering the report, the workflow is complete. Do not load any further step file — there is no `nextStepFile`.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final step. Once the report has been rendered, the drop-skill workflow is finished. Do not re-run any earlier step automatically — if the user wants another drop, they should re-invoke the workflow from the top.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Report rendered with operation type, skill, version(s), and mode
+- Manifest update outcome clearly stated (yes/no)
+- Platform files rebuilt listed (and failures surfaced when present)
+- Purge mode: files deleted and disk freed reported
+- Soft drop: reversibility note included with concrete instructions
+- Remaining versions for the affected skill accurately listed from the updated manifest (or "(skill fully removed)" for skill-level drops)
+- Verification warnings surfaced, not hidden
+- No further file writes or executions performed
+
+### ❌ SYSTEM FAILURE:
+
+- Hiding failed platform rebuilds or verification errors
+- Reporting "complete" when step-02 partially failed without flagging it
+- Reading stale manifest data instead of the post-drop state
+- Re-executing any part of the drop workflow
+- Omitting the reversibility note in soft drop mode
+- Displaying remaining versions from memory rather than from the updated manifest
+
+**Master Rule:** The report must be an honest, complete summary of what step-02 actually did. Every partial failure must be visible so the user knows exactly what manual follow-up, if any, is required.

package/src/workflows/drop-skill/workflow.md

@@ -0,0 +1,63 @@
+---
+name: drop-skill
+description: "Drop (deprecate or purge) skill versions. Soft drop keeps files; hard drop deletes them. Active version guarded."
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/drop-skill'
+---
+
+# Drop Skill
+
+**Goal:** Drop a specific skill version or an entire skill, either as a soft deprecation (manifest-only, files retained) or a hard purge (files deleted). Ensures platform context files are rebuilt to exclude dropped versions.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also Ferris in Delivery/Management mode — a destructive operation specialist who enforces safety guards. You treat every drop as potentially irreversible and require explicit user confirmation before touching the manifest or the filesystem. You protect the active version, keep the export manifest consistent with on-disk state, and ensure that downstream platform context files (CLAUDE.md / AGENTS.md / .cursorrules) are rebuilt so dropped versions disappear cleanly.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory — never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **Safety-First Destruction**: Every destructive action is preceded by an explicit user confirmation gate; nothing is deleted silently
+- **Manifest-Driven Truth**: The export manifest is the source of truth for what exists and what is active; the filesystem is updated to match
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- ⚙️ **TOOL/SUBPROCESS FALLBACK**: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- 🛡️ **NEVER** delete files without explicit user confirmation in purge mode
+- 🛡️ **NEVER** drop an active version when other non-deprecated versions exist — enforce the active version guard
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full 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`
+- Generate and store `timestamp` as the current date-time in `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run and must not be regenerated in subsequent steps.
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `./steps-c/step-01-select.md` to begin the workflow.

package/src/workflows/export-skill/data/managed-section-format.md

@@ -18,9 +18,31 @@
 
 | Platform | Flag Value | Target File |
 |----------|-----------|-------------|
-| Claude | `claude` (default) | CLAUDE.md |
+| Copilot | `copilot` (default) | AGENTS.md |
+| Claude | `claude` | CLAUDE.md |
 | Cursor | `cursor` | .cursorrules |
-| Copilot | `copilot` | AGENTS.md |
+
+## IDE → Platform Mapping (config.yaml `ides` list)
+
+The installer writes installer-specific IDE identifiers to `config.yaml` under the `ides` key (not platform values). Any workflow that rebuilds platform context files from `config.yaml` MUST map each entry to a platform before looking up its target file.
+
+| config.yaml IDE value | Platform | Target File | Rationale |
+|----------------------|----------|-------------|-----------|
+| `claude-code` | `claude` | CLAUDE.md | native — reads `CLAUDE.md` and `.claude/skills/` |
+| `cursor` | `cursor` | .cursorrules | native — reads `.cursorrules` and `.cursor/skills/` |
+| `github-copilot` | `copilot` | AGENTS.md | native — reads `AGENTS.md` and `.agents/skills/` |
+| `codex` | `copilot` | AGENTS.md | OpenAI Codex reads `AGENTS.md` (same convention as copilot) |
+| `cline` | `copilot` | AGENTS.md | uses `AGENTS.md` as fallback context file |
+| `roo` | `copilot` | AGENTS.md | uses `AGENTS.md` as fallback context file |
+| `windsurf` | `copilot` | AGENTS.md | uses `AGENTS.md` as fallback context file |
+| `other` | `copilot` | AGENTS.md | generic AGENTS.md fallback |
+| _(any unknown value)_ | `copilot` | AGENTS.md | warn: "Unknown IDE '{value}' in config.yaml — defaulting to copilot" |
+
+**Deduplication:** When multiple IDE entries map to the same platform (e.g. `codex` and `cline` both → `copilot`), deduplicate so each platform is processed exactly once. Report the deduplication to the user.
+
+**Missing `ides` key:** If the `ides` key is absent from `config.yaml`, treat it as an empty list. If the resulting platform set is empty (no recognized entries), fall back to `["copilot"]`.
+
+This mapping is the single source of truth. Workflows that need it: `export-skill/step-01` (resolves `target_platforms` for the export), `drop-skill/step-02` and `rename-skill/step-02` (rebuild platform context files after a management operation).
 
 ## Four-Case Logic
 
@@ -62,13 +84,16 @@ Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker.
 
 ## Regeneration: Full Index Rebuild
 
-When regenerating (Case 3), rebuild the COMPLETE skill index:
+When regenerating (Case 3) or creating/appending (Cases 1-2), rebuild the skill index from the **exported skill set** only:
+
+1. Read `{skills_output_folder}/.export-manifest.json` (v2 schema — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)) to determine which skills have been explicitly exported and their `active_version` (if no manifest exists, only the current export target qualifies)
+2. For each skill in the exported set, resolve the snippet at `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md` (i.e., `{skill_package}/context-snippet.md`). Do NOT use glob patterns across version directories — always resolve via manifest `active_version` or `active` symlink
+3. Count total skills and stack skills (from filtered set only)
+4. Assemble filtered snippets into managed section
+5. Sort alphabetically by skill name
+6. Update the header line with correct counts
 
-1. Scan `{skills_output_folder}/*/context-snippet.md` for all exported skills
-2. Count total skills and stack skills
-3. Assemble all snippets into managed section
-4. Sort alphabetically by skill name
-5. Update the header line with correct counts
+**Rationale:** create-skill and update-skill also write `context-snippet.md` as a build artifact, but only export-skill is the publishing gate (ADR-K). The `.export-manifest.json` file tracks which skills have passed through export-skill, preventing draft skills from leaking into the agent's passive context.
 
 ## Safety Rules
 

package/src/workflows/export-skill/data/snippet-format.md

@@ -1,5 +1,17 @@
 # Context Snippet Format (Vercel-Aligned Indexed Format)
 
+## Platform Root Path Mapping
+
+The snippet `root:` path must reflect the platform-specific skills directory:
+
+| Platform | Root Path Prefix |
+|----------|-----------------|
+| `claude` | `.claude/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `copilot` | `.agents/skills/` |
+
+The root path in context-snippet.md on disk uses the **first platform in `target_platforms`** (the first entry from config.yaml IDE mapping, or the explicit `--platform` flag value if provided). When assembling managed sections for other platforms, step-04 rewrites root paths to match the target platform.
+
 ## Format Rules
 
 - Indexed pipe-delimited format per skill — retrieval instruction + file map + inline gotchas
@@ -13,7 +25,7 @@
 ## Single Skill Snippet Template
 
 ```markdown
-[{skill-name} v{version}]|root: skills/{skill-name}/
+[{skill-name} v{version}]|root: {platform_root}{skill-name}/
 |IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {top exports with () for functions, comma-separated}
@@ -21,7 +33,7 @@
 |gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
-- **Line 1:** Skill name + version + root path — version signals training data staleness
+- **Line 1:** Skill name + version + platform-aware root path — version signals training data staleness
 - **Line 2 (IMPORTANT):** Retrieval instruction — always present
 - **Line 3 (quick-start):** Anchor pointer to Quick Start section
 - **Line 4 (api):** Top exports from metadata.json `exports` array (up to 10, with `()` for functions)
@@ -31,7 +43,7 @@
 ## Stack Skill Snippet Template
 
 ```markdown
-[{project}-stack v{version}]|root: skills/{project}-stack/
+[{project}-stack v{version}]|root: {platform_root}{project}-stack/
 |IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
@@ -48,4 +60,4 @@
 - If fewer exports than the limit, list all available
 - If no exports data available, omit the api line
 - Section anchors must be verified against actual SKILL.md headings during generation. For split-body skills (where `references/` exists and `## Full` headings are stubs), if a heading is missing from SKILL.md, rewrite the anchor to point to the reference file path (preferred). Omit the anchor line only if the heading cannot be found in either SKILL.md or `references/*.md`
-- Skill path is relative to project root
+- Skill path is relative to project root and uses the platform-specific root prefix (see Platform Root Path Mapping above)

package/src/workflows/export-skill/steps-c/step-01-load-skill.md

@@ -59,23 +59,59 @@ To load the target skill's artifacts, validate they meet agentskills.io spec com
 
 Determine the skill to export and any flags:
 
-**Skill Path Discovery:**
+**Skill Path Discovery (version-aware — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)):**
 - If user provided a skill name or path as argument, use that
-- If not provided, search `{skills_output_folder}/*/SKILL.md` for available skills
+- If not provided, discover available skills using the export manifest:
+  1. Read `{skills_output_folder}/.export-manifest.json` — list skill names from `exports`
+  2. For each skill group directory in `{skills_output_folder}/`, check for `{skill_group}/active/{skill-name}/SKILL.md`
+  3. If neither manifest nor `active` symlink yields results, fall back to flat path: `{skills_output_folder}/{skill-name}/SKILL.md`
 - If multiple skills found, present list and ask user to select
 - If no skills found, halt: "No skills found in {skills_output_folder}/. Run create-skill first."
 
 **Flag Parsing:**
-- `--platform` flag: Check if provided (claude/cursor/copilot). Default: `claude`
+- `--platform` flag: Check if explicitly provided (claude/cursor/copilot)
 - `--dry-run` flag: Check if provided. Default: `false`
 
+**Platform Resolution:**
+
+If `--platform` is explicitly provided, use that single platform as the sole target. If other IDEs are configured in config.yaml, emit a note: "**Note:** Exporting to {platform} only. config.yaml also lists: {other-ides}. Run without `--platform` to export to all configured IDEs."
+
+If `--platform` is NOT provided, read the `ides` list from config.yaml and map each IDE to a target platform. Every IDE the installer offers has an explicit mapping — no silent skips.
+
+| config.yaml IDE value | Platform | Rationale |
+|----------------------|----------|-----------|
+| `claude-code` | `claude` | native — reads `CLAUDE.md` and `.claude/skills/` |
+| `cursor` | `cursor` | native — reads `.cursorrules` and `.cursor/skills/` |
+| `github-copilot` | `copilot` | native — reads `AGENTS.md` and `.agents/skills/` |
+| `codex` | `copilot` | OpenAI Codex reads `AGENTS.md` (same convention as copilot) |
+| `cline` | `copilot` | uses `AGENTS.md` as a fallback context file |
+| `roo` | `copilot` | uses `AGENTS.md` as a fallback context file |
+| `windsurf` | `copilot` | uses `AGENTS.md` as a fallback context file |
+| `other` | `copilot` | generic AGENTS.md fallback |
+| Any other value | `copilot` | warn: "Unknown IDE '{value}' in config.yaml — defaulting to copilot (AGENTS.md)" |
+
+When the same platform is produced by multiple IDE entries (e.g. both `codex` and `cline` map to `copilot`), deduplicate so each platform appears in `target_platforms` only once. Report the deduplication: "Multiple IDEs target the same platform — exporting to {platform} once."
+
+**Missing-key handling:** If the `ides` key is absent from config.yaml (older installation or manually edited file), treat it as an empty list.
+
+- If mapping produces one or more platforms (after dedup), store as `target_platforms` list
+- If mapping produces zero platforms (empty ides list and no recognized entries), fall back to `["copilot"]` with note: "No IDEs configured in config.yaml — defaulting to copilot (AGENTS.md / .agents/skills/)."
+
 "**Skill:** {skill-name}
-**Platform:** {platform} ({target-file})
+**Platform(s):** {platform-list} ({target-file-list})
 **Dry Run:** {yes/no}"
 
 ### 2. Load and Validate Skill Artifacts
 
-Load all files from the skill directory `{skills_output_folder}/{skill-name}/`:
+Resolve the skill's versioned path before loading artifacts:
+
+1. Read `{skills_output_folder}/.export-manifest.json` and look up `{skill-name}` in `exports` to get `active_version`
+2. If found: resolve to `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill-name}/active` — resolve to `{skill_group}/active/{skill-name}/`
+4. If neither: fall back to flat path `{skills_output_folder}/{skill-name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
+5. Store the resolved path as `{resolved_skill_package}` for all subsequent artifact loading
+
+Load all files from `{resolved_skill_package}`:
 
 **Required Files (hard halt if missing):**
 - `SKILL.md` — The main skill document
@@ -117,7 +153,7 @@ Load `{sidecar_path}/preferences.yaml` (if exists):
 
 ### 4b. Check Test Report (Quality Gate)
 
-Search for a test report at `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
+Search for a test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
 
 **If test report found:**
 - Read frontmatter `testResult` and `score`
@@ -146,7 +182,8 @@ Continue to step 5 regardless — this is advisory, not blocking.
 **Export Configuration:**
 | Setting | Value |
 |---------|-------|
-| **Platform** | {platform} → {target-file} |
+| **Platform(s)** | {platform-list} → {target-file-list} |
+| **Explicit --platform** | {yes (user-specified) / no (from config.yaml)} |
 | **Dry Run** | {yes/no} |
 | **Passive Context** | {enabled/disabled} |
 
@@ -183,6 +220,7 @@ ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will yo
 - All required files loaded and validated
 - metadata.json parsed with required fields
 - Export flags parsed (platform, dry-run)
+- config.yaml ides list consumed for multi-platform resolution when --platform not provided
 - Forge config checked for passive_context
 - Clear summary presented to user
 - User confirms correct skill
@@ -193,6 +231,7 @@ ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will yo
 - Not validating metadata.json fields
 - Not checking preferences.yaml for passive_context opt-out
 - Proceeding without user confirmation
+- Ignoring config.yaml ides list when no --platform flag is provided
 - Modifying any skill files (read-only step)
 
 **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/export-skill/steps-c/step-02-package.md

@@ -52,10 +52,10 @@ To assemble and validate an agentskills.io-compliant package structure from the
 
 ### 1. Validate Package Structure
 
-Verify the skill directory contains the expected agentskills.io package layout:
+Verify the skill package at `{resolved_skill_package}` (resolved in step-01 via manifest or `active` symlink — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)) contains the expected agentskills.io package layout:
 
 ```
-{skills_output_folder}/{skill-name}/
+{skill_package} = {skills_output_folder}/{skill-name}/{version}/{skill-name}/
 ├── SKILL.md              ← Required: Active skill document
 ├── metadata.json         ← Required: Machine-readable metadata
 ├── context-snippet.md    ← Will be generated/updated in step-03

package/src/workflows/export-skill/steps-c/step-03-generate-snippet.md

@@ -66,6 +66,30 @@ Auto-proceed immediately to {nextStepFile}.
 
 Load {snippetFormatData} and read the format template for the skill type.
 
+### 2.5. Check Existing Snippet
+
+Before generating new snippet content, check for a prior snippet:
+
+1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step-01 — see [knowledge/version-paths.md](../../../knowledge/version-paths.md))
+2. If it exists, extract the `|gotchas:` line (if any). Trim leading whitespace and the `|gotchas:` prefix, then capture the remaining content as `prior_gotchas_content`.
+3. **Detect the carry-forward marker:** If `prior_gotchas_content` starts with the token `[CARRIED]` (whitespace-insensitive), set `prior_gotchas_already_carried = true` and strip the marker before storing the remainder. Otherwise set `prior_gotchas_already_carried = false`.
+4. **Distinguish empty from absent:** If the `|gotchas:` line exists but has no non-whitespace content after the prefix, treat it as **absent** — set `prior_gotchas = null`. Only a non-empty value counts as a prior gotchas line worth carrying forward.
+5. If no prior snippet exists at all, set `prior_gotchas = null` and `prior_gotchas_already_carried = false`.
+
+These values will be used as a fallback in section 3 if new gotchas cannot be derived. The `[CARRIED]` marker provides a **hard one-cycle expiry**: gotchas that were already carried once will be dropped on the next carry-forward attempt rather than preserved indefinitely.
+
+### 2.7. Resolve Platform Root Path
+
+Using the first platform in `target_platforms` (resolved in step-01), resolve the root path prefix:
+
+| Platform | `{platform_root}` |
+|----------|-------------------|
+| `claude` | `.claude/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `copilot` | `.agents/skills/` |
+
+Store `{platform_root}` for use in snippet generation. The context-snippet.md written to disk uses this platform's root path.
+
 ### 3. Generate Snippet Content
 
 **For single skills (`skill_type: "single"`):**
@@ -74,11 +98,15 @@ Load {snippetFormatData} and read the format template for the skill type.
 2. Select top exports (up to 10 for Deep tier, 5 otherwise). Append `()` to function names.
 3. Read SKILL.md to extract: heading slugs for `#quick-start` and `#key-types`, inline summary of key types (~10 words)
 4. **Anchor verification (split-body awareness):** For each section anchor (`#quick-start`, `#key-types`), verify the heading exists in SKILL.md. If a `references/` directory exists and `## Full` headings in SKILL.md are absent or stubs (indicating split-body, not a stack skill's structural references), rewrite the anchor to point to the reference file path (e.g., `references/{file}.md#key-types`). If the heading cannot be resolved in either location, omit that anchor line from the snippet.
-5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior. If no gotchas, omit the gotchas line.
+5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior.
+   - **If new gotchas are derived:** Use them (they supersede any prior gotchas). Write as `|gotchas: {pitfall-1}, {pitfall-2}` with no marker.
+   - **If NO new gotchas are derived BUT `prior_gotchas` exists AND `prior_gotchas_already_carried == false`:** First carry-forward cycle — preserve the prior gotchas line, prefixing the value with `[CARRIED]` so the next export can detect that expiry has been reached. Write as `|gotchas: [CARRIED] {prior gotchas content}`. Emit warning: "**Gotchas preserved from prior export (one-cycle carry-forward).** These gotchas will be DROPPED on the next export unless new gotchas are derived or you manually refresh them. Review now if they are still applicable."
+   - **If NO new gotchas are derived AND `prior_gotchas` exists AND `prior_gotchas_already_carried == true`:** Expiry reached — drop the gotchas line entirely. Emit warning: "**Stale gotchas dropped** — the prior gotchas were already carried forward once and cannot be derived from the current evidence report. The snippet now has no gotchas line. If the prior gotchas are still relevant, re-add them to the evidence report's T2-future section and re-run export."
+   - **If NO new gotchas derived AND no `prior_gotchas`:** Omit the gotchas line.
 
 Generate:
 ```
-[{skill-name} v{version}]|root: skills/{skill-name}/
+[{skill-name} v{version}]|root: {platform_root}{skill-name}/
 |IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {export-1}(), {export-2}(), {export-3}, {export-4}(), {export-5}
@@ -88,19 +116,21 @@ Generate:
 
 **If fewer exports than limit:** List all available.
 **If no exports:** Omit the api line.
-**If no gotchas derivable:** Omit the gotchas line.
+**If no gotchas derivable AND no prior gotchas to carry forward:** Omit the gotchas line.
 
 **For stack skills (`skill_type: "stack"`):**
 
 Generate:
 ```
-[{project}-stack v{version}]|root: skills/{project}-stack/
+[{project}-stack v{version}]|root: {platform_root}{project}-stack/
 |IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
 |gotchas: {pitfall-1}, {pitfall-2}
 ```
 
+**Stack skill gotchas carry-forward:** Same one-cycle expiry logic as single skills. If no new gotchas derived and `prior_gotchas_already_carried == false`, preserve with the `[CARRIED]` prefix. If already carried once (`prior_gotchas_already_carried == true`), drop the line and warn loudly. See the single-skill steps for the complete protocol.
+
 ### 4. Verify Token Count
 
 Estimate token count of generated snippet (approximate: words * 1.3).
@@ -114,7 +144,7 @@ Estimate token count of generated snippet (approximate: words * 1.3).
 **If dry-run mode:**
 
 "**[DRY RUN] context-snippet.md would be written to:**
-`{skills_output_folder}/{skill-name}/context-snippet.md`
+`{resolved_skill_package}/context-snippet.md`
 
 **Content:**
 ```
@@ -127,10 +157,10 @@ Hold content in context for step-04.
 
 **If NOT dry-run:**
 
-Write the generated content to `{skills_output_folder}/{skill-name}/context-snippet.md`.
+Write the generated content to `{resolved_skill_package}/context-snippet.md`.
 
 "**context-snippet.md written.**
-**Path:** `{skills_output_folder}/{skill-name}/context-snippet.md`
+**Path:** `{resolved_skill_package}/context-snippet.md`
 **Estimated tokens:** {count}"
 
 ### 6. Proceed to Context Update
@@ -162,10 +192,12 @@ ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-
 - Token count estimated and within target
 - File written (or previewed in dry-run)
 - Passive context opt-out correctly handled (skip when disabled)
+- Prior gotchas checked and carried forward when new derivation yields nothing (with warning)
 - Auto-proceed to step-04
 
 ### ❌ SYSTEM FAILURE:
 
+- Silently dropping prior gotchas without checking for carry-forward
 - Deviating from Vercel-aligned indexed format
 - Including T2 annotations or temporal context
 - Not checking passive_context setting