specweave 0.22.13 → 0.23.0

package/dist/src/validators/format-preservation-validator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Format Preservation Validator
+ *
+ * Validates sync operations to ensure external items maintain their original format.
+ * Prevents unintended modifications to external item titles, descriptions, and ACs.
+ *
+ * Key validations:
+ * - External items (format_preservation=true) → only comments allowed
+ * - Internal items (format_preservation=false) → full sync allowed
+ * - Title immutability for external items
+ * - Description immutability for external items
+ * - AC modifications blocked for external items
+ *
+ * Part of increment 0047-us-task-linkage (T-034C)
+ */
+import type { Logger } from '../utils/logger.js';
+/**
+ * Sync operation to validate
+ */
+export interface SyncOperation {
+    /** User Story ID (e.g., "US-009") */
+    usId: string;
+    /** Format preservation enabled flag */
+    formatPreservation: boolean;
+    /** Fields to update (e.g., ['title', 'description', 'comments']) */
+    updates: string[];
+    /** Origin (internal | external) */
+    origin?: 'internal' | 'external';
+    /** Proposed title change (if any) */
+    proposedTitle?: string;
+    /** Current title (for validation) */
+    currentTitle?: string;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    /** Validation passed flag */
+    valid: boolean;
+    /** Validation errors */
+    errors?: string[];
+    /** Validation warnings (non-blocking) */
+    warnings?: string[];
+    /** Allowed fields (after filtering blocked fields) */
+    allowedFields?: string[];
+    /** Blocked fields */
+    blockedFields?: string[];
+}
+/**
+ * Format Preservation Validator
+ *
+ * Ensures external items maintain their original format during sync operations.
+ */
+export declare class FormatPreservationValidator {
+    private logger;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Validate sync operation
+     *
+     * Checks if the proposed sync operation violates format preservation rules.
+     *
+     * Rules:
+     * 1. External items (format_preservation=true) → ONLY comments allowed
+     * 2. Title updates → BLOCKED for external items
+     * 3. Description updates → BLOCKED for external items
+     * 4. AC updates → BLOCKED for external items
+     * 5. Status updates → ALLOWED (external tools control lifecycle)
+     * 6. Comments → ALWAYS ALLOWED
+     *
+     * @param operation - Sync operation to validate
+     * @returns Validation result
+     */
+    validate(operation: SyncOperation): ValidationResult;
+    /**
+     * Check if field is blocked for external items
+     *
+     * @param field - Field name (e.g., 'title', 'description', 'comments')
+     * @returns True if field is blocked for external items
+     */
+    private isBlockedField;
+    /**
+     * Get error message for blocked field
+     *
+     * @param field - Blocked field name
+     * @param usId - User Story ID
+     * @returns Error message
+     */
+    private getBlockedFieldError;
+    /**
+     * Validate batch sync operations
+     *
+     * Validates multiple sync operations and returns results for each.
+     *
+     * @param operations - Array of sync operations
+     * @returns Array of validation results
+     */
+    validateBatch(operations: SyncOperation[]): ValidationResult[];
+    /**
+     * Quick check: Is sync allowed?
+     *
+     * Simplified validation that returns true/false without detailed errors.
+     *
+     * @param formatPreservation - Format preservation flag
+     * @param proposedUpdates - Fields to update
+     * @returns True if sync is allowed
+     */
+    isSyncAllowed(formatPreservation: boolean, proposedUpdates: string[]): boolean;
+    /**
+     * Filter allowed fields from sync operation
+     *
+     * Returns only the fields that are allowed for the given operation.
+     *
+     * @param operation - Sync operation
+     * @returns Array of allowed field names
+     */
+    filterAllowedFields(operation: SyncOperation): string[];
+    /**
+     * Get validation summary for logging
+     *
+     * @param result - Validation result
+     * @returns Human-readable summary
+     */
+    getValidationSummary(result: ValidationResult): string;
+}
+//# sourceMappingURL=format-preservation-validator.d.ts.map

