specweave 0.28.1 → 0.28.5

package/README.md

@@ -39,62 +39,17 @@ Every AI coding tool promises productivity. But after the chat ends:
 
 **SpecWeave is the only framework where AI decisions become permanent, searchable documentation.**
 
-```
-┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
-│  Your    │    │   Spec   │    │   Plan   │    │  Tasks   │    │   Code   │    │  Living  │
-│  Idea    │───▶│(permanent│───▶│(permanent│───▶│(permanent│───▶│          │───▶│   Docs   │
-│          │    │    ✓)    │    │    ✓)    │    │    ✓)    │    │          │    │(auto-sync│
-└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anton-abyzov/specweave/develop/docs-site/static/img/specweave-flow.svg" alt="SpecWeave Flow: Your Idea → Spec → Plan → Tasks → Code → Living Docs" width="800"/>
+</p>
 
 ---
 
 ## The Workflow
 
-```mermaid
-flowchart TB
-    subgraph INPUT["1. TYPE ONE COMMAND"]
-        A["/specweave:increment<br/>'Add dark mode'"]
-    end
-
-    subgraph AGENTS["2. AI AGENTS CREATE"]
-        direction TB
-        PM["PM Agent<br/>User stories + ACs"]
-        ARCH["Architect Agent<br/>Design + ADRs"]
-        PLAN["Planner Agent<br/>Tasks + Tests"]
-        PM --> ARCH --> PLAN
-    end
-
-    subgraph OUTPUT["3. PERMANENT FILES"]
-        direction LR
-        SPEC["spec.md<br/>WHAT"]
-        PLANF["plan.md<br/>HOW"]
-        TASKS["tasks.md<br/>DO"]
-    end
-
-    subgraph EXECUTE["4. BUILD"]
-        B["/specweave:do<br/>Autonomous execution"]
-    end
-
-    subgraph SYNC["5. AUTO-SYNC"]
-        direction LR
-        GH["GitHub"]
-        JIRA["JIRA"]
-        ADO["ADO"]
-        DOCS["Docs"]
-    end
-
-    INPUT --> AGENTS
-    AGENTS --> OUTPUT
-    OUTPUT --> EXECUTE
-    EXECUTE --> SYNC
-
-    style INPUT fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
-    style AGENTS fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
-    style OUTPUT fill:#fff3e0,stroke:#ff9800,stroke-width:2px
-    style EXECUTE fill:#fce4ec,stroke:#e91e63,stroke-width:2px
-    style SYNC fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anton-abyzov/specweave/develop/docs-site/static/img/workflow-diagram.svg" alt="SpecWeave Workflow: Command → AI Agents → Permanent Files → Build → Auto-Sync" width="700"/>
+</p>
 
 ---
 
@@ -135,31 +90,9 @@ Then in Claude Code:
 
 SpecWeave keeps your project management tools in sync **automatically**:
 
