specweave 3.0.15 → 3.0.17

package/dist/src/utils/increment-id-validator.d.ts

@@ -1,71 +1,31 @@
-/**
- * Increment ID Validator
- *
- * SECURITY: Centralized validation for increment IDs to prevent path traversal attacks.
- * Increment IDs are used in file paths - malicious IDs like "../../etc/passwd" could
- * escape the .specweave/increments directory.
- *
- * Valid formats:
- * - Standard: NNNN-name (e.g., "0001-feature-name")
- * - External: NNNNE-name (e.g., "0111E-external-import")
- * - Archived: Same as above, stored in _archive/
- *
- * @module utils/increment-id-validator
- */
-/**
- * Validates increment ID format to prevent path traversal attacks.
- *
- * @param id - Increment ID to validate
- * @returns true if ID format is valid, false otherwise
- *
- * @example
- * isValidIncrementId('0001-feature-name') // true
- * isValidIncrementId('0111E-external')    // true
- * isValidIncrementId('0001A-hotfix')      // true (alpha suffix)
- * isValidIncrementId('../../etc')         // false (path traversal)
- * isValidIncrementId('')                  // false (empty)
- * isValidIncrementId('001-short')         // false (only 3 digits)
- */
+/** Shared increment ID syntax. Four digits are minimum padding, never a ceiling. */
+export interface ParsedIncrementId {
+    id: string;
+    number: number;
+    /** Canonical numeric alias, without an import suffix. */
+    numberText: string;
+    suffix: string;
+    name: string;
+}
+export declare function formatIncrementNumber(number: number): string;
+/** Readers accept old three-digit IDs and underscores without renaming them. */
+export declare function parseIncrementId(id: string, options?: {
+    allowLegacy?: boolean;
+}): ParsedIncrementId | null;
 export declare function isValidIncrementId(id: string): boolean;
-/**
- * Validates increment ID and throws an error if invalid.
- *
- * Use this in entry points (CLI commands, API handlers) where you want to
- * fail fast with a clear error message.
- *
- * @param id - Increment ID to validate
- * @throws Error if ID format is invalid
- *
- * @example
- * validateIncrementId('0001-feature'); // passes
- * validateIncrementId('../../etc');    // throws Error
- */
-export declare function validateIncrementId(id: string): void;
-/**
- * Sanitizes an increment ID by extracting just the number prefix.
- * Useful for sorting or comparison operations.
- *
- * @param id - Increment ID to extract number from
- * @returns Numeric prefix (e.g., 1 for "0001-feature") or null if invalid
- *
- * @example
- * extractIncrementNumber('0053-feature')  // 53
- * extractIncrementNumber('0111E-external') // 111
- * extractIncrementNumber('invalid')       // null
- */
+export declare function validateIncrementId(id: string, options?: {
+    allowLegacy?: boolean;
+}): void;
+/** Numeric extraction requires a boundary; it never truncates a longer number. */
 export declare function extractIncrementNumber(id: string): number | null;
-/**
- * Checks if an increment ID has the external suffix (E).
- *
- * External increments are imported from external tools (GitHub, JIRA, ADO)
- * and have read-only sync behavior.
- *
- * @param id - Increment ID to check
- * @returns true if this is an external increment
- *
- * @example
- * isExternalIncrement('0111E-jira-import') // true
- * isExternalIncrement('0001-feature')      // false
- */
 export declare function isExternalIncrement(id: string): boolean;
+export declare function compareIncrementIds(a: string, b: string): number;
+/** Bare numeric aliases match the whole number, optionally an exact suffix. */
+export declare function parseIncrementAlias(value: string): {
+    number: number;
+    suffix: string;
+} | null;
+export declare function matchesIncrementAlias(id: string, alias: string): boolean;
+/** Shared selection policy for readers with different filesystem adapters. */
+export declare function matchIncrementIds(ids: string[], query: string): string[];
 //# sourceMappingURL=increment-id-validator.d.ts.map