package/dist/src/validators/format-preservation-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-preservation-validator.d.ts","sourceRoot":"","sources":["../../../src/validators/format-preservation-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,uCAAuC;IACvC,kBAAkB,EAAE,OAAO,CAAC;IAE5B,oEAAoE;IACpE,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,mCAAmC;IACnC,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEjC,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,KAAK,EAAE,OAAO,CAAC;IAEf,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,qBAAqB;IACrB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAI7C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;IAsDpD;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAatB;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;;;;;;OAOG;IACH,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,gBAAgB,EAAE;IAI9D;;;;;;;;OAQG;IACH,aAAa,CAAC,kBAAkB,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO;IAU9E;;;;;;;OAOG;IACH,mBAAmB,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,EAAE;IASvD;;;;;OAKG;IACH,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;CAWvD"}

package/dist/src/validators/format-preservation-validator.js

@@ -0,0 +1,187 @@
+/**
+ * Format Preservation Validator
+ *
+ * Validates sync operations to ensure external items maintain their original format.
+ * Prevents unintended modifications to external item titles, descriptions, and ACs.
+ *
+ * Key validations:
+ * - External items (format_preservation=true) → only comments allowed
+ * - Internal items (format_preservation=false) → full sync allowed
+ * - Title immutability for external items
+ * - Description immutability for external items
+ * - AC modifications blocked for external items
+ *
+ * Part of increment 0047-us-task-linkage (T-034C)
+ */
+import { consoleLogger } from '../utils/logger.js';
+/**
+ * Format Preservation Validator
+ *
+ * Ensures external items maintain their original format during sync operations.
+ */
+export class FormatPreservationValidator {
+    constructor(options = {}) {
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Validate sync operation
+     *
+     * Checks if the proposed sync operation violates format preservation rules.
+     *
+     * Rules:
+     * 1. External items (format_preservation=true) → ONLY comments allowed
+     * 2. Title updates → BLOCKED for external items
+     * 3. Description updates → BLOCKED for external items
+     * 4. AC updates → BLOCKED for external items
+     * 5. Status updates → ALLOWED (external tools control lifecycle)
+     * 6. Comments → ALWAYS ALLOWED
+     *
+     * @param operation - Sync operation to validate
+     * @returns Validation result
+     */
+    validate(operation) {
+        const errors = [];
+        const warnings = [];
+        const blockedFields = [];
+        const allowedFields = [];
+        // Internal items → full sync allowed, no validation needed
+        if (!operation.formatPreservation) {
+            return {
+                valid: true,
+                allowedFields: operation.updates,
+                blockedFields: []
+            };
+        }
+        // External items → validate each field
+        for (const field of operation.updates) {
+            if (this.isBlockedField(field)) {
+                blockedFields.push(field);
+                errors.push(this.getBlockedFieldError(field, operation.usId));
+            }
+            else {
+                allowedFields.push(field);
+            }
+        }
+        // Validate title immutability (if title change proposed)
+        if (operation.proposedTitle && operation.currentTitle) {
+            if (operation.proposedTitle !== operation.currentTitle) {
+                errors.push(`Title immutability violation for ${operation.usId}: ` +
+                    `Cannot change external item title from "${operation.currentTitle}" to "${operation.proposedTitle}"`);
+            }
+        }
+        // Log validation result
+        if (errors.length > 0) {
+            this.logger.warn(`   ⚠️  Format preservation validation failed for ${operation.usId}:`);
+            errors.forEach(err => this.logger.warn(`      - ${err}`));
+        }
+        if (warnings.length > 0) {
+            warnings.forEach(warn => this.logger.warn(`   ⚠️  ${warn}`));
+        }
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            allowedFields,
+            blockedFields
+        };
+    }
+    /**
+     * Check if field is blocked for external items
+     *
+     * @param field - Field name (e.g., 'title', 'description', 'comments')
+     * @returns True if field is blocked for external items
+     */
+    isBlockedField(field) {
+        const BLOCKED_FIELDS = [
+            'title',
+            'description',
+            'acceptance_criteria',
+            'acs',
+            'body',
+            'overview'
+        ];
+        return BLOCKED_FIELDS.includes(field.toLowerCase());
+    }
+    /**
+     * Get error message for blocked field
+     *
+     * @param field - Blocked field name
+     * @param usId - User Story ID
+     * @returns Error message
+     */
+    getBlockedFieldError(field, usId) {
+        const fieldName = field.toLowerCase();
+        switch (fieldName) {
+            case 'title':
+                return `Cannot update title for ${usId} (external item with format preservation enabled). Original title must be preserved.`;
+            case 'description':
+            case 'body':
+            case 'overview':
+                return `Cannot update description/body for ${usId} (external item with format preservation enabled). Original description must be preserved.`;
+            case 'acceptance_criteria':
+            case 'acs':
+                return `Cannot update acceptance criteria for ${usId} (external item with format preservation enabled). Original ACs must be preserved.`;
+            default:
+                return `Cannot update field "${field}" for ${usId} (external item with format preservation enabled).`;
+        }
+    }
+    /**
+     * Validate batch sync operations
+     *
+     * Validates multiple sync operations and returns results for each.
+     *
+     * @param operations - Array of sync operations
+     * @returns Array of validation results
+     */
+    validateBatch(operations) {
+        return operations.map(op => this.validate(op));
+    }
+    /**
+     * Quick check: Is sync allowed?
+     *
+     * Simplified validation that returns true/false without detailed errors.
+     *
+     * @param formatPreservation - Format preservation flag
+     * @param proposedUpdates - Fields to update
+     * @returns True if sync is allowed
+     */
+    isSyncAllowed(formatPreservation, proposedUpdates) {
+        // Internal items → always allowed
+        if (!formatPreservation) {
+            return true;
+        }
+        // External items → check if any blocked fields
+        return !proposedUpdates.some(field => this.isBlockedField(field));
+    }
+    /**
+     * Filter allowed fields from sync operation
+     *
+     * Returns only the fields that are allowed for the given operation.
+     *
+     * @param operation - Sync operation
+     * @returns Array of allowed field names
+     */
+    filterAllowedFields(operation) {
+        if (!operation.formatPreservation) {
+            return operation.updates; // All fields allowed for internal items
+        }
+        // For external items, filter out blocked fields
+        return operation.updates.filter(field => !this.isBlockedField(field));
+    }
+    /**
+     * Get validation summary for logging
+     *
+     * @param result - Validation result
+     * @returns Human-readable summary
+     */
+    getValidationSummary(result) {
+        if (result.valid) {
+            return `✅ Validation passed (${result.allowedFields?.length || 0} fields allowed)`;
+        }
+        const errorCount = result.errors?.length || 0;
+        const warningCount = result.warnings?.length || 0;
+        const blockedCount = result.blockedFields?.length || 0;
+        return `❌ Validation failed: ${errorCount} error(s), ${warningCount} warning(s), ${blockedCount} field(s) blocked`;
+    }
+}
+//# sourceMappingURL=format-preservation-validator.js.map