-```mermaid
-flowchart LR
-    subgraph SPECWEAVE["SpecWeave"]
-        TASK["Task Completed"]
-        US["User Story Updated"]
-        INC["Increment Progress"]
-    end
-
-    subgraph EXTERNAL["Your Tools (Bidirectional)"]
-        GH["<b>GitHub Issues</b><br/>Checkboxes, comments,<br/>labels auto-update"]
-        JIRA["<b>JIRA</b><br/>Epic/Story hierarchy,<br/>status transitions"]
-        ADO["<b>Azure DevOps</b><br/>Work items,<br/>area paths"]
-    end
-
-    TASK -->|"hooks auto-fire"| GH
-    TASK -->|"hooks auto-fire"| JIRA
-    TASK -->|"hooks auto-fire"| ADO
-
-    GH -->|"import existing"| INC
-    JIRA -->|"import existing"| INC
-    ADO -->|"import existing"| INC
-
-    style SPECWEAVE fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
-    style EXTERNAL fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anton-abyzov/specweave/develop/docs-site/static/img/external-sync-diagram.svg" alt="SpecWeave External Tool Integration: Bidirectional sync with GitHub, JIRA, Azure DevOps" width="800"/>
+</p>
 
 | Platform | Capabilities |
 |----------|--------------|
@@ -226,25 +159,9 @@ As a user, I want to toggle dark mode so that I can reduce eye strain at night.
 
 ### Autonomous Multi-Agent Orchestration
 
-```mermaid
-flowchart LR
-    subgraph AGENTS["15+ Specialized Agents"]
-        PM["PM Agent"]
-        ARCH["Architect"]
-        TECH["Tech Lead"]
-        QA["QA Lead"]
-        SEC["Security"]
-        DEVOPS["DevOps"]
-    end
-
-    PM -->|"spec.md"| ARCH
-    ARCH -->|"plan.md"| TECH
-    TECH -->|"code"| QA
-    QA -->|"tests"| SEC
-    SEC -->|"security review"| DEVOPS
-
-    style AGENTS fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/anton-abyzov/specweave/develop/docs-site/static/img/agents-diagram.svg" alt="SpecWeave Multi-Agent Orchestration: PM → Architect → Tech Lead → QA → Security → DevOps" width="850"/>
+</p>
 
 - **PM Agent**: User stories, acceptance criteria, market analysis
 - **Architect Agent**: System design, ADRs, tech stack decisions
@@ -276,6 +193,28 @@ Three gates before any increment closes:
 - Context optimizer removes irrelevant specs
 - Sub-agent parallelization isolates context
 
