gsd-antigravity-kit 1.25.2 → 1.27.2

package/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Antigravity Compatible](https://img.shields.io/badge/Antigravity-Compatible-purple.svg?logo=google&logoColor=white)](https://github.com/google-deepmind/antigravity)
 [![NPM Version](https://img.shields.io/npm/v/gsd-antigravity-kit.svg?logo=npm)](https://www.npmjs.com/package/gsd-antigravity-kit)
-[![Release Version](https://img.shields.io/badge/Release-v1.25.2-blue?style=flat-square)](https://github.com/dturkuler/GSD-Antigravity/releases/latest)
+[![Release Version](https://img.shields.io/badge/Release-v1.27.2-blue?style=flat-square)](https://github.com/dturkuler/GSD-Antigravity/releases/latest)
 [![GSD Version](https://img.shields.io/badge/GSD-v1.27.0-orange?style=flat-square)](https://github.com/glittercowboy/get-shit-done)
 
 **GSD-Antigravity Kit** is the official bootstrapping and management utility for the [Get Shit Done (GSD)](https://github.com/glittercowboy/get-shit-done) protocol within the Antigravity AI framework. It serves as a high-performance **Installer** and **Skill Manager** that provision, optimizes, and maintains GSD skills in your AG environment.
@@ -45,6 +45,8 @@ Installation is handled via `npx` to automatically provision your current projec
 # In your project root:
 npx gsd-antigravity-kit
 ```
+> [!NOTE]
+> The installer is now **interactive**. It will check for existing skills, offer to clean up old folders, and let you choose which skills (`gsd` or `gsd-converter`) to install.
 
 ### 2️⃣ Initialize the GSD Engine
 Run the converter script provided by the kit to fetch and package the GSD protocol:

package/bin/install.js

@@ -2,37 +2,98 @@
 
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
 const { execSync } = require('child_process');
 
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+});
+
+const ask = (query) => new Promise((resolve) => rl.question(query, (ans) => resolve(ans.toLowerCase().trim())));
+
 async function install() {
     const targetDir = process.cwd();
-    // Location of the .agent folder relative to this script in the package
     const sourceAgentDir = path.join(__dirname, '..', '.agent');
-    const targetAgentDir = path.join(targetDir, '.agent');
+    const skillsSourceDir = path.join(sourceAgentDir, 'skills');
+    
+    // Skills to check/install
+    const skillNames = ['gsd', 'gsd-converter'];
+    const targetSkillsDir = path.join(targetDir, '.agent', 'skills');
 
-    console.log('🌌 Initializing GSD-Antigravity Skill System...');
+    console.log('\n🌌 GSD-Antigravity Skill System Installer\n');
 
     try {
-        // 1. Copy .agent folder
-        if (fs.existsSync(sourceAgentDir)) {
-            console.log(`📦 Copying .agent skills to ${targetDir}...`);
+        // 1. Check for existing skills
+        const existing = [];
+        for (const name of skillNames) {
+            if (fs.existsSync(path.join(targetSkillsDir, name))) {
+                existing.push(name);
+            }
+        }
 
-            // We use a simple recursive copy strategy
-            copyFolderSync(sourceAgentDir, targetAgentDir);
-            console.log('✅ .agent folder installed successfully.');
-        } else {
-            console.error('❌ Error: Could not find .agent folder in the package.');
-            process.exit(1);
+        if (existing.length > 0) {
+            console.log(`⚠️  Detected existing skills in .agent/skills/: ${existing.join(', ')}`);
+            const confirmRemove = await ask(`Do you want to REMOVE existing skills and perform a fresh install? (y/n): `);
+            if (confirmRemove === 'y') {
+                for (const name of existing) {
+                    const p = path.join(targetSkillsDir, name);
+                    console.log(`  🗑️  Removing ${name}...`);
+                    fs.rmSync(p, { recursive: true, force: true });
+                }
+            } else {
+                console.log('  ⏩ Skipping removal. New files will be merged/overwritten.');
+            }
+        }
+
+        // 2. Interactive Installation Selection
+        const installGsd = await ask(`Install GSD skill? (y/n) [default: y]: `);
+        const installConverter = await ask(`Install GSD-Converter skill? (y/n) [default: y]: `);
+
+        const selection = {
+            'gsd': installGsd !== 'n',
+            'gsd-converter': installConverter !== 'n'
+        };
+
+        // 3. Perform Installation
+        if (!fs.existsSync(targetSkillsDir)) {
+            fs.mkdirSync(targetSkillsDir, { recursive: true });
+        }
+
+        // Also copy rules if they exist
+        const sourceRulesDir = path.join(sourceAgentDir, 'rules');
+        const targetRulesDir = path.join(targetDir, '.agent', 'rules');
+        if (fs.existsSync(sourceRulesDir)) {
+            copyFolderSync(sourceRulesDir, targetRulesDir);
         }
 
-        // 2. Offer to run the converter
-        console.log('\n✨ GSD-Antigravity is now in your project.');
-        console.log('To initialize the GSD engine, run:');
-        console.log('  py .agent/skills/gsd-converter/scripts/convert.py gsd\n');
+        let installedCount = 0;
+        for (const [name, shouldInstall] of Object.entries(selection)) {
+            if (shouldInstall) {
+                const src = path.join(skillsSourceDir, name);
+                const tgt = path.join(targetSkillsDir, name);
+                if (fs.existsSync(src)) {
+                    console.log(`📦 Installing ${name}...`);
+                    copyFolderSync(src, tgt);
+                    installedCount++;
+                }
+            }
+        }
+
+        if (installedCount > 0) {
+            console.log('\n✅ Installation completed successfully.');
+            if (selection['gsd-converter']) {
+                console.log('\n✨ To initialize the GSD engine, run:');
+                console.log('  py .agent/skills/gsd-converter/scripts/convert.py gsd\n');
+            }
+        } else {
+            console.log('\nℹ️  No skills were selected for installation.');
+        }
 
     } catch (err) {
-        console.error('❌ Installation failed:', err.message);
-        process.exit(1);
+        console.error('\n❌ Installation failed:', err.message);
+    } finally {
+        rl.close();
     }
 }
 
@@ -41,11 +102,13 @@ function copyFolderSync(from, to) {
         fs.mkdirSync(to, { recursive: true });
     }
     fs.readdirSync(from).forEach(element => {
-        const stat = fs.lstatSync(path.join(from, element));
+        const srcPath = path.join(from, element);
+        const tgtPath = path.join(to, element);
+        const stat = fs.lstatSync(srcPath);
         if (stat.isFile()) {
-            fs.copyFileSync(path.join(from, element), path.join(to, element));
+            fs.copyFileSync(srcPath, tgtPath);
         } else if (stat.isDirectory()) {
-            copyFolderSync(path.join(from, element), path.join(to, element));
+            copyFolderSync(srcPath, tgtPath);
         }
     });
 }

package/package.json

@@ -1,8 +1,12 @@
 {
     "name": "gsd-antigravity-kit",
-    "version": "1.25.2",
+    "version": "1.27.2",
     "description": "Installer for GSD-Antigravity skills",
     "main": "index.js",
+    "files": [
+        "bin/",
+        ".agent/"
+    ],
     "bin": {
         "gsd-antigravity-kit": "bin/install.js"
     },

package/CHANGELOG.md

@@ -1,150 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.25.2] - 2026-03-21
-
-### Added
-- **GSD Sync 1.27.0**: Synchronized with the latest GSD core (v1.27.0), featuring enhanced initialization signatures and improved state tracking.
-
-### Fixed
-- **Path Resolution**: Patched `gsd-converter` to robustly handle absolute path prefixes (e.g., `C:/projects/...`) during migration, ensuring valid skill-relative references in all command files.
-- **Branding Consistency**: Reinforced "Antigravity" rebranding across all migrated GSD references, eliminating legacy `.claude` mentions in command execution contexts.
-
-## [1.25.1] - 2026-03-16
-
-### Added
-- **GSD Sync 1.25.1**: Full synchronization with the latest GSD core, featuring optimized model profiles and enhanced state consistency.
-- **Selective Inclusion Engine**: Injected `parseIncludeFlag`, `applyIncludes`, and `buildPhaseBase` into the core CLI, enabling granular context management via the `--include` flag.
-- **Artifact Discovery**: Integrated `discoverPhaseArtifacts` for automated detection of hierarchical project files, improving context gathering automation.
-
-### Changed
-- **Skill Optimization**: Applied advanced refactoring via `gsd-converter`, reducing script overhead through 2-space indentation and condensed headers.
-- **Improved Portability**: Enhanced regex-based path mapping for even more robust environment isolation in Antigravity.
-
-## [1.24.0] - 2026-03-15
-
-### Added
-- **Major GSD Sync**: Synchronized with GSD `1.24.0`, bringing full support for the new modular engine and enhanced state management workflows.
-- **Improved Phase Operations**: Added native support for `phase insert`, `phase remove`, and `phase-plan-index` through the modular CLI.
-- **New Init Workflows**: Expanded `init` command to support `milestone-op`, `phase-op`, and `roadmap-op` for safer state transitions.
-
-### Changed
-- **Modular DRY Refactoring**: The monolithic `gsd-tools.cjs` has been completely refactored into a DRY architecture. Core logic is now modularized within `bin/lib/*.cjs`, significantly improving maintainability and reducing the primary script overhead.
-- **Automated Help Generation**: `gsd-converter` now automatically populates `help-manifest.json` with detailed subcommand metadata, enabling rich interactive help via the `--help` flag.
-
-## [1.22.6] - 2026-03-13
-
-### Added
-- **Help System Integration**: `gsd-converter` now generates a `help-manifest.json` and injects a dynamic help system into `gsd-tools.cjs`. Users can run `node gsd-tools.cjs --help <command>` for detailed subcommand usage.
-- **Nyquist Validation**: Retroactive validation is now supported via `gsd:validate-phase`. `nyquist_validation` is now enabled by default in new project templates.
-
-### Changed
-- **Config Directory Discovery**: Improved robustness of config directory detection (Antigravity/Gemini/OpenCode) across all hooks, now respecting `CLAUDE_CONFIG_DIR`.
-- **Semantic Configuration**: Migrated "depth" terminology to "granularity" (coarse/standard/fine) for better alignment with GSD specifications.
-- **Git Ignore Handling**: Updated `isGitIgnored` to use `--no-index`, ensuring correct behavior for files tracked before being ignored.
-
-### Fixed
-- **Windows UTF-8 Stability**: Enforced UTF-8 encoding for Python and Node.js subprocesses on Windows to eliminate character mangling.
-- **Multi-word Commit Messages**: Fixed the `commit` command in `gsd-tools.cjs` to correctly capture multi-word messages across different shell environments.
-- **Hook Reliability**: Added 3-second stdin timeout guards to `gsd-statusline.js` and `gsd-context-monitor.js` to prevent hanging on Windows/Git Bash.
-
-## [1.22.5] - 2026-03-09
-
-### Changed
-- **Maintenance**: General synchronization and maintenance release.
-
-## [1.22.4] - 2026-03-03
-
-### Added
-- **Resource Migration**: Updated `gsd-converter` to explicitly migrate the `mapping.md` documentation into the target `gsd` skill for better user reference.
-
-### Fixed
-- **Terminal & Encoding Polish**: Resolved character mangling (`✅`) and output overlap in `gsd-converter` by enforcing UTF-8 and improving stdout flushing.
-- **Robust Path Refactoring**: Improved regex-based path refactoring to handle Windows backslashes more safely, preventing potential `undefined` path segments.
-- **GSD Skill Update**: Synchronized with GSD 1.22.4, ensuring full Antigravity rebranding and optimization across all migrated files.
-
-## [1.22.3] - 2026-03-03
-
-### Fixed
-- **CLI Path Resolution**: Added explicit warnings across `SKILL.md`, `gsd-tools.md`, and the `gsd-tools.cjs` header that `gsd-tools` is NOT globally installed. AI agents must invoke it as `node .agent/skills/gsd/bin/gsd-tools.cjs <command>` — never as bare `gsd-tools`.
-- **Converter Template**: Updated both the converter asset (`gsd-tools.md` template) and the `gsd_skill_template.md` to include the CLI invocation warning, ensuring future conversions also receive the fix.
-
-## [1.22.2] - 2026-03-03
-
-### Fixed
-- **Optimizer Import Bug**: Fixed a bug where the `parseIncludeFlag` import injection in `optimize-gsd-tools.cjs` was incorrectly failing its condition check, resulting in `parseIncludeFlag` not being imported in `gsd-tools.cjs`.
-
-## [1.22.1] - 2026-03-03
-
-### Changed
-- **GSD Skill Update**: Synchronized with GSD 1.22.1, ensuring full Antigravity rebranding and optimization across all migrated files.
-
-### Fixed
-- **Optimizer Path Bug**: Fixed a critical bug in `gsd-converter's` `convert.py` where it passed the file path of `gsd-tools.cjs` instead of the `bin` directory to the optimizer script, causing directory-level processing to fail.
-
-## [1.22.0] - 2026-03-01
-
-### Added
-- **Smart Inclusion Engine**:
-  - Injected `parseIncludeFlag()`, `applyIncludes()`, and `buildPhaseBase()` into `gsd-tools.cjs` to support the `--include` flag for granular context management.
-  - Added `MODEL_PROFILES` for optimized model selection.
-- **Artifact Discovery**:
-  - Automated phase document lookup via `discoverPhaseArtifacts()` in the core engine.
-
-### Changed
-- **GSD Skill Update**: Synchronized with GSD 1.22.0, ensuring full Antigravity rebranding and optimization across all migrated files.
-- **Performance Optimization**: 
-  - Refactored `gsd-tools.cjs` with 2-space indentation and condensed headers, reducing script size by ~25KB.
-  - Improved regex-based path refactoring for more robust environment isolation.
-
-## [1.21.1] - 2026-02-27
-## [1.21.0] - 2026-02-27
-
-### Added
-- **Dynamic `gsd-tools` Discovery**:
-  - `gsd-converter` now dynamically parses `gsd-tools.cjs` comments to generate up-to-date Antigravity command documentation.
-  - Automates the inclusion of new GSD commands without manual script updates.
-- **Enhanced Path Refactoring**:
-  - Implemented robust regex-based path mapping to handle all `.claude` and shell-relative path variants (`@./.claude`, `~/.claude`, etc.).
-  - Ensures a 100% self-contained skill environment in Antigravity.
-- **Automatic Cleanup**:
-  - The converter now automatically purges legacy `.bak` and temporary files during the migration process.
-
-### Changed
-- **Release Manager Sync**: Updated the release workflow to enforce GSD synchronization and dynamic help verification before tagging.
-- **GSD Skill Architecture**: Refactored the internal skill structure to mirror GSD 1.21.0's modular `hooks/` and `bin/lib/` organization.
-
-## [1.0.2] - 2026-02-20
-
-### Added
-- **`gsd-converter` Automation**:
-  - Now automatically refactors and enhances `gsd-tools.cjs` during the migration process.
-- **`gsd-tools.cjs` Enhancements** (Injected via Converter):
-  - **Selective Inclusion Engine**: Injected `parseIncludeFlag`, `applyIncludes`, and `buildPhaseBase` to support the new `--include` CLI flag.
-  - **Contextual Awareness**: Added `discoverPhaseArtifacts` for automated detection of hierarchical project files.
-  - **Persona-Based Model Profiles**: Implemented `MODEL_PROFILES` mapping to optimize AI model selection.
-
-## [1.0.1] - 2026-02-20
-
-### Added
-- **Core Skill System**: Established the `.agent/skills/` directory structure for modular Antigravity agents.
-- **`gsd-converter` Skill**: Implemented a zero-config automation script to migrate legacy GSD installations into the portable Antigravity Skill format.
-- **Release Manager Skill**: Orchestrated a multi-phase release workflow for Node.js/NPM, including GitHub CLI (`gh`) integration and NPM publication logic.
-- **GH CLI Integration**: Bundled `gh.exe` within the release-manager skill folder for portable environment support.
-- **NPX Distribution**: Added `bin/install.js` to enable seamless installation via `npx gsd-antigravity-kit`.
-- **Project Structure**: Established standard configurations including `.gitignore`, `package.json`, and initial project documentation.
-
-### Changed
-- **Rebranding**: Completed full migration from "Claude" to "Antigravity" terminology across all scripts and prompts.
-- **Script Optimization**: Refactored core GSD tool scripts to reduce complexity and file size without sacrificing functionality.
-
-### Documentation
-- Created `README.md` with the new "GSD Cycle" philosophy (Plan, Execute, Verify).
-- Initialized `CHANGELOG.md` to track project evolution.
-- Created `docs/DEV_KNOWLEDGEBASE.md` for technical Root Cause Analysis (RCA).
-
-**Git range:** `1a7e252` → `HEAD`

package/CONTRIBUTING.md

@@ -1,30 +0,0 @@
-# Contributing to GSD-Antigravity
-
-Thank you for your interest in contributing to GSD-Antigravity! We welcome contributions that improve the reliability, efficiency, and extensibility of our GSD system.
-
-## 🚀 Getting Started
-
-1. **Fork the repository** and create your branch from `main`.
-2. **Follow the Skill Spec**: All changes to skills must adhere to the Antigravity Skill specification found in [.agent/skills/skill-developer/SKILL.md](.agent/skills/skill-developer/SKILL.md).
-3. **Draft your changes**: Whether it's a new command, an agent prompt improvement, or a bug fix in the converter.
-
-## 🛠️ Development Guidelines
-
-- **Maintain Hierarchy**: Ensure any new commands fit into the Plan -> Execute -> Verify workflow.
-- **Spec-Driven**: Use the provided templates in `assets/templates` when creating new project artifacts.
-- **Rebranding**: If adding new commands, ensure they follow the `gsd:` prefix nomenclature.
-- **Testing**: Before submitting a PR, verify your skill by running the `gsd-converter` script to ensure it packages correctly.
-
-## 📋 Pull Request Process
-
-1. Update the README.md with details of changes to the interface, if applicable.
-2. Ensure any new dependencies are clearly documented.
-3. Your PR will be reviewed by the maintainers for compliance with GSD core principles.
-
-## 💬 Community
-
-Join our Discord or open an issue for architectural discussions before making major changes.
-
----
-
-*Happy Coding!*

package/docs/DEV_KNOWLEDGEBASE.md

@@ -1,125 +0,0 @@
-# Developer Knowledgebase (RCA)
-
-This document tracks technical Root Cause Analysis (RCA) for bug fixes in the **gsd-antigravity-kit** project. Its purpose is to prevent regression and document technical debt resolutions.
-
----
-
-## Technical Analysis History
-
-### v1.25.2 (2026-03-21)
-*   **Context:** `gsd-converter` (`convert.py`) and GSD Skill (v1.27.0)
-*   **Issue:** Broken path references in migrated GSD commands; legacy branding in execution contexts; and outdated GSD v1.26.0 core.
-*   **Root Cause Analysis:** 
-    - The GSD installer used absolute paths (e.g., `C:/projects/.../.claude/...`) in its generated command files.
-    - The `convert.py` regexes (`r'@\.?/?\.claude/...'`) were too strict, only matching relative versions starting with `@.claude` or `@/.claude`.
-    - When an absolute path was encountered (e.g., `@C:/projects/GSD-Antigravity/.claude/...`), the regex failed to match the `@` at the start of the sequence, but a subsequent less-strict rule matching `\.claude/...` consumed the leading slash of the absolute path, resulting in merged strings like `GSD-Antigravityreferences/...`.
-*   **How it was fixed:**
-    - **Robust Regex Pathing**: Updated `convert.py` to use non-greedy wildcards (`r'@.*?\.claude/...'`) to capture any characters (including absolute drive paths) between `@` and `.claude/`. This ensures they are replaced wholesale with skill-relative `@references/...` or `@assets/...` tags.
-    - **GSD v1.27.0 Sync**: Upgraded the core GSD installation, bringing new `init` workflow signatures (`cmdInitExecutePhase`, `cmdInitPlanPhase`, `cmdInitProgress`) for improved state tracking.
-    - **Enhanced Branding**: Reinforced the Antigravity rebranding regexes to ensure no `.claude` or `Claude` mentions remain in the final skill artifacts.
-
-### v1.25.1 (2026-03-16)
-*   **Context:** `gsd-tools.cjs` (Selective Inclusion and Artifact Discovery)
-*   **Issue:** Lack of standardized context slicing and automated artifact traversal in the core GSD engine, leading to inconsistent context gathering across different subagents.
-*   **Root Cause Analysis:** 
-    - The core engine was missing a unified way to handle partial context loading, forcing agents to either load the entire state or manually parse it.
-    - Artifact discovery relied on static paths which didn't always account for deeply nested or dynamically named phase directories.
-*   **How it was fixed:**
-    - **Smart Inclusions**: Injected `parseIncludeFlag`, `applyIncludes`, and `buildPhaseBase` into `gsd-tools.cjs`. This allows the `--include` flag to dynamically filter state/roadmap data, significantly reducing token overhead for long-running workflows.
-    - **Automated Discovery**: Integrated `discoverPhaseArtifacts()` to automatically traverse the `.planning/` hierarchy, ensuring that all relevant requirements, plans, and implementation notes are available to the agent without manual specification.
-    - **Model Profile Injection**: Injected a centralized `MODEL_PROFILES` object to ensure consistent model selection (e.g., using better models for planning and cheaper ones for simple tasks) across the entire GSD toolchain.
-
-### v1.24.0 (2026-03-15)
-*   **Context:** `gsd-tools.cjs` (Engine Modernization)
-*   **Issue:** Technical debt in the core engine; increasing complexity of the monolithic `gsd-tools.cjs` script; and lack of granular control over phase/milestone state transitions.
-*   **Root Cause Analysis:** 
-    - The monolithic design of `gsd-tools.cjs` was becoming difficult to audit and extend, leading to duplication of logic across commands.
-    - Previous `init` workflows were too coarse-grained, making it difficult to perform atomic state updates for complex roadmap changes.
-*   **How it was fixed:**
-    - **Modularization (DRY)**: Refactored `gsd-tools.cjs` to delegate all command implementation to a dedicated library in `bin/lib/`. This reduced the main router file size and centralized error handling and state management.
-    - **Internal Library**: Created specialized modules: `phase.cjs` for roadmap manipulation, `init.cjs` for workflow bootstrapping, and `verify.cjs` for project health checks.
-    - **Enhanced Init Router**: Added multiple specialized init workflows (`milestone-op`, `phase-op`, `roadmap-op`) to provide agents with precise control over project structure modifications.
-
-### v1.22.6 (2026-03-13)
-*   **Context:** `gsd-tools.cjs` and `gsd-converter`
-*   **Issue:** Missing detailed CLI help for subcommands; character encoding issues on Windows; hung terminal processes; and deprecated configuration keys.
-*   **Root Cause Analysis:** 
-    - The `gsd-tools.cjs` lacked an internal help system, relying on external documentation that wasn't always accessible to sub-agents.
-    - Windows `cp1252` encoding caused mangling of Unicode status markers in Python and Node.js output.
-    - Synchronous blocking on `stdin` in hooks caused terminal hangs in environments where `stdin` didn't close properly (e.g., Git Bash on Windows).
-    - Hardcoded GSD home paths didn't account for newer "Antigravity" or "Gemini" branding in local configuration directories.
-*   **How it was fixed:**
-    - **Help Manifest**: Implemented a dynamic `help-manifest.json` generation in `convert.py` and a `--help` interceptor in `gsd-tools.cjs`.
-    - **Encoding Stability**: Enforced UTF-8 for `stdout`/`stderr` in `convert.py` and passed `encoding: 'utf-8'` to `execSync`/`spawn` calls.
-    - **Timeout Guards**: Added 3-second `setTimeout` exits for `gsd-statusline.js` and `gsd-context-monitor.js` to prevent deadlock if `stdin` stays open.
-    - **Branding-Neutral Paths**: Refactored config directory lookup to check for `.antigravity`, `.gemini`, and `.opencode`, supporting the `CLAUDE_CONFIG_DIR` environment variable.
-    - **Semantic Migration**: Automatically migrates the `depth` configuration key to the more descriptive `granularity`.
-
-### v1.22.4 (2026-03-03)
-*   **Context:** `gsd-converter` (`convert.py` and `optimize-gsd-tools.cjs`)
-*   **Issue:** Terminal output characters mangled (`✅`) and version summary overlapped with optimizer logs.
-*   **Root Cause Analysis:** 
-    - Windows terminal encoding defaults (CP1252/437) didn't support UTF-8 checkmarks.
-    - Race condition between `npx` status-line updates (`\r`) and Python `print()` statements.
-    - Subprocess output from `node` was being captured without explicit encoding, leading to character mapping errors.
-*   **How it was fixed:**
-    - **UTF-8 Enforcement**: Added `sys.stdout.reconfigure(encoding='utf-8')` to the converter script.
-    - **Logging Cleanliness**: Improved subprocess output handling with explicit newlines and `sys.stdout.flush()`.
-    - **Resource Deployment**: Explicitly configured the converter to migrate `mapping.md` to the target skill.
-    - **Path Refactoring**: Safely handled Windows backslashes in regex replacements to prevent `undefined` segments.
-
-### v1.22.3 (2026-03-03)
-*   **Context:** GSD Skill CLI invocation across SKILL.md, gsd-tools.md, and gsd-tools.cjs
-*   **Issue:** AI agents generated bare `gsd-tools scaffold uat --phase 29` instead of `node .agent/skills/gsd/bin/gsd-tools.cjs scaffold uat --phase 29`, resulting in `Command 'gsd-tools' not found`.
-*   **Root Cause Analysis:** 
-    *   `gsd-tools` is not installed globally via `npm link` or as a PATH binary. It only exists as a local `.cjs` script inside the skill's `bin/` directory.
-    *   The usage header in `gsd-tools.cjs` had `Usage: node gsd-tools.cjs` which was ambiguous — AI agents interpreted this as a globally available command.
-    *   No documentation or reference files explicitly warned that `gsd-tools` must be invoked via `node .agent/skills/gsd/bin/gsd-tools.cjs`.
-*   **How it was fixed:**
-    *   Updated the `gsd-tools.cjs` usage header comment to show the full project-relative path.
-    *   Updated the error message in the fallback `if (!command)` handler.
-    *   Added `CRITICAL` warning blocks to `gsd-tools.md` (both live and converter asset).
-    *   Added Best Practice #5 (`CLI Invocation`) to both `SKILL.md` and `gsd_skill_template.md`.
-    *   Updated the `CONDENSED_HEADER` in `optimize-gsd-tools.cjs` to inject the correct path during future conversions.
-
-### v1.22.2 (2026-03-03)
-*   **Context:** `optimize-gsd-tools.cjs` (GSD Converter Script)
-*   **Issue:** `parseIncludeFlag` missing in `gsd-tools.cjs` after conversion.
-*   **Root Cause Analysis:** 
-    *   The optimizer script checked `!gsdContent.includes('parseIncludeFlag')` to decide whether to inject the `require` statement. 
-    *   Since `parseIncludeFlag` had already been injected earlier in the switch case router, that condition evaluated to false, skipping the import injection.
-*   **How it was fixed:**
-    *   Changed the checking condition to explicitly examine if `parseIncludeFlag } = require` existed rather than just the generic variable string.
-    *   Also modified the injection method to seamlessly inject into the existing `require('./lib/core.cjs')` instead of clumsily appending a new statement.
-
-### v1.22.1 (2026-03-03)
-*   **Context:** `gsd-converter` (`convert.py`)
-*   **Issue:** Optimizer script failed with `ENOTDIR` error during post-processing.
-*   **Root Cause Analysis:** 
-    *   The `convert.py` script was passing the absolute path of `gsd-tools.cjs` to the `optimize-gsd-tools.cjs` script.
-    *   The optimizer script expects a directory path (the `bin` directory) as it needs to recurse through `bin/` and `bin/lib/` to format all `.cjs` files.
-*   **How it was fixed:**
-    *   Modified `convert.py` to resolve the directory name (`os.path.dirname`) of the `gsd_tools_path` before passing it to the optimizer process.
-    *   This ensures the optimizer successfully finds and formats all modular engine components.
-
-### v1.22.0 (2026-03-01)
-*   **Context:** `gsd-tools.cjs` (GSD Core Engine Optimization)
-*   **Issue:** Token overhead and high script size (~125KB) impacting agent context limits.
-*   **Root Cause Analysis:** 
-    *   Legacy indentation (4 spaces) and large diagnostic headers consumed excessive context space in agent prompts.
-    *   Monolithic inclusion of state and roadmap metadata made context windows unmanageable for long phases.
-*   **How it was fixed:**
-    *   **Whitespace Optimization**: Refactored the core engine with 2-space indentation and LF line endings during the migration, reducing the file size by approximately 20-25KB.
-    *   **Modular Inclusions**: Injected `applyIncludes` logic to allow subagents to slice the state file (e.g., `--include roadmap` or `--include state`) instead of loading the entire object.
-    *   **Dynamic Command Discovery**: Automated command list generation in `SKILL.md` to ensure documentation matches the actual capabilities of the CLI tools.
-
-### v1.21.1 (2026-02-27)
-### v1.0.2 (2026-02-20)
-*   **Context:** `gsd-tools.cjs` (Core Engine)
-*   **Issue:** Legacy script was monolithic, lacked contextual flexibility, and had high token overhead for large phases.
-*   **Root Cause Analysis:** Standard GSD scripts didn't support partial file embedding or hierarchical artifact discovery, forcing agents to either read too much or too little context. 
-*   **How it was fixed:** 
-    *   **Automated via `gsd-converter`**: The converter now dynamically injects a modular helper system (`parseIncludeFlag`, `applyIncludes`) into `gsd-tools.cjs`.
-    *   Added regex-based `discoverPhaseArtifacts` to traverse `.planning/` and phase subdirectories automatically.
-    *   Introduced the `--include` flag (e.g., `--include state,roadmap`) to allow sub-agents to request only necessary context, optimizing token usage.
-    *   Injected `MODEL_PROFILES` to centralize model selection logic keyed by GSD role.