ma-agents 3.12.2 → 3.13.0

package/lib/bmad-cache/wds/src/workflows/wds-4-ux-design/workflow-specify.xml

@@ -0,0 +1,387 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="wds-4-specify" name="WDS Phase 4 — Specify Page" version="1.0">
+  <description>
+    Create a complete, implementation-ready page specification: layout, components with Object IDs,
+    multilingual content, interactions, states, validation, spacing, and typography.
+    All 9 steps must be completed in sequence before the specification is considered done.
+    Validation runs at step 9 before the spec is written to disk.
+  </description>
+
+  <prerequisites>
+    <require file="{output_folder}/C-UX-Scenarios/{scenario-slug}/{scenario-slug}.md" label="Scenario outline"/>
+    <require file="{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/" label="Page folder from Phase 3 or design activity"/>
+    <require file="{output_folder}/_progress/00-design-log.md" label="Design log"/>
+  </prerequisites>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- INITIALIZATION — runs before step 1                                -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <initialization>
+    <instruction>
+      Read the design log at {output_folder}/_progress/00-design-log.md before starting.
+      Check Current table for any in-progress work from a previous session.
+    </instruction>
+    <instruction>
+      Load page context from the existing page folder:
+      {output_folder}/C-UX-Scenarios/[NN-slug]/pages/[NN].[step]-[page-slug]/
+      The page boilerplate created in Phase 3 contains scenario, page number, platform,
+      page purpose, entry context, exit action, and on-page interactions.
+    </instruction>
+    <instruction>
+      Update the design log Current table: add this page with status "specifying".
+    </instruction>
+    <gate type="file-exists" path="{output_folder}/C-UX-Scenarios/{scenario-slug}/{scenario-slug}.md"
+          failure-message="Scenario outline must exist. Select a scenario from the design log before running Specify."/>
+    <gate type="folder-exists" path="{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/"
+          failure-message="Page folder must exist. Run Phase 3 or a design activity (Suggest/Dream) to create the page structure before specifying."/>
+  </initialization>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 1 — Page Basics                                               -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="1-page-basics" name="Capture page metadata and entry/exit points" step-file="steps-p/step-01-page-basics.md">
+    <instruction>
+      Present the page basics form to the user and collect all required fields:
+      - Page name/title
+      - URL/route (if applicable)
+      - Main user goal (one sentence)
+      - Entry points (where users come from)
+      - Exit points (where users go next)
+
+      For public pages, also collect SEO data — check the project brief's SEO Strategy for target keywords:
+      - Primary keyword
+      - Secondary keywords
+      - URL slug (from keyword map)
+    </instruction>
+    <instruction>
+      Store all captured values as page_basics:
+      page_title, url_route, user_goal, entry_points, exit_points,
+      primary_keyword (public pages), secondary_keywords (public pages), url_slug (public pages).
+    </instruction>
+
+    <gate type="data-captured" required="page_title url_route user_goal entry_points exit_points"
+          failure-message="All basic page fields must be captured before proceeding. Do not skip any field."/>
+    <gate type="seo-data-captured" condition="page-is-public"
+          required="primary_keyword secondary_keywords url_slug"
+          failure-message="SEO data is mandatory for public pages. Check the project brief's SEO Strategy section."/>
+    <gate type="user-confirms" prompt="All page basics captured and confirmed by user?"/>
+
+    <output>page_basics stored — title, route, goal, entry/exit points, and SEO data (if public page).</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 2 — Layout Sections                                           -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="2-layout-sections" name="Define major page sections" step-file="steps-p/step-02-layout-sections.md">
+    <instruction>
+      Ask the user to describe the major areas of the page (header, hero, main content, sidebar,
+      footer, etc.). Do not define individual components yet — only high-level sections.
+    </instruction>
+    <instruction>
+      For each section described, store:
+      - section_name
+      - section_purpose
+      - section_priority (primary / secondary)
+    </instruction>
+    <instruction>
+      Confirm the section list with the user before proceeding.
+    </instruction>
+
+    <gate type="data-captured" required="layout_sections" minimum-count="1"
+          failure-message="At least one layout section must be defined. Do not proceed to components without a section structure."/>
+    <gate type="section-attributes-complete" required-per-section="name purpose priority"
+          failure-message="Each section must have a name, purpose, and priority before proceeding."/>
+    <gate type="user-confirms" prompt="Layout sections defined and confirmed?"/>
+
+    <output>layout_sections stored — section names, purposes, and priorities captured.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 3 — Components and Object IDs                                 -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="3-components-objects" name="Identify components and assign Object IDs" step-file="steps-p/step-03-components-objects.md">
+    <instruction>
+      Work through each section identified in step 2. For each section, go top-to-bottom,
+      left-to-right. Ask the user to describe the next object in the section.
+    </instruction>
+    <instruction>
+      For each object described, load and execute the object router:
+      data/object-types/object-router.md
+      The router will: ask for object type, load the correct object-type template, guide through
+      complete documentation, generate a specification with an Object ID, then return here.
+    </instruction>
+    <instruction>
+      After each component specification is complete, check project config:
+      if design system is enabled, run workflows/wds-7-design-system/design-system-router.md
+      to check for similar components and extract component-level info. Update page spec with
+      the reference. If design system is disabled, keep the full specification on the page.
+    </instruction>
+    <instruction>
+      Continue until the user confirms all objects in the section are documented.
+      Move to the next section. Continue until all sections are complete.
+      Present a summary: sections processed, total components, components by type, all Object IDs assigned.
+    </instruction>
+
+    <gate type="all-sections-processed" rule="every-layout-section-has-been-worked-through"
+          failure-message="All sections from step 2 must be processed. Do not skip any section."/>
+    <gate type="object-ids-assigned" rule="every-component-has-an-object-id"
+          failure-message="Every documented component must have an Object ID before proceeding to content. Missing IDs block downstream steps."/>
+    <gate type="object-router-used" rule="every-component-routed-through-object-router"
+          failure-message="Object-type routing must be used for every component. Do not document components without using the router."/>
+    <gate type="design-system-check-performed" condition="design-system-enabled"
+          failure-message="Design system check must be performed after every component when design system is enabled."/>
+    <gate type="user-confirms" prompt="All components documented with Object IDs, design system checks complete?"/>
+
+    <output>Component registry complete — all Object IDs assigned, design system references updated where applicable.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 4 — Content and Languages                                     -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="4-content-languages" name="Specify all text content in all languages" step-file="steps-p/step-04-content-languages.md">
+    <instruction>
+      Ask the user what languages this page supports. Store as supported_languages array.
+    </instruction>
+    <instruction>
+      For every text element on the page (labels, buttons, headings, messages, placeholders,
+      error text — derived from the component list), ask the user to provide content in every
+      supported language. Primary language first, then each additional language.
+    </instruction>
+    <instruction>
+      Store multilingual_content keyed by element and language.
+      No text element may have content in only a subset of languages — full coverage is required.
+    </instruction>
+
+    <gate type="languages-defined" required="supported_languages-array-not-empty"
+          failure-message="Supported languages must be defined before collecting content. Ask the user for the language list first."/>
+    <gate type="multilingual-coverage" rule="every-text-element-has-content-in-every-language"
+          failure-message="Every text element must have content in ALL supported languages. Do not proceed with incomplete language coverage."/>
+    <gate type="user-confirms" prompt="All text content specified in all supported languages?"/>
+
+    <output>multilingual_content stored — all text elements captured in all supported languages.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 5 — Interactions                                              -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="5-interactions" name="Define interaction behaviors per component" step-file="steps-p/step-05-interactions.md">
+    <instruction>
+      For each interactive component in the registry (from step 3), ask the user what happens
+      when the user interacts with it. Cover: on click / on input / on focus,
+      immediate response, state changes, navigation (if applicable), data sent/received.
+    </instruction>
+    <instruction>
+      Store interaction_behavior keyed by Object ID. Do not generate behaviors without
+      user input — ask for each component individually.
+    </instruction>
+    <instruction>
+      Do not define visual states in this step — that is step 6.
+    </instruction>
+
+    <gate type="all-interactive-components-covered" rule="every-interactive-object-id-has-interaction-behavior"
+          failure-message="Every interactive component must have defined behaviors. Do not skip any."/>
+    <gate type="interaction-types-covered" rule="click-input-focus-navigation-data-considered-per-component"
+          failure-message="Consider all relevant interaction types for each component before moving on."/>
+    <gate type="user-confirms" prompt="All interaction behaviors defined for every interactive component?"/>
+
+    <output>interaction_behavior stored per Object ID — all interactive components covered.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 6 — States                                                    -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="6-states" name="Define page-level and component-level states" step-file="steps-p/step-06-states.md">
+    <instruction>
+      Define page-level states first. Ask the user to describe each situation:
+      default/loaded, empty (no data), loading (fetching), error (something went wrong),
+      success (after action completes). For each: when it occurs, what user sees, available actions.
+    </instruction>
+    <instruction>
+      For each component with multiple possible appearances, ask the user to define applicable states:
+      default, hover, active/pressed, focus, disabled, loading, error, success.
+      Only specify states that actually apply to each component.
+    </instruction>
+    <instruction>
+      Store page_states and component_states.
+      Do not define validation rules in this step — that is step 7.
+    </instruction>
+
+    <gate type="page-states-defined" required="default-state-minimum"
+          failure-message="At minimum, the default page state must be defined."/>
+    <gate type="component-states-defined" rule="multi-state-components-have-all-applicable-states"
+          failure-message="Components with multiple appearances must have all applicable states documented. Do not skip multi-state components."/>
+    <gate type="user-confirms" prompt="All page-level and component-level states defined?"/>
+
+    <output>page_states and component_states stored — all state variations documented.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 7 — Validation                                                -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="7-validation" name="Define validation rules and error messages" step-file="steps-p/step-07-validation.md">
+    <instruction>
+      Identify all fields and inputs that require validation. For each, ask:
+      - What makes it valid / invalid?
+      - Required or optional?
+      - Format rules and length limits?
+      - Custom rules?
+      - Validation timing: on blur, on submit, or real-time?
+    </instruction>
+    <instruction>
+      For each validation rule, define error messages in ALL supported languages.
+      Assign an error code (e.g., ERR_EMAIL_INVALID) to every message.
+    </instruction>
+    <instruction>
+      Store validation_rules and error_messages per field, with codes and translations.
+      Do not generate the specification document yet — that is step 9.
+    </instruction>
+
+    <check-if condition="page-has-input-fields-or-forms">
+      <then>
+        Proceed with full validation definition. Every input field must have rules and error messages.
+      </then>
+      <else>
+        No validated fields on this page. Store an empty validation_rules object and note
+        "No form inputs on this page" before proceeding to step 8.
+      </else>
+    </check-if>
+
+    <gate type="validation-rules-complete" rule="every-input-field-has-rules"
+          condition="page-has-input-fields"
+          failure-message="Every input field must have validation rules defined. Do not skip any field."/>
+    <gate type="error-messages-translated" rule="every-error-code-has-message-in-every-language"
+          condition="page-has-input-fields"
+          failure-message="Error messages must be provided in ALL supported languages. Incomplete translations block step 9."/>
+    <gate type="error-codes-assigned" rule="every-error-message-has-a-code"
+          condition="page-has-input-fields"
+          failure-message="Every error message must have an error code (e.g., ERR_EMAIL_INVALID)."/>
+    <gate type="user-confirms" prompt="Validation rules and error messages complete?"/>
+
+    <output>validation_rules and error_messages stored — all fields covered, all languages translated, all codes assigned.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 8 — Spacing and Typography                                    -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="8-spacing-typography" name="Define spacing objects and typography tokens" step-file="steps-p/step-08-spacing-typography.md">
+    <instruction>
+      Walk through adjacent section pairs top-to-bottom. For each pair, ask the user which
+      spacing token applies. Present the full table of gaps at once for efficiency.
+
+      Available tokens: zero, sm, md, lg, xl, 2xl, 3xl.
+      Zero-spacing is an intentional design choice — document it, never skip it.
+
+      Store spacing objects using naming convention:
+      - {page-slug}-v-space-{size} for vertical spacing
+      - {page-slug}-v-separator-{size} for lines/dividers with spacing
+
+      Also capture grid gaps for sections with repeated items (card grids, lists).
+    </instruction>
+    <instruction>
+      For each heading in the content (from step 4), define typography tokens.
+      Collect from the user: semantic tag (h1/h2/h3) and visual size per breakpoint
+      (mobile / tablet / desktop).
+
+      Available heading tokens: heading-xxs (14px), heading-xs (16px), heading-sm (18px),
+      heading-md (20px), heading-lg (24px), heading-xl (30px), heading-2xl (36px),
+      heading-3xl (44px), heading-4xl (56px).
+
+      Rule: use token names only — never arbitrary pixel values.
+      Rule: step up one token size per breakpoint (mobile → tablet → desktop) as a guide.
+
+      Store typography_tokens with Object ID, tag, and visual size per breakpoint.
+    </instruction>
+    <instruction>
+      Present the complete invisible layer to the user — spacing objects and typography tokens.
+      Ask if anything needs adjusting before generating the specification.
+    </instruction>
+
+    <gate type="spacing-complete" rule="every-section-boundary-has-spacing-object"
+          failure-message="Every adjacent section pair must have a spacing object. Including zero-spacing decisions."/>
+    <gate type="no-pixel-values" rule="only-token-names-used-in-spacing-and-typography"
+          failure-message="Only token names are allowed (zero, sm, md, lg, xl, 2xl, 3xl for spacing; heading-xxs through heading-4xl for typography). No pixel values."/>
+    <gate type="typography-complete" rule="every-heading-has-tag-and-responsive-token"
+          failure-message="Every heading must have a semantic tag and visual token for all three breakpoints."/>
+    <gate type="grid-gaps-documented" condition="page-has-card-grids-or-repeated-items"
+          failure-message="Grid gaps must be documented for sections containing repeated items (card grids, lists)."/>
+    <gate type="user-confirms" prompt="Spacing objects and typography tokens reviewed and approved?"/>
+
+    <output>spacing_objects and typography_tokens stored — every section boundary and heading documented with tokens.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 9 — Generate Specification                                    -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="9-generate-spec" name="Compile and save the complete page specification" step-file="steps-p/step-09-generate-spec.md">
+    <instruction>
+      Verify all data from steps 1-8 is present before generating:
+      page_basics, layout_sections, component registry with Object IDs, multilingual_content,
+      interaction_behavior, page_states, component_states, validation_rules, error_messages,
+      spacing_objects, typography_tokens.
+      If any section is missing, return to the relevant step to complete it first.
+    </instruction>
+    <instruction>
+      Generate the complete specification document using the template at:
+      templates/page-specification.template.md
+
+      Fill ALL sections with data from steps 1-8. Do not invent new formats —
+      the template defines the structure.
+    </instruction>
+    <instruction>
+      Run the validation script before saving:
+      wds-validate.js --page {current-page-path}
+      Review any errors or warnings reported. Fix issues in the relevant data sections
+      and re-run until validation passes.
+    </instruction>
+    <instruction>
+      Save the complete specification to:
+      {output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/{NN}.{step}-{page-slug}.md
+
+      Present the summary to the user: sections, components, languages, interactions, states,
+      validation rules, spacing objects, typography tokens — with counts.
+    </instruction>
+    <instruction>
+      Update the design log: append a row to the Design Loop Status table with status "specified":
+      | [scenario-slug] | [NN.step] | [page-name] | specified | [YYYY-MM-DD] |
+
+      Remove this page from the Current table. Do NOT skip this — the design log drives the
+      adaptive dashboard across sessions.
+    </instruction>
+
+    <gate type="all-data-sections-present" required="page_basics layout_sections components multilingual_content interaction_behavior page_states validation_rules spacing_objects typography_tokens"
+          failure-message="All data sections from steps 1-8 must be present before generating the specification. Return to incomplete steps."/>
+    <gate type="script-run" script="src/scripts/wds-validate.js" args="--page {current-page-path}"
+          failure-message="Validation script must pass before saving the specification. Fix reported issues and re-run."/>
+    <gate type="file-saved" path="{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/{NN}.{step}-{page-slug}.md"
+          failure-message="Specification file must be saved to the correct path before this step is complete."/>
+    <gate type="design-log-updated" rule="design-loop-status-row-appended-with-status-specified"
+          failure-message="Design log must be updated with 'specified' status before this step is complete. This is not optional."/>
+
+    <output>Complete page specification generated, validated, saved, and design log updated with 'specified' status.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- COMPLETION                                                         -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <completion>
+    <require step="all" failure-message="All 9 steps must be completed. The specification is not valid until step 9 passes validation and saves the file."/>
+    <output-file>{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/{NN}.{step}-{page-slug}.md</output-file>
+    <post-completion>
+      Return to the calling workflow's transition logic. If called from step-01-exploration.md (Discuss)
+      or workflow-suggest.md (Suggest), the calling step determines what comes next.
+      The design log status "specified" is the signal that this page is done.
+    </post-completion>
+  </completion>
+
+</workflow>

package/lib/bmad-extension/.claude-plugin/marketplace.json.template

@@ -39,7 +39,7 @@
     "roo-code",
     "kilocode"
   ],
-  "bmad_min_version": "6.6.0",
+  "bmad_min_version": "6.8.0",
   "plugins": [
     {
       "name": "ma-skills",

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -31,13 +31,13 @@
     "roo-code",
     "kilocode"
   ],
-  "bmad_min_version": "6.6.0",
+  "bmad_min_version": "6.8.0",
   "plugins": [
     {
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.12.2",
+      "version": "3.13.0",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad.js

@@ -1,7 +1,8 @@
 const fs = require('fs-extra');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
+const { pathToFileURL } = require('url');
 const chalk = require('chalk');
 const yaml = require('yaml');
 const jsYaml = require('js-yaml');
@@ -471,7 +472,7 @@ const BMAD_MODULE_DESCRIPTIONS = Object.freeze({
     cis: 'Creative Intelligence Suite — innovation and ideation toolkit',
     gds: 'Game Dev Studio — game development workflows',
     tea: 'Test Architecture Enterprise — Test Architect (Murat) + 9 testarch workflows',
-    wds: 'Web Dev Studio — retired upstream',
+    wds: 'Whiteport Design Studio — strategic UX and design-first planning',
 });
 
 /**
@@ -481,7 +482,9 @@ const BMAD_MODULE_DESCRIPTIONS = Object.freeze({
  * the optional external modules (bmb, cis, gds, tea, wds, ...).
  *
  * Each entry carries a `retired` flag so the caller can hide modules that
- * have been retired upstream (e.g. wds).
+ * have been retired upstream (driven by the manifest's `retiredUpstream`
+ * marker; at v6.8.0 the bundled set — tea, bmb, cis, gds, wds — are all
+ * active `type: bmad-org` clones, so none are flagged).
  *
  * If the cache manifest is missing or unreadable, falls back to a list
  * containing only `bmm` — that's the minimum a successful install needs.
@@ -1472,10 +1475,42 @@ async function deployMethodology(projectRoot = process.cwd(), force = false) {
     console.log(chalk.gray('  Tip: Use /open-presentation to open the slides (install via npx ma-agents install open-presentation)'));
 }
 
+/**
+ * Detect whether a `.clinerules/workflows/*.md` file is a ma-agents-generated
+ * Cline workflow wrapper (as opposed to a user-authored file that happens to
+ * live in the same directory).
+ *
+ * Reconciliation (Story 27.4) deletes stale wrappers, so the matcher must be
+ * conservative: it returns `true` ONLY for the exact shape this function emits.
+ * Every generated wrapper contains a line that points the reader back into the
+ * backing skill via a `.cline/skills/<name>/` reference (either `SKILL.md` or
+ * `workflow.md`). User files under `.clinerules/` will not carry that marker,
+ * so they are never mistaken for wrappers and never deleted.
+ *
+ * @param {string} content - Raw UTF-8 contents of the candidate `.md` file.
+ * @returns {boolean} `true` if the content matches the generated-wrapper shape.
+ */
+function isGeneratedClineWrapper(content) {
+    if (typeof content !== 'string' || content.length === 0) return false;
+    // The generated-wrapper fingerprint: a body line that instructs the reader
+    // to read a file under `.cline/skills/<name>/` (SKILL.md or workflow.md).
+    // Matches forward-slashed paths only — that is exactly what we emit.
+    return /\.cline\/skills\/[^/\s`]+\/(?:SKILL|workflow)\.md/.test(content);
+}
+
 /**
  * Generate Cline workflow wrappers for all BMAD skills installed to .cline/skills/.
  * Creates .clinerules/workflows/<skill-name>.md for each installed skill so they
  * can be invoked via / commands in Cline chat.
+ *
+ * Reconciliation (Story 27.4): after (re)generating wrappers for all current
+ * skills, any stale wrapper under `.clinerules/workflows/` whose backing
+ * `.cline/skills/<name>/` directory no longer exists is removed. This keeps
+ * `/`-invocation in Cline from offering workflows for skills BMAD renamed away
+ * or retired. Deletion is scoped strictly to ma-agents-generated wrapper files
+ * (see {@link isGeneratedClineWrapper}); user-authored files elsewhere under
+ * `.clinerules/` are never touched, and the operation is idempotent.
+ *
  * No-op when 'cline' is not in the selected tools list.
  */
 async function deployClineWorkflows(projectRoot, tools = []) {
@@ -1502,6 +1537,10 @@ async function deployClineWorkflows(projectRoot, tools = []) {
     const entries = await fs.readdir(clineSkillsDir, { withFileTypes: true });
     const skillDirs = entries.filter(e => e.isDirectory());
 
+    // Live skill-name set: every `.cline/skills/<name>/` that backs a wrapper
+    // (i.e. contains a SKILL.md). Used below to reconcile stale wrappers.
+    const liveSkillNames = new Set();
+
     let generated = 0;
     for (const entry of skillDirs) {
         const skillName = entry.name;
@@ -1510,6 +1549,7 @@ async function deployClineWorkflows(projectRoot, tools = []) {
         const workflowMdPath = path.join(skillDir, 'workflow.md');
 
         if (!(await fs.pathExists(skillMdPath))) continue;
+        liveSkillNames.add(skillName);
 
         const skillMdContent = await fs.readFile(skillMdPath, 'utf8');
         let displayName = skillName.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
@@ -1546,10 +1586,47 @@ async function deployClineWorkflows(projectRoot, tools = []) {
         generated++;
     }
 
+    // Reconciliation (Story 27.4): remove stale wrappers whose backing skill
+    // dir no longer exists. Scope is strictly the generated-wrapper `.md` files
+    // directly inside `workflows/` — subdirectories and non-wrapper user files
+    // are left untouched.
+    let removed = 0;
+    const workflowEntries = await fs.readdir(workflowsDir, { withFileTypes: true });
+    for (const wf of workflowEntries) {
+        // Only top-level `.md` files are candidate wrappers. Skip directories
+        // and any non-markdown file outright.
+        if (!wf.isFile()) continue;
+        if (!wf.name.endsWith('.md')) continue;
+
+        const wrapperName = wf.name.slice(0, -'.md'.length);
+        // A wrapper whose name is still in the live set is current — keep it.
+        // (It was just (re)written above.)
+        if (liveSkillNames.has(wrapperName)) continue;
+
+        // Name is not backed by a live skill. Before deleting, confirm the file
+        // actually matches the ma-agents generated-wrapper shape so we never
+        // remove a user-authored `.md` that happens to share a stale name.
+        const wrapperPath = path.join(workflowsDir, wf.name);
+        let wrapperContent;
+        try {
+            wrapperContent = await fs.readFile(wrapperPath, 'utf8');
+        } catch {
+            // Unreadable (e.g. vanished mid-run) — nothing to reconcile.
+            continue;
+        }
+        if (!isGeneratedClineWrapper(wrapperContent)) continue;
+
+        await fs.remove(wrapperPath);
+        removed++;
+    }
+
     if (generated > 0) {
         console.log(chalk.green(`  ✓ Generated ${generated} Cline workflow wrappers in .clinerules/workflows/`));
         console.log(chalk.gray('  Tip: In Cline, type / to browse and invoke BMAD skills'));
     }
+    if (removed > 0) {
+        console.log(chalk.green(`  ✓ Removed ${removed} stale Cline workflow wrapper${removed === 1 ? '' : 's'} (backing skill no longer present)`));
+    }
 }
 
 /**
@@ -1793,7 +1870,7 @@ function ensureCanonicalConfigLocation(projectRoot) {
 
 // ── Migration constants ─────────────────────────────────────────────────────
 
-const BMAD_TARGET_VERSION = '6.6.0';
+const BMAD_TARGET_VERSION = '6.8.0';
 const BMAD_MIGRATION_THRESHOLD = '6.2.0'; // versions below this need migration
 const BACKUP_DIR_NAME = '.backup-pre-migration';
 
@@ -2733,10 +2810,15 @@ function restoreGitDir(moduleDir) {
     }
     fs.renameSync(preserved, gitDir);
 
-    // Point origin at the local directory so `git fetch origin` succeeds offline
+    // Point origin at the local directory so `git fetch origin` succeeds offline.
+    // Use pathToFileURL so a Windows absolute path becomes a well-formed
+    // `file:///C:/...` URL (three slashes) rather than `file://C:/...`, and so
+    // paths containing spaces or other reserved characters are percent-encoded.
+    // execFileSync (arg array) avoids shell interpolation — matching the rest of
+    // the codebase's git calls (see scripts/build-bmad-cache.js).
     try {
-        const localUrl = 'file://' + moduleDir.replace(/\\/g, '/');
-        execSync(`git remote set-url origin "${localUrl}"`, {
+        const localUrl = pathToFileURL(moduleDir).href;
+        execFileSync('git', ['remote', 'set-url', 'origin', localUrl], {
             cwd: moduleDir,
             stdio: 'pipe'
         });
@@ -2754,6 +2836,8 @@ module.exports = {
     prePopulateBmadCache,
     deployMethodology,
     deployClineWorkflows,
+    // Story 27.4 — exported for unit tests of stale-wrapper reconciliation
+    isGeneratedClineWrapper,
     // Story 22.7 — canonical config (_bmad/bmm/config.yaml) helpers
     readCanonicalBmadConfig,
     ensureCanonicalConfigLocation,

package/lib/installer.js

@@ -12,6 +12,7 @@ const MANIFEST_VERSION = '1.2.0';
 const MA_AGENTS_SOURCE = 'ma-agents';
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'project-context.template.md');
 const UNIVERSAL_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-universal.template.md');
+const GIT_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-git.template.md');
 const ONPREM_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-onprem.template.md');
 const CLINERULES_TEMPLATE_PATH = path.join(__dirname, 'templates', 'clinerules.template.md');
 const EXTRA_TEMPLATE_DIR = path.join(__dirname, 'templates');
@@ -133,19 +134,39 @@ function composeInstructionBlock({ profile, projectRoot } = {}) {
     );
   }
 
+  // Story 26.1 — the git workflow guardrail block is appended to EVERY profile
+  // (standard and on-prem), so this read must be as robust as the universal
+  // read above. Any failure to load a non-empty git template surfaces as a
+  // clear, path-identifying error — the guardrails must never silently vanish.
+  let git;
+  try {
+    git = fs.readFileSync(GIT_INSTRUCTION_TEMPLATE_PATH, 'utf-8');
+  } catch (err) {
+    throw new Error(
+      `git instruction template not found or unreadable at ${GIT_INSTRUCTION_TEMPLATE_PATH} — ma-agents installation may be corrupted: ${err.message}`
+    );
+  }
+  if (git.trim() === '') {
+    throw new Error(
+      `git instruction template at ${GIT_INSTRUCTION_TEMPLATE_PATH} is empty — ma-agents installation may be corrupted`
+    );
+  }
+
+  // Compose in the exact order universal + git (+ on-prem). Each piece is
+  // trailing-whitespace-normalized and joined by exactly one blank line so that
+  // first-insert and in-place-replace produce byte-identical marker content
+  // (FR176 / NFR46 idempotency).
+  let composed = universal.replace(/\s+$/, '') + '\n\n' + git.replace(/\s+$/, '');
+
   if (profile === 'on-prem') {
     if (!fs.existsSync(ONPREM_INSTRUCTION_TEMPLATE_PATH)) {
       throw new Error('on-prem profile selected but instruction-block-onprem.template.md is missing');
     }
     const onprem = fs.readFileSync(ONPREM_INSTRUCTION_TEMPLATE_PATH, 'utf-8');
-    // Normalize both pieces so the concatenation has exactly one blank line between them
-    // and no trailing whitespace — feeds NFR46 byte-identity.
-    return universal.replace(/\s+$/, '') + '\n\n' + onprem.replace(/\s+$/, '') + '\n';
+    composed += '\n\n' + onprem.replace(/\s+$/, '');
   }
 
-  // Normalize trailing whitespace so first-insert and in-place-replace both
-  // produce byte-identical content inside the markers (NFR46, AC #6).
-  return universal.replace(/\s+$/, '') + '\n';
+  return composed + '\n';
 }
 
 /**
@@ -2000,6 +2021,7 @@ module.exports = {
   buildBackupFilename,
   formatBackupTimestamp,
   UNIVERSAL_INSTRUCTION_TEMPLATE_PATH,
+  GIT_INSTRUCTION_TEMPLATE_PATH,
   ONPREM_INSTRUCTION_TEMPLATE_PATH,
   // Story 21.4 — AGENTS.md template, markdown-markers merger, extraInstructionTemplates processor.
   // Story 21.3 (rebased) — yaml-customModes merger dispatch is integrated into stampExtraInstructionTemplates.