+### Why Skills, Not MCP?
+
+**Community insight**: Anthropic's engineering team discovered that [code execution beats direct tool calls](https://www.anthropic.com/engineering/code-execution-with-mcp) for AI agent efficiency.
+
+**The MCP Problem**:
+| Issue | Impact |
+|-------|--------|
+| Tool definition bloat | All tools loaded upfront → context waste |
+| Data duplication | Same data flows through model 2-3× |
+| Token explosion | 150,000 tokens vs 2,000 with code-first |
+
+**SpecWeave's Approach**:
+```
+❌ MCP: Load 50 tools → model picks → fetch → model processes → call another
+✅ Skills: Load 1 skill on-demand → Claude writes code → process locally
+```
+
+> "LLMs are adept at writing code and developers should take advantage of this strength."
+> — [Anthropic Engineering](https://www.anthropic.com/engineering/code-execution-with-mcp)
+
+**Result**: 98%+ token reduction, deterministic execution, reusable skill library.
+
 ---
 
 ## Commands Reference

package/dist/src/core/living-docs/feature-consistency-validator.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Feature Consistency Validator
+ *
+ * Validates and repairs consistency between:
+ * - .specweave/docs/internal/specs/_features/FS-XXX/
+ * - .specweave/docs/internal/specs/{project}/FS-XXX/
+ *
+ * PROBLEM SOLVED:
+ * Living docs sync creates _features/ and {project}/ folders sequentially.
+ * If sync fails midway or increment is deleted, folders can get out of sync.
+ *
+ * SOLUTION:
+ * 1. Detect discrepancies (orphaned _features without project folders)
+ * 2. Auto-repair by creating missing project folders
+ * 3. Report issues for manual intervention when auto-repair not possible
+ *
+ * @see ADR-0142 (if created) for architectural decision
+ */
+import { Logger } from '../../utils/logger.js';
+export interface DiscrepancyReport {
+    /** Feature ID (e.g., "FS-062") */
+    featureId: string;
+    /** Type of discrepancy */
+    type: 'missing_project_folder' | 'missing_features_folder' | 'orphaned_feature';
+    /** Description of the issue */
+    description: string;
+    /** Can this be auto-repaired? */
+    autoRepairable: boolean;
+    /** Path to _features folder (if exists) */
+    featuresPath?: string;
+    /** Path to project folder (if exists) */
+    projectPath?: string;
+    /** Linked increment ID (if found in FEATURE.md) */
+    linkedIncrementId?: string;
+    /** Whether linked increment exists */
+    incrementExists?: boolean;
+}
+export interface ValidationResult {
+    /** Total features scanned */
+    totalFeatures: number;
+    /** Number of consistent features */
+    consistentCount: number;
+    /** List of discrepancies found */
+    discrepancies: DiscrepancyReport[];
+    /** Auto-repair results (if repair was attempted) */
+    repairs?: RepairResult[];
+}
+export interface RepairResult {
+    featureId: string;
+    success: boolean;
+    action: string;
+    error?: string;
+}
+export interface ValidatorOptions {
+    /** Logger instance */
+    logger?: Logger;
+    /** Default project name (for creating missing project folders) */
+    defaultProject?: string;
+    /** Whether to include archived features in validation */
+    includeArchived?: boolean;
+}
+export declare class FeatureConsistencyValidator {
+    private projectRoot;
+    private specsPath;
+    private incrementsPath;
+    private logger;
+    private defaultProject;
+    private includeArchived;
+    constructor(projectRoot: string, options?: ValidatorOptions);
+    /**
+     * Validate consistency between _features and project folders
+     *
+     * @param autoRepair - If true, attempt to auto-repair discrepancies
+     * @returns Validation result with discrepancies and repair results
+     */
+    validate(autoRepair?: boolean): Promise<ValidationResult>;
+    /**
+     * Get all feature folder IDs from _features directory
+     */
+    private getFeatureFolders;
+    /**
+     * Get all project folder names (excluding _features, _epics, _archive)
+     */
+    private getProjectFolders;
+    /**
+     * Check if a feature has consistent folders across _features and projects
+     */
+    private checkFeatureConsistency;
+    /**
+     * Check if a feature is from an external source (GitHub, JIRA, ADO)
+     * External features should NOT be considered orphaned even if local increment is missing
+     */
+    private isExternalFeature;
+    /**
+     * Extract linked increment ID from FEATURE.md
+     */
+    private extractLinkedIncrement;
+    /**
+     * Check if an increment exists (in active or archive folder)
+     */
+    private checkIncrementExists;
+    /**
+     * Attempt to repair a discrepancy
+     */
+    private repairDiscrepancy;
+    /**
+     * Archive an orphaned feature (increment was deleted)
+     * Delegates to FeatureArchiver for consistent archiving behavior
+     */
+    private archiveOrphanedFeature;
+    /**
+     * Create missing project folder for a feature
+     */
+    private repairMissingProjectFolder;
+    /**
+     * Log validation summary
+     */
+    private logValidationSummary;
+    /**
+     * Quick check: Are there any discrepancies?
+     * Use this for fast validation without full report
+     */
+    hasDiscrepancies(): Promise<boolean>;
+    /**
+     * Get list of orphaned features (features in _features without corresponding project folder)
+     */
+    getOrphanedFeatures(): Promise<string[]>;
+}
+//# sourceMappingURL=feature-consistency-validator.d.ts.map

package/dist/src/core/living-docs/feature-consistency-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-consistency-validator.d.ts","sourceRoot":"","sources":["../../../../src/core/living-docs/feature-consistency-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,IAAI,EAAE,wBAAwB,GAAG,yBAAyB,GAAG,kBAAkB,CAAC;IAChF,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,oDAAoD;IACpD,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,qBAAa,2BAA2B;IACtC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAU;gBAErB,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAS/D;;;;;OAKG;IACG,QAAQ,CAAC,UAAU,GAAE,OAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqDtE;;OAEG;YACW,iBAAiB;IAmB/B;;OAEG;YACW,iBAAiB;IAoB/B;;OAEG;YACW,uBAAuB;IAqErC;;;OAGG;YACW,iBAAiB;IAiC/B;;OAEG;YACW,sBAAsB;IA6BpC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;YACW,iBAAiB;IAsC/B;;;OAGG;YACW,sBAAsB;IA0BpC;;OAEG;YACW,0BAA0B;IAwExC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA+C5B;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAK1C;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAM/C"}