package/dist/src/utils/increment-id-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"increment-id-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/increment-id-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA6BtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAOpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKvD"}
+{"version":3,"file":"increment-id-validator.d.ts","sourceRoot":"","sources":["../../../src/utils/increment-id-validator.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK5D;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,iBAAiB,GAAG,IAAI,CAU9G;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CAI7F;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMhE;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIhE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAK5F;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAIxE;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIxE"}

package/dist/src/utils/increment-id-validator.js

@@ -1,117 +1,68 @@
-/**
- * Increment ID Validator
- *
- * SECURITY: Centralized validation for increment IDs to prevent path traversal attacks.
- * Increment IDs are used in file paths - malicious IDs like "../../etc/passwd" could
- * escape the .specweave/increments directory.
- *
- * Valid formats:
- * - Standard: NNNN-name (e.g., "0001-feature-name")
- * - External: NNNNE-name (e.g., "0111E-external-import")
- * - Archived: Same as above, stored in _archive/
- *
- * @module utils/increment-id-validator
- */
-/**
- * Validates increment ID format to prevent path traversal attacks.
- *
- * @param id - Increment ID to validate
- * @returns true if ID format is valid, false otherwise
- *
- * @example
- * isValidIncrementId('0001-feature-name') // true
- * isValidIncrementId('0111E-external')    // true
- * isValidIncrementId('0001A-hotfix')      // true (alpha suffix)
- * isValidIncrementId('../../etc')         // false (path traversal)
- * isValidIncrementId('')                  // false (empty)
- * isValidIncrementId('001-short')         // false (only 3 digits)
- */
-export function isValidIncrementId(id) {
-    if (!id || typeof id !== 'string') {
-        return false;
-    }
-    // Expected format:
-    // - 4 digits (0000-9999)
-    // - Optional single letter suffix (A-Z, a-z, or E for external)
-    // - Hyphen
-    // - Kebab-case name (alphanumeric and hyphens, no leading/trailing hyphens)
-    //
-    // Regex breakdown:
-    // ^\d{4}     - Must start with exactly 4 digits
-    // [A-Za-z]?  - Optional single letter suffix
-    // -          - Required hyphen separator
-    // [a-zA-Z0-9] - Name must start with alphanumeric
-    // [a-zA-Z0-9-]* - Rest of name can include hyphens
-    // [a-zA-Z0-9]$ - Name must end with alphanumeric (prevents trailing hyphen)
-    // OR
-    // [a-zA-Z0-9]$ - Single character name is also valid
-    //
-    // Note: We don't allow dots, slashes, or other path-sensitive characters
-    if (!/^\d{4}[A-Za-z]?-[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(id)) {
-        return false;
+export function formatIncrementNumber(number) {
+    if (!Number.isSafeInteger(number) || number < 1) {
+        throw new Error('Increment number must be a positive safe integer');
     }
-    // Reject 0000 — increment numbers must be 0001+
-    const num = parseInt(id.slice(0, 4), 10);
-    return num > 0;
+    return String(number).padStart(4, '0');
+}
+/** Readers accept old three-digit IDs and underscores without renaming them. */
+export function parseIncrementId(id, options = {}) {
+    if (typeof id !== 'string')
+        return null;
+    const pattern = options.allowLegacy
+        ? /^(\d{3,})([A-Za-z]?)-([a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?)$/
+        : /^(\d{4,})([A-Za-z]?)-([a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)$/;
+    const match = id.match(pattern);
+    if (!match)
+        return null;
+    const number = Number(match[1]);
+    if (!Number.isSafeInteger(number) || number < 1)
+        return null;
+    return { id, number, numberText: formatIncrementNumber(number), suffix: match[2], name: match[3] };
+}
+export function isValidIncrementId(id) {
+    return parseIncrementId(id) !== null;
 }
-/**
- * Validates increment ID and throws an error if invalid.
- *
- * Use this in entry points (CLI commands, API handlers) where you want to
- * fail fast with a clear error message.
- *
- * @param id - Increment ID to validate
- * @throws Error if ID format is invalid
- *
- * @example
- * validateIncrementId('0001-feature'); // passes
- * validateIncrementId('../../etc');    // throws Error
- */
-export function validateIncrementId(id) {
-    if (!isValidIncrementId(id)) {
-        throw new Error(`Invalid increment ID format: "${id}". ` +
-            `Expected format: NNNN-name (e.g., "0001-feature-name") or NNNNE-name for external imports.`);
+export function validateIncrementId(id, options = {}) {
+    if (!parseIncrementId(id, options)) {
+        throw new Error(`Invalid increment ID format: "${id}". Expected format: NNNN-name (four or more digits), e.g. "0001-feature-name" or "10000G-import".`);
     }
 }
-/**
- * Sanitizes an increment ID by extracting just the number prefix.
- * Useful for sorting or comparison operations.
- *
- * @param id - Increment ID to extract number from
- * @returns Numeric prefix (e.g., 1 for "0001-feature") or null if invalid
- *
- * @example
- * extractIncrementNumber('0053-feature')  // 53
- * extractIncrementNumber('0111E-external') // 111
- * extractIncrementNumber('invalid')       // null
- */
+/** Numeric extraction requires a boundary; it never truncates a longer number. */
 export function extractIncrementNumber(id) {
-    if (!id || typeof id !== 'string') {
+    if (typeof id !== 'string')
         return null;
-    }
-    const match = id.match(/^(\d{4})/);
-    if (!match) {
+    const match = id.match(/^(\d{4,})(?:[A-Za-z])?(?=-|$)/);
+    if (!match)
         return null;
-    }
-    return parseInt(match[1], 10);
+    const number = Number(match[1]);
+    return Number.isSafeInteger(number) ? number : null;
 }
-/**
- * Checks if an increment ID has the external suffix (E).
- *
- * External increments are imported from external tools (GitHub, JIRA, ADO)
- * and have read-only sync behavior.
- *
- * @param id - Increment ID to check
- * @returns true if this is an external increment
- *
- * @example
- * isExternalIncrement('0111E-jira-import') // true
- * isExternalIncrement('0001-feature')      // false
- */
 export function isExternalIncrement(id) {
-    if (!isValidIncrementId(id)) {
-        return false;
-    }
-    return /^\d{4}E-/.test(id);
+    return parseIncrementId(id)?.suffix === 'E';
+}
+export function compareIncrementIds(a, b) {
+    const x = parseIncrementId(a, { allowLegacy: true });
+    const y = parseIncrementId(b, { allowLegacy: true });
+    return x && y ? x.number - y.number || a.localeCompare(b) : a.localeCompare(b);
+}
+/** Bare numeric aliases match the whole number, optionally an exact suffix. */
+export function parseIncrementAlias(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = value.match(/^(\d+)([A-Za-z]?)$/);
+    const number = match ? Number(match[1]) : 0;
+    return match && Number.isSafeInteger(number) && number > 0 ? { number, suffix: match[2].toUpperCase() } : null;
+}
+export function matchesIncrementAlias(id, alias) {
+    const parsed = parseIncrementId(id, { allowLegacy: true });
+    const query = parseIncrementAlias(alias);
+    return !!parsed && !!query && parsed.number === query.number && (!query.suffix || parsed.suffix.toUpperCase() === query.suffix);
+}
+/** Shared selection policy for readers with different filesystem adapters. */
+export function matchIncrementIds(ids, query) {
+    const valid = ids.filter(id => parseIncrementId(id, { allowLegacy: true }));
+    if (valid.includes(query))
+        return [query];
+    return valid.filter(id => matchesIncrementAlias(id, query)).sort(compareIncrementIds);
 }
 //# sourceMappingURL=increment-id-validator.js.map

package/dist/src/utils/increment-id-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"increment-id-validator.js","sourceRoot":"","sources":["../../../src/utils/increment-id-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mBAAmB;IACnB,yBAAyB;IACzB,gEAAgE;IAChE,WAAW;IACX,4EAA4E;IAC5E,EAAE;IACF,mBAAmB;IACnB,gDAAgD;IAChD,6CAA6C;IAC7C,yCAAyC;IACzC,kDAAkD;IAClD,mDAAmD;IACnD,4EAA4E;IAC5E,KAAK;IACL,qDAAqD;IACrD,EAAE;IACF,yEAAyE;IACzE,IAAI,CAAC,yDAAyD,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gDAAgD;IAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,GAAG,GAAG,CAAC,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU;IAC5C,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,iCAAiC,EAAE,KAAK;YACxC,4FAA4F,CAC7F,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAU;IAC/C,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU;IAC5C,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"increment-id-validator.js","sourceRoot":"","sources":["../../../src/utils/increment-id-validator.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/resolve-increment-id.d.ts

@@ -1,24 +1,2 @@
-/**
- * Resolve Increment ID Utility
- *
- * Resolves a potentially short increment ID (e.g., "0589") to the full
- * directory name (e.g., "0589-cli-complete-improvements") by matching
- * against .specweave/increments/ entries.
- *
- * Supports:
- * - Exact match: "0589-cli-complete-improvements" → same
- * - Prefix match: "0589" → "0589-cli-complete-improvements"
- * - Ambiguous match: "0573" → ["0573-fix-a", "0573-fix-b"]
- * - No match: "9999" → null
- *
- * @module utils/resolve-increment-id
- */
-/**
- * Resolve a potentially short increment ID to the full directory name.
- *
- * @param incrementId - Short or full increment ID
- * @param projectRoot - Project root directory containing .specweave/
- * @returns Full increment directory name (string), array of matches (string[]) if ambiguous, or null if not found
- */
 export declare function resolveIncrementId(incrementId: string, projectRoot: string): string | string[] | null;
 //# sourceMappingURL=resolve-increment-id.d.ts.map

package/dist/src/utils/resolve-increment-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-increment-id.d.ts","sourceRoot":"","sources":["../../../src/utils/resolve-increment-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAiC1B"}
+{"version":3,"file":"resolve-increment-id.d.ts","sourceRoot":"","sources":["../../../src/utils/resolve-increment-id.ts"],"names":[],"mappings":"AAKA,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAgBrG"}

package/dist/src/utils/resolve-increment-id.js

@@ -1,53 +1,29 @@
-/**
- * Resolve Increment ID Utility
- *
- * Resolves a potentially short increment ID (e.g., "0589") to the full
- * directory name (e.g., "0589-cli-complete-improvements") by matching
- * against .specweave/increments/ entries.
- *
- * Supports:
- * - Exact match: "0589-cli-complete-improvements" → same
- * - Prefix match: "0589" → "0589-cli-complete-improvements"
- * - Ambiguous match: "0573" → ["0573-fix-a", "0573-fix-b"]
- * - No match: "9999" → null
- *
- * @module utils/resolve-increment-id
- */
+/** Resolve a full ID, exact numeric alias, or immutable UUID without prefix guessing. */
 import * as fs from 'fs';
 import * as path from 'path';
-/**
- * Resolve a potentially short increment ID to the full directory name.
- *
- * @param incrementId - Short or full increment ID
- * @param projectRoot - Project root directory containing .specweave/
- * @returns Full increment directory name (string), array of matches (string[]) if ambiguous, or null if not found
- */
+import { compareIncrementIds, matchIncrementIds, parseIncrementId } from './increment-id-validator.js';
 export function resolveIncrementId(incrementId, projectRoot) {
     const incrementsDir = path.join(projectRoot, '.specweave', 'increments');
-    if (!fs.existsSync(incrementsDir)) {
-        return null;
-    }
-    // Check for exact match first
-    const exactPath = path.join(incrementsDir, incrementId);
-    if (fs.existsSync(exactPath)) {
-        return incrementId;
-    }
-    // Try prefix match
     let entries;
     try {
-        entries = fs.readdirSync(incrementsDir);
+        entries = fs.readdirSync(incrementsDir)
+            .filter((entry) => parseIncrementId(entry, { allowLegacy: true }) && fs.statSync(path.join(incrementsDir, entry)).isDirectory());
     }
     catch {
         return null;
     }
-    const matches = entries.filter((e) => e.startsWith(incrementId));
-    if (matches.length === 0) {
-        return null;
-    }
-    if (matches.length === 1) {
-        return matches[0];
-    }
-    // Ambiguous — multiple matches
-    return matches.sort();
+    const exact = entries.find((entry) => entry === incrementId);
+    if (exact)
+        return exact;
+    const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(incrementId);
+    const matches = !uuid ? matchIncrementIds(entries, incrementId) : entries.filter((entry) => {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(incrementsDir, entry, 'metadata.json'), 'utf8')).uuid?.toLowerCase() === incrementId.toLowerCase();
+        }
+        catch {
+            return false;
+        }
+    }).sort(compareIncrementIds);
+    return matches.length === 0 ? null : matches.length === 1 ? matches[0] : matches;
 }
 //# sourceMappingURL=resolve-increment-id.js.map

package/dist/src/utils/resolve-increment-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-increment-id.js","sourceRoot":"","sources":["../../../src/utils/resolve-increment-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,WAAmB;IAEnB,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;IAEzE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8BAA8B;IAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IACxD,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,mBAAmB;IACnB,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAEjE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,+BAA+B;IAC/B,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC"}
+{"version":3,"file":"resolve-increment-id.js","sourceRoot":"","sources":["../../../src/utils/resolve-increment-id.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEvG,MAAM,UAAU,kBAAkB,CAAC,WAAmB,EAAE,WAAmB;IACzE,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;IACzE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC;aACpC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IACrI,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IACxB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC;IAC7D,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,IAAI,GAAG,gDAAgD,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACzF,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,WAAW,CAAC,WAAW,EAAE,CAAC;QACjJ,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,KAAK,CAAC;QAAC,CAAC;IAC3B,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC7B,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACnF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "3.0.15",
+  "version": "3.0.17",
   "description": "Keep intent, specifications, and verified progress portable across AI coding tools. A local live work board, append-only task evidence, explicit handoffs, and optional GitHub/Jira/Azure DevOps integrations.",
   "type": "module",
   "bin": {
@@ -94,6 +94,7 @@
     ".claude-plugin",
     "plugins",
     "src/templates",
+    "src/core/schemas",
     "README.md",
     "CLAUDE.md",
     "INSTALL.md",

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

@@ -1,7 +1,7 @@
 {
   "name": "sw",
   "description": "Portable intent and verified progress across coding tools. Eleven focused workflow skills, two default lifecycle hooks, and a deterministic CLI and live local dashboard.",
-  "version": "3.0.15",
+  "version": "3.0.17",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"

package/plugins/specweave/lib/integrations/github/github-client-v2.js

@@ -228,9 +228,9 @@ WHY: Correct data flow is: Increment \u2192 Living Docs \u2192 GitHub
 FIX: Run 'specweave docs sync <id>' to generate living docs, then sync to GitHub.`
       );
     }
-    const plainIncrementPattern = /^\[\d{3,4}E?\]\s/;
+    const plainIncrementPattern = /^\[\d{3,}[A-Za-z]?\]\s/;
     if (plainIncrementPattern.test(title)) {
-      const match = title.match(/^\[(\d{3,4}E?)\]/);
+      const match = title.match(/^\[(\d{3,}[A-Za-z]?)\]/);
       const incrementId = match ? match[1] : "XXXX";
       const num = parseInt(incrementId.replace("E", ""), 10);
       const isExternal = incrementId.endsWith("E");

package/plugins/specweave/lib/integrations/github/github-client-v2.ts

@@ -307,9 +307,9 @@ export class GitHubClientV2 {
 
     // Check for plain increment ID format [0001] without FS- prefix (CRITICAL FIX v1.0.31)
     // This catches issues like "[0001] Basic layout MVP" that should be "[FS-001][US-001] Basic layout MVP"
-    const plainIncrementPattern = /^\[\d{3,4}E?\]\s/;
+    const plainIncrementPattern = /^\[\d{3,}[A-Za-z]?\]\s/;
     if (plainIncrementPattern.test(title)) {
-      const match = title.match(/^\[(\d{3,4}E?)\]/);
+      const match = title.match(/^\[(\d{3,}[A-Za-z]?)\]/);
       const incrementId = match ? match[1] : 'XXXX';
       // Derive proper FS-ID from the increment number
       const num = parseInt(incrementId.replace('E', ''), 10);