package/dist/src/validators/format-preservation-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-preservation-validator.js","sourceRoot":"","sources":["../../../src/validators/format-preservation-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA6CnD;;;;GAIG;AACH,MAAM,OAAO,2BAA2B;IAGtC,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,SAAwB;QAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,aAAa,GAAa,EAAE,CAAC;QACnC,MAAM,aAAa,GAAa,EAAE,CAAC;QAEnC,2DAA2D;QAC3D,IAAI,CAAC,SAAS,CAAC,kBAAkB,EAAE,CAAC;YAClC,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,aAAa,EAAE,SAAS,CAAC,OAAO;gBAChC,aAAa,EAAE,EAAE;aAClB,CAAC;QACJ,CAAC;QAED,uCAAuC;QACvC,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/B,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,CAAC;iBAAM,CAAC;gBACN,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,IAAI,SAAS,CAAC,aAAa,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;YACtD,IAAI,SAAS,CAAC,aAAa,KAAK,SAAS,CAAC,YAAY,EAAE,CAAC;gBACvD,MAAM,CAAC,IAAI,CACT,oCAAoC,SAAS,CAAC,IAAI,IAAI;oBACtD,2CAA2C,SAAS,CAAC,YAAY,SAAS,SAAS,CAAC,aAAa,GAAG,CACrG,CAAC;YACJ,CAAC;QACH,CAAC;QAED,wBAAwB;QACxB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oDAAoD,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC;YACxF,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;YAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;YAC9C,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YACpD,aAAa;YACb,aAAa;SACd,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACK,cAAc,CAAC,KAAa;QAClC,MAAM,cAAc,GAAG;YACrB,OAAO;YACP,aAAa;YACb,qBAAqB;YACrB,KAAK;YACL,MAAM;YACN,UAAU;SACX,CAAC;QAEF,OAAO,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;OAMG;IACK,oBAAoB,CAAC,KAAa,EAAE,IAAY;QACtD,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAEtC,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,OAAO;gBACV,OAAO,2BAA2B,IAAI,sFAAsF,CAAC;YAE/H,KAAK,aAAa,CAAC;YACnB,KAAK,MAAM,CAAC;YACZ,KAAK,UAAU;gBACb,OAAO,sCAAsC,IAAI,4FAA4F,CAAC;YAEhJ,KAAK,qBAAqB,CAAC;YAC3B,KAAK,KAAK;gBACR,OAAO,yCAAyC,IAAI,oFAAoF,CAAC;YAE3I;gBACE,OAAO,wBAAwB,KAAK,SAAS,IAAI,oDAAoD,CAAC;QAC1G,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,UAA2B;QACvC,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,kBAA2B,EAAE,eAAyB;QAClE,kCAAkC;QAClC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,+CAA+C;QAC/C,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;OAOG;IACH,mBAAmB,CAAC,SAAwB;QAC1C,IAAI,CAAC,SAAS,CAAC,kBAAkB,EAAE,CAAC;YAClC,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC,wCAAwC;QACpE,CAAC;QAED,gDAAgD;QAChD,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,MAAwB;QAC3C,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,wBAAwB,MAAM,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,kBAAkB,CAAC;QACrF,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;QAC9C,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,CAAC;QAEvD,OAAO,wBAAwB,UAAU,cAAc,YAAY,gBAAgB,YAAY,mBAAmB,CAAC;IACrH,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.22.13",
+  "version": "0.23.0",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,10 +9,11 @@
   },
   "scripts": {
     "clean": "rm -rf dist/",
-    "build": "tsc && npm run copy:locales && npm run copy:plugins",
+    "build": "tsc && npm run copy:locales && npm run copy:plugins && npm run copy:hook-deps",
     "rebuild": "npm run clean && npm run build",
     "copy:locales": "node scripts/copy-locales.js",
     "copy:plugins": "node scripts/copy-plugin-js.js",
+    "copy:hook-deps": "node scripts/copy-hook-dependencies.js",
     "dev": "tsc --watch",
     "prepare": "npm run build",
     "prepublishOnly": "npm run rebuild",

package/plugins/specweave/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
   "description": "SpecWeave framework. Provides increment planning (PM, Architect, Tech Lead agents), specification generation, TDD workflow, living docs sync, and brownfield support. Essential for all SpecWeave projects.",
-  "version": "0.8.0",
+  "version": "0.22.14",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"
@@ -18,5 +18,39 @@
     "pm",
     "architect",
     "living-docs"
-  ]
+  ],
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-spec.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-write-spec.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
 }

package/plugins/specweave/agents/architect/AGENT.md

@@ -885,7 +885,11 @@ Before marking your work complete, verify:
    - Use template: Context → Decision → Consequences
    - Explain WHY not just WHAT
    - Document alternatives considered
-   - Save to `.specweave/docs/internal/architecture/adr/###-decision-title.md`
+   - **CRITICAL**: Save to `.specweave/docs/internal/architecture/adr/XXXX-decision-title.md`
+     - ✅ CORRECT: `0007-github-first-task-sync.md` (4-digit number, kebab-case)
+     - ❌ WRONG: `adr-0007-github-first-task-sync.md` (NO `adr-` prefix!)
+     - ❌ WRONG: `ADR-0007-github-first-task-sync.md` (lowercase filename)
+     - **Why**: The `adr-` prefix is redundant (already in `/adr/` directory)
 
 3. **Design API Contracts**
    - RESTful API design (resources, verbs, status codes)
@@ -945,8 +949,13 @@ High-level description of the system.
 ```
 
 ### ADR Template
+
+**IMPORTANT**: Filename format vs. content header:
+- **Filename**: `XXXX-decision-title.md` (e.g., `0007-github-first-task-sync.md`)
+- **Header**: `# ADR-XXXX: Decision Title` (includes `ADR-` prefix for clarity in document)
+
 ```markdown
-# ADR-###: [Decision Title]
+# ADR-XXXX: [Decision Title]
 
 **Date**: YYYY-MM-DD
 **Status**: [Proposed | Accepted | Deprecated | Superseded]

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -73,17 +73,24 @@ The test-aware-planner agent is responsible for generating `tasks.md` with **emb
 
 ---
 
-## Task Format (NEW - With Embedded Tests)
+## Task Format (NEW - v0.23.0: Hierarchical US-Task Linkage)
+
+**CRITICAL**: v0.23.0+ requires hierarchical structure grouped by User Story.
 
 Each task in `tasks.md` follows this format:
 
 ```markdown
+## User Story: US-001 - User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: X total, 0 completed
+
 ### T-001: Implement Feature X
 
-**User Story**: US1
-**Acceptance Criteria**: AC-US1-01, AC-US1-02
-**Priority**: P1
-**Estimate**: 4 hours
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
+**Priority**: P0 (Critical) | P1 (Important) | P2 (Nice-to-have)
+**Estimated Effort**: 4 hours
 **Status**: [ ] pending
 
 **Test Plan**:
@@ -667,44 +674,88 @@ If TDD mode is enabled (check frontmatter: `test_mode: TDD`), add TDD workflow s
 
 ### Phase 3: File Generation
 
-**Step 3.1: Generate tasks.md Frontmatter**
+**Step 3.1: Generate tasks.md Frontmatter (v0.23.0+)**
 
 ```markdown
 ---
-increment: {increment-id}
 total_tasks: {count}
-completed_tasks: 0
-test_mode: {TDD|standard}
-coverage_target: {percentage}%
+completed: 0
+by_user_story:
+  US-001: {count_for_us1}
+  US-002: {count_for_us2}
+  US-003: {count_for_us3}
+test_mode: {TDD|test-after}
+coverage_target: {percentage}
 ---
 
-# Implementation Tasks
+# Tasks: {Increment Title}
 ```
 
-**Rules:**
-- `increment`: Use increment ID from folder name
+**Rules (v0.23.0+)**:
 - `total_tasks`: Count all generated tasks
-- `completed_tasks`: Always starts at 0
-- `test_mode`: TDD if user requested, standard otherwise
-- `coverage_target`: Overall target (typically 80-90%)
+- `completed`: Always starts at 0
+- `by_user_story`: Map of US-ID → task count (REQUIRED for progress tracking)
+- `test_mode`: TDD or test-after (no "standard")
+- `coverage_target`: Number without % (e.g., 85, not 85%)
 
-**Step 3.2: Assemble All Tasks**
+**Example**:
+```yaml
+---
+total_tasks: 22
+completed: 0
+by_user_story:
+  US-001: 4
+  US-002: 3
+  US-003: 5
+  US-004: 3
+  US-005: 4
+  US-006: 3
+test_mode: test-after
+coverage_target: 90
+---
+```
 
-Combine all generated tasks in sequence:
+**Step 3.2: Assemble All Tasks (v0.23.0+: Hierarchical by User Story)**
+
+**CRITICAL**: Tasks MUST be grouped by User Story with section headers:
 
 ```markdown
-### T-001: [Task 1]
+## User Story: US-001 - User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: 4 total, 0 completed
+
+### T-001: [First task for US-001]
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01, AC-US1-02
 [Full task format from Phase 2]
 
-### T-002: [Task 2]
+### T-002: [Second task for US-001]
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-03
 [Full task format from Phase 2]
 
-...
+---
 
-### T-{N}: [Last task]
+## User Story: US-002 - Another User Story Title
+
+**Linked ACs**: AC-US2-01, AC-US2-02
+**Tasks**: 3 total, 0 completed
+
+### T-003: [First task for US-002]
+**User Story**: US-002
+**Satisfies ACs**: AC-US2-01
 [Full task format from Phase 2]
+
+...
 ```
 
+**Rules**:
+- Group tasks by User Story using `## User Story: US-XXX - Title` headers
+- Each section shows linked ACs and task count
+- Tasks within section MUST link to that User Story
+- Use `---` separator between User Story sections
+
 **Step 3.3: Write tasks.md**
 
 Save the complete file to:
@@ -719,9 +770,14 @@ Save the complete file to:
 
 Before finalizing, validate the generated tasks.md:
 
-**Validation Checklist:**
+**Validation Checklist (v0.23.0+)**:
 
-- [ ] **AC-ID Coverage**: Every AC-ID from spec.md is referenced in at least one task
+- [ ] **AC-ID Coverage**: Every AC-ID from spec.md is referenced in at least one task (100% coverage required)
+- [ ] **US-Task Linkage**: Every task has **User Story** field linking to valid US-ID
+- [ ] **AC Linkage**: Every task has **Satisfies ACs** field with valid AC-IDs
+- [ ] **Hierarchical Structure**: Tasks grouped by User Story with section headers
+- [ ] **by_user_story Map**: Frontmatter includes by_user_story with correct counts
+- [ ] **No Orphan Tasks**: All tasks link to at least one AC
 - [ ] **Task Format**: Each task follows the standard format (header, test plan, test cases, implementation)
 - [ ] **Test Plans**: All testable tasks have Given/When/Then
 - [ ] **Test Cases**: Test file paths follow project conventions
@@ -731,7 +787,7 @@ Before finalizing, validate the generated tasks.md:
 - [ ] **TDD Workflow**: Included if test_mode is TDD
 - [ ] **Estimates**: Realistic (2-8 hours typical per task)
 - [ ] **Dependencies**: Tasks ordered by dependencies
-- [ ] **Frontmatter**: Correct increment ID, task count, test mode
+- [ ] **Frontmatter**: Correct total_tasks, by_user_story map, test_mode, coverage_target
 
 **Validation Script Example:**
 

package/plugins/specweave/commands/specweave-archive-features.md

@@ -19,6 +19,7 @@ Archive features and epics based on their increment archive status. Features are
 - `--update-links`: Update all links to archived items (default: true)
 - `--preserve-active`: Don't archive features with active projects (default: true)
 - `--orphaned`: Also archive orphaned features/epics with no increments/features
+- `--reason <text>`: Optional reason for archiving (for audit trail, AC-US13-07)
 
 ## Examples
 
@@ -31,6 +32,9 @@ Archive features and epics based on their increment archive status. Features are
 
 # Archive including orphaned features
 /specweave:archive-features --orphaned
+
+# Archive with custom reason for audit trail (AC-US13-07)
+/specweave:archive-features --reason="Obsolete after product pivot"
 ```
 
 ## Archive Rules
@@ -80,12 +84,18 @@ task.run(async () => {
   const archiver = new FeatureArchiver(process.cwd());
 
   // Parse options
+  const reasonIndex = process.argv.indexOf('--reason');
+  const customReason = reasonIndex !== -1 && reasonIndex + 1 < process.argv.length
+    ? process.argv[reasonIndex + 1]
+    : undefined;
+
   const options = {
     dryRun: process.argv.includes('--dry-run'),
     updateLinks: !process.argv.includes('--no-update-links'),
     preserveActiveFeatures: !process.argv.includes('--no-preserve-active'),
     archiveOrphanedFeatures: process.argv.includes('--orphaned'),
-    archiveOrphanedEpics: process.argv.includes('--orphaned')
+    archiveOrphanedEpics: process.argv.includes('--orphaned'),
+    customReason: customReason
   };
 
   // Execute archiving