@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/auto-migrate-detect.js

@@ -8,51 +8,150 @@
  * These functions only read state and return status information.
  *
  * @see STORY-073 External Project Migration Auto-Detection
+ * @see STORY-426 The item files are the index — tracked index files are removed
+ * @see STORY-427 Every item is a folder
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { hasLegacyIndex, hasRefsStyleIndex, loadLegacyIndex } from './index-refs.js';
-/**
- * Check if index migration is needed (legacy → refs-style)
- */
-export function checkMigrationNeeded(devstepsDir) {
-    if (!existsSync(devstepsDir)) {
-        return { needed: false, hasLegacy: false, hasRefs: false, message: 'Not a DevSteps project (no .devsteps directory)' };
+import { parseItemId, TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { archivedTypeDirectory, typeDirectory } from './item-paths.js';
+/** Derived index directories that 2.0 no longer keeps under `.devsteps/index/`. */
+export const TRACKED_INDEX_DIRS = ['by-type', 'by-status', 'by-priority', 'by-tag'];
+/** Tracked index paths present in the project, relative to `.devsteps/`. */
+export function listTrackedIndexPaths(devstepsDir) {
+    const found = [];
+    for (const dir of TRACKED_INDEX_DIRS) {
+        if (existsSync(join(devstepsDir, 'index', dir)))
+            found.push(`index/${dir}`);
     }
-    const hasLegacy = hasLegacyIndex(devstepsDir);
-    const hasRefs = hasRefsStyleIndex(devstepsDir);
-    if (!hasLegacy && hasRefs) {
-        return { needed: false, hasLegacy: false, hasRefs: true, message: 'Project already using refs-style index ✓' };
+    let entries = [];
+    try {
+        entries = readdirSync(devstepsDir);
     }
-    if (hasLegacy && hasRefs) {
-        return { needed: false, hasLegacy: true, hasRefs: true, message: 'Both index formats exist - manual intervention required' };
+    catch {
+        /* not a project directory */
     }
-    if (!hasLegacy && !hasRefs) {
-        return { needed: false, hasLegacy: false, hasRefs: false, message: 'No index found - new project or not initialized' };
+    for (const name of entries) {
+        if (name.startsWith('index.backup-'))
+            found.push(name);
     }
-    let itemCount;
+    return found;
+}
+function flatItemsIn(typeDir, type) {
+    let entries;
     try {
-        const legacy = loadLegacyIndex(devstepsDir);
-        itemCount = legacy.items.length;
+        entries = readdirSync(typeDir, { withFileTypes: true });
     }
-    catch (_error) {
-        // Ignore - legacy index might be corrupted
+    catch {
+        return [];
     }
-    return { needed: true, hasLegacy: true, hasRefs: false, itemCount, message: `Migration needed: ${itemCount ?? 'unknown'} items to migrate` };
+    // An orphaned `.md` counts too: it moves into the folder, and doctor names the gap.
+    const ids = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const match = /^(.+)\.(json|md)$/.exec(entry.name);
+        if (match && parseItemId(match[1])?.type === type)
+            ids.add(match[1]);
+    }
+    return [...ids].map((id) => ({ typeDir, id }));
+}
+/** Items of every type still in the flat layout, live ones first, then archived ones. */
+export function listFlatItems(devstepsDir) {
+    const types = Object.keys(TYPE_TO_DIRECTORY);
+    return [
+        ...types.flatMap((type) => flatItemsIn(typeDirectory(devstepsDir, type), type)),
+        ...types.flatMap((type) => flatItemsIn(archivedTypeDirectory(devstepsDir, type), type)),
+    ];
+}
+/** Whether the item-folder step has anything to do. */
+export function needsItemFolderMigration(devstepsDir) {
+    return listFlatItems(devstepsDir).length > 0;
+}
+/**
+ * Check if legacy index.json exists (migration detection)
+ */
+export function hasLegacyIndex(devstepsDir) {
+    return existsSync(join(devstepsDir, 'index.json'));
+}
+/** Whether the index-removal step has anything to do. */
+export function needsIndexRemoval(devstepsDir) {
+    return hasLegacyIndex(devstepsDir) || listTrackedIndexPaths(devstepsDir).length > 0;
+}
+function countLegacyItems(devstepsDir) {
+    try {
+        const legacy = JSON.parse(readFileSync(join(devstepsDir, 'index.json'), 'utf-8'));
+        return Array.isArray(legacy.items) ? legacy.items.length : undefined;
+    }
+    catch {
+        return undefined; // corrupted legacy index — still removed, just not counted
+    }
+}
+function describeNeeds(legacy, itemCount, tracked, flat) {
+    const parts = [];
+    if (flat > 0)
+        parts.push(`move ${flat} item${flat === 1 ? '' : 's'} into folders`);
+    const removals = [];
+    if (legacy)
+        removals.push(`legacy index.json (${itemCount ?? 'unknown'} items)`);
+    if (tracked > 0)
+        removals.push(`${tracked} tracked index director${tracked === 1 ? 'y' : 'ies'}`);
+    if (removals.length > 0)
+        parts.push(`remove ${removals.join(' and ')}`);
+    return `Migration needed: ${parts.join('; ')}`;
+}
+/**
+ * Check whether the project still carries a layout the 2.0 artifacts have replaced:
+ * flat item files, tracked index files, or a legacy `index.json`.
+ */
+export function checkMigrationNeeded(devstepsDir) {
+    if (!existsSync(devstepsDir)) {
+        return {
+            needed: false,
+            hasLegacyIndex: false,
+            hasTrackedIndex: false,
+            hasCounters: false,
+            flatItemCount: 0,
+            message: 'Not a DevSteps project (no .devsteps directory)',
+        };
+    }
+    const legacy = hasLegacyIndex(devstepsDir);
+    const tracked = listTrackedIndexPaths(devstepsDir);
+    const flatItemCount = listFlatItems(devstepsDir).length;
+    const hasCounters = existsSync(join(devstepsDir, 'index', 'counters.json'));
+    const itemCount = legacy ? countLegacyItems(devstepsDir) : undefined;
+    const needed = legacy || tracked.length > 0 || flatItemCount > 0;
+    let message;
+    if (needed) {
+        message = describeNeeds(legacy, itemCount, tracked.length, flatItemCount);
+    }
+    else {
+        message = hasCounters
+            ? 'Project on the 2.0 layout — the item files are the index ✓'
+            : 'No index found - new project or not initialized';
+    }
+    return {
+        needed,
+        hasLegacyIndex: legacy,
+        hasTrackedIndex: tracked.length > 0,
+        hasCounters,
+        flatItemCount,
+        ...(itemCount !== undefined ? { itemCount } : {}),
+        message,
+    };
 }
 /**
  * Get user-friendly migration status message
  */
 export function getMigrationStatusMessage(devstepsDir) {
-    const result = checkMigrationNeeded(devstepsDir);
     if (!existsSync(devstepsDir))
         return '❌ Not a DevSteps project';
-    if (result.needed)
-        return `🔄 Migration available: ${result.itemCount ?? 'unknown'} items can be migrated to refs-style index`;
-    if (result.hasRefs)
-        return '✅ Project using refs-style index';
-    if (result.hasLegacy && result.hasRefs)
-        return '⚠️  Both index formats detected - manual cleanup needed';
+    const result = checkMigrationNeeded(devstepsDir);
+    if (result.needed) {
+        return `🔄 Migration available: ${result.message.replace('Migration needed: ', '')}`;
+    }
+    if (result.hasCounters)
+        return '✅ Project on the 2.0 layout';
     return '📦 DevSteps project (no index yet)';
 }
 /**

package/dist/core/auto-migrate-detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto-migrate-detect.js","sourceRoot":"","sources":["../../src/core/auto-migrate-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA0CrF;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,iDAAiD,EAAE,CAAC;IACzH,CAAC;IAED,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAE/C,IAAI,CAAC,SAAS,IAAI,OAAO,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,0CAA0C,EAAE,CAAC;IACjH,CAAC;IAED,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,yDAAyD,EAAE,CAAC;IAC/H,CAAC;IAED,IAAI,CAAC,SAAS,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,iDAAiD,EAAE,CAAC;IACzH,CAAC;IAED,IAAI,SAA6B,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;QAC5C,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;IAClC,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,2CAA2C;IAC7C,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,qBAAqB,SAAS,IAAI,SAAS,mBAAmB,EAAE,CAAC;AAC/I,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAmB;IAC3D,MAAM,MAAM,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAEjD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,0BAA0B,CAAC;IAChE,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,2BAA2B,MAAM,CAAC,SAAS,IAAI,SAAS,4CAA4C,CAAC;IAC/H,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,kCAAkC,CAAC;IAC9D,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,yDAAyD,CAAC;IACzG,OAAO,oCAAoC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,WAAmB;IAC9D,MAAM,eAAe,GACnB,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACtC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACxC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/D,OAAO,eAAe,IAAI,CAAC,eAAe,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"auto-migrate-detect.js","sourceRoot":"","sources":["../../src/core/auto-migrate-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEvE,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,CAAU,CAAC;AA8D7F,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACrC,IAAI,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,OAAO,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,OAAe,EAAE,IAAc;IAClD,IAAI,OAAmD,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,oFAAoF;IACpF,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAS;QAC9B,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,IAAI;YAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAe,CAAC;IAC3D,OAAO;QACL,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QAC/E,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,qBAAqB,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;KACxF,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,OAAO,aAAa,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,OAAO,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,OAAO,cAAc,CAAC,WAAW,CAAC,IAAI,qBAAqB,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,gBAAgB,CAAC,WAAmB;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAClF,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,2DAA2D;IAC/E,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CACpB,MAAe,EACf,SAA6B,EAC7B,OAAe,EACf,IAAY;IAEZ,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC;IACnF,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,MAAM;QAAE,QAAQ,CAAC,IAAI,CAAC,sBAAsB,SAAS,IAAI,SAAS,SAAS,CAAC,CAAC;IACjF,IAAI,OAAO,GAAG,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,0BAA0B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAClG,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxE,OAAO,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,MAAM,EAAE,KAAK;YACb,cAAc,EAAE,KAAK;YACrB,eAAe,EAAE,KAAK;YACtB,WAAW,EAAE,KAAK;YAClB,aAAa,EAAE,CAAC;YAChB,OAAO,EAAE,iDAAiD;SAC3D,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;IACxD,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;IAC5E,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,CAAC;IAEjE,IAAI,OAAe,CAAC;IACpB,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,GAAG,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,WAAW;YACnB,CAAC,CAAC,4DAA4D;YAC9D,CAAC,CAAC,iDAAiD,CAAC;IACxD,CAAC;IAED,OAAO;QACL,MAAM;QACN,cAAc,EAAE,MAAM;QACtB,eAAe,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;QACnC,WAAW;QACX,aAAa;QACb,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAmB;IAC3D,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,0BAA0B,CAAC;IAEhE,MAAM,MAAM,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,2BAA2B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,EAAE,CAAC;IACvF,CAAC;IACD,IAAI,MAAM,CAAC,WAAW;QAAE,OAAO,6BAA6B,CAAC;IAC7D,OAAO,oCAAoC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,WAAmB;IAC9D,MAAM,eAAe,GACnB,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACtC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACxC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC,MAAM,eAAe,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/D,OAAO,eAAe,IAAI,CAAC,eAAe,CAAC;AAC7C,CAAC"}

package/dist/core/auto-migrate-folders.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Item-folder migration and the migration lock (STORY-427, STORY-428).
+ *
+ * Moves `items/<type>s/<ID>.json|.md` into `items/<type>s/<ID>/`, for live and
+ * archived items. The CLI, the MCP server and the extension all migrate on start,
+ * and the extension starts the MCP server — so the first process takes a lock and
+ * the others wait for it instead of moving the same files at the same time.
+ */
+import { type AutoMigrationOptions } from './auto-migrate-detect.js';
+/** Lock file under `.devsteps/` while a migration runs; ignored by Git. */
+export declare const MIGRATION_LOCK_FILE = "migration.lock";
+/** A lock older than this belongs to a process that died mid-migration. */
+export declare const STALE_LOCK_MS: number;
+export interface FolderMigrationResult {
+    /** Items now in their folder. */
+    moved: number;
+    /** Files left in place because the folder already held a file of that name. */
+    conflicts: string[];
+}
+/**
+ * Move every flat item into its folder. Idempotent and resumable: an item already in
+ * its folder is not listed, and a file whose target already exists is left where it
+ * is and reported — a migration never overwrites.
+ */
+export declare function migrateItemFolders(devstepsDir: string, options?: AutoMigrationOptions): FolderMigrationResult;
+/**
+ * Run `task` while holding `.devsteps/migration.lock`. `openSync(..., 'wx')` creates
+ * the lock atomically; a second process polls until the lock is released, or
+ * removes it once it is older than {@link STALE_LOCK_MS}.
+ */
+export declare function withMigrationLock<T>(devstepsDir: string, task: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=auto-migrate-folders.d.ts.map

package/dist/core/auto-migrate-folders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-migrate-folders.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate-folders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,0BAA0B,CAAC;AAGpF,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,aAAa,QAAiB,CAAC;AAI5C,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,qBAAqB,CA4BvB;AAsBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAwBZ"}

package/dist/core/auto-migrate-folders.js

@@ -0,0 +1,104 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Item-folder migration and the migration lock (STORY-427, STORY-428).
+ *
+ * Moves `items/<type>s/<ID>.json|.md` into `items/<type>s/<ID>/`, for live and
+ * archived items. The CLI, the MCP server and the extension all migrate on start,
+ * and the extension starts the MCP server — so the first process takes a lock and
+ * the others wait for it instead of moving the same files at the same time.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, renameSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { join } from 'node:path';
+import { listFlatItems } from './auto-migrate-detect.js';
+import { invalidateStore } from './item-store.js';
+/** Lock file under `.devsteps/` while a migration runs; ignored by Git. */
+export const MIGRATION_LOCK_FILE = 'migration.lock';
+/** A lock older than this belongs to a process that died mid-migration. */
+export const STALE_LOCK_MS = 10 * 60 * 1000;
+const LOCK_POLL_MS = 100;
+/**
+ * Move every flat item into its folder. Idempotent and resumable: an item already in
+ * its folder is not listed, and a file whose target already exists is left where it
+ * is and reported — a migration never overwrites.
+ */
+export function migrateItemFolders(devstepsDir, options = {}) {
+    const flat = listFlatItems(devstepsDir);
+    const result = { moved: 0, conflicts: [] };
+    flat.forEach(({ typeDir, id }, index) => {
+        const dir = join(typeDir, id);
+        mkdirSync(dir, { recursive: true });
+        for (const name of [`${id}.json`, `${id}.md`]) {
+            const from = join(typeDir, name);
+            if (!existsSync(from))
+                continue;
+            const to = join(dir, name);
+            if (existsSync(to)) {
+                result.conflicts.push(join(typeDir, name));
+                continue;
+            }
+            renameSync(from, to);
+        }
+        result.moved += 1;
+        options.onProgress?.({ step: 'item-folders', done: index + 1, total: flat.length, id });
+    });
+    invalidateStore(devstepsDir);
+    if (!options.silent && result.moved > 0) {
+        console.log(`   📁 Moved ${result.moved} items into their folders`);
+    }
+    return result;
+}
+function tryAcquire(lockPath) {
+    try {
+        const fd = openSync(lockPath, 'wx');
+        writeSync(fd, JSON.stringify({ pid: process.pid, started: new Date().toISOString() }));
+        closeSync(fd);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        return false;
+    }
+}
+function isStale(lockPath) {
+    try {
+        return Date.now() - statSync(lockPath).mtimeMs > STALE_LOCK_MS;
+    }
+    catch {
+        return false; // released between the failed acquire and this check — just retry
+    }
+}
+/**
+ * Run `task` while holding `.devsteps/migration.lock`. `openSync(..., 'wx')` creates
+ * the lock atomically; a second process polls until the lock is released, or
+ * removes it once it is older than {@link STALE_LOCK_MS}.
+ */
+export async function withMigrationLock(devstepsDir, task) {
+    const lockPath = join(devstepsDir, MIGRATION_LOCK_FILE);
+    while (!tryAcquire(lockPath)) {
+        if (isStale(lockPath)) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                /* another waiter removed it first */
+            }
+            continue;
+        }
+        await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+    try {
+        return await task();
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+//# sourceMappingURL=auto-migrate-folders.js.map

package/dist/core/auto-migrate-folders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-migrate-folders.js","sourceRoot":"","sources":["../../src/core/auto-migrate-folders.ts"],"names":[],"mappings":"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"}

package/dist/core/auto-migrate-impl.d.ts

@@ -4,22 +4,24 @@
  *
  * Auto-Migration Implementation
  *
- * Stateful migration operations: performs actual index and directory migrations.
- * Contains all I/O-heavy transformation logic.
+ * Stateful migration operations: performs the directory move and the removal of
+ * the tracked index files. Contains all I/O-heavy transformation logic.
  *
  * @see STORY-073 External Project Migration Auto-Detection
+ * @see STORY-426 The item files are the index
  */
-import type { AutoMigrationOptions, MigrationStats } from './auto-migrate-detect.js';
+import { type AutoMigrationOptions, type MigrationStats } from './auto-migrate-detect.js';
 /**
- * Perform core index migration: legacy index.json → refs-style distributed index
+ * Remove the tracked index files the item store has replaced (STORY-426).
  *
- * @param devstepsDir Path to .devsteps directory
- * @param options Migration options
- * @returns Migration statistics
- * @throws Error if migration fails or preconditions not met
- * @internal
+ * Order matters: the counters are secured first — from `counters.json`, the legacy
+ * `index.json`, and the highest IDs on disk, whichever is greater — and only then are
+ * `index/by-*`, `index.backup-*` and `index.json` deleted. Run after the item-folder
+ * step, so the IDs on disk are read from the folder layout. Idempotent.
+ *
+ * @throws Error when `.devsteps` does not exist
  */
-export declare function performMigration(devstepsDir: string, options?: AutoMigrationOptions): Promise<MigrationStats>;
+export declare function removeTrackedIndexes(devstepsDir: string, options?: AutoMigrationOptions): MigrationStats;
 /**
  * Migrate from flat directory structure to items/ subdirectory
  *

package/dist/core/auto-migrate-impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-migrate-impl.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate-impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsBH,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAErF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,cAAc,CAAC,CA6DzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA2BlD"}
+{"version":3,"file":"auto-migrate-impl.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate-impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,OAAO,EACL,KAAK,oBAAoB,EAGzB,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAqBlC;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,cAAc,CAyChB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA2ClD"}

package/dist/core/auto-migrate-impl.js

@@ -4,81 +4,85 @@
  *
  * Auto-Migration Implementation
  *
- * Stateful migration operations: performs actual index and directory migrations.
- * Contains all I/O-heavy transformation logic.
+ * Stateful migration operations: performs the directory move and the removal of
+ * the tracked index files. Contains all I/O-heavy transformation logic.
  *
  * @see STORY-073 External Project Migration Auto-Detection
+ * @see STORY-426 The item files are the index
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, unlinkSync, } from 'node:fs';
 import { join } from 'node:path';
-import { TYPE_TO_DIRECTORY } from '../utils/index.js';
-import { addItemToIndex, getIndexPaths, hasLegacyIndex, hasRefsStyleIndex, initializeRefsStyleIndex, loadAllIndexes, } from './index-refs.js';
+import { getTypePrefix, TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { hasLegacyIndex, listTrackedIndexPaths, } from './auto-migrate-detect.js';
+import { deriveCounters, updateCounters } from './counters.js';
+import { invalidateStore } from './item-store.js';
+/** Counters a pre-refs `index.json` carries, keyed by type prefix. */
+function legacyCounters(devstepsDir) {
+    const counters = {};
+    try {
+        const legacy = JSON.parse(readFileSync(join(devstepsDir, 'index.json'), 'utf-8'));
+        for (const [key, value] of Object.entries(legacy.counters ?? {})) {
+            if (typeof value !== 'number')
+                continue;
+            // Legacy files keyed counters by type name ("task"), later ones by prefix ("TASK").
+            const prefix = key in TYPE_TO_DIRECTORY ? getTypePrefix(key) : key.toUpperCase();
+            counters[prefix] = Math.max(counters[prefix] ?? 0, value);
+        }
+    }
+    catch {
+        /* unreadable legacy index: the IDs on disk decide */
+    }
+    return counters;
+}
 /**
- * Perform core index migration: legacy index.json → refs-style distributed index
+ * Remove the tracked index files the item store has replaced (STORY-426).
+ *
+ * Order matters: the counters are secured first — from `counters.json`, the legacy
+ * `index.json`, and the highest IDs on disk, whichever is greater — and only then are
+ * `index/by-*`, `index.backup-*` and `index.json` deleted. Run after the item-folder
+ * step, so the IDs on disk are read from the folder layout. Idempotent.
  *
- * @param devstepsDir Path to .devsteps directory
- * @param options Migration options
- * @returns Migration statistics
- * @throws Error if migration fails or preconditions not met
- * @internal
+ * @throws Error when `.devsteps` does not exist
  */
-export async function performMigration(devstepsDir, options = {}) {
-    const { skipBackup = false } = options;
-    const paths = getIndexPaths(devstepsDir);
-    if (!existsSync(devstepsDir))
+export function removeTrackedIndexes(devstepsDir, options = {}) {
+    const { silent = false } = options;
+    if (!existsSync(devstepsDir)) {
         throw new Error('.devsteps directory not found. Is this a DevSteps project?');
-    if (!hasLegacyIndex(devstepsDir))
-        throw new Error('No index.json found. Nothing to migrate.');
-    if (hasRefsStyleIndex(devstepsDir))
-        throw new Error('Refs-style index already exists. Aborting to prevent data loss.');
-    const stats = { totalItems: 0, byType: {}, byStatus: {}, byPriority: {} };
-    // Backup old index
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    if (!skipBackup) {
-        const backupPath = `${paths.legacy}.backup-${timestamp}`;
-        writeFileSync(backupPath, readFileSync(paths.legacy, 'utf-8'));
-        stats.backupPath = backupPath;
     }
-    // Load legacy index + initialize new structure
-    const legacyIndex = JSON.parse(readFileSync(paths.legacy, 'utf-8'));
-    initializeRefsStyleIndex(devstepsDir, legacyIndex.counters || {});
-    // Migrate each item into new index
-    for (const item of legacyIndex.items) {
-        const typeFolder = TYPE_TO_DIRECTORY[item.type];
-        const metadataPath = join(devstepsDir, typeFolder, `${item.id}.json`);
-        if (!existsSync(metadataPath))
-            continue;
-        const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
-        if (!metadata.eisenhower)
-            metadata.eisenhower = 'not-urgent-important'; // Default Q2
-        addItemToIndex(devstepsDir, metadata);
-        stats.totalItems++;
-        stats.byType[item.type] = (stats.byType[item.type] || 0) + 1;
-        stats.byStatus[item.status] = (stats.byStatus[item.status] || 0) + 1;
-        stats.byPriority[metadata.eisenhower] = (stats.byPriority[metadata.eisenhower] || 0) + 1;
+    const proposed = {};
+    for (const source of [legacyCounters(devstepsDir), deriveCounters(devstepsDir)]) {
+        for (const [key, value] of Object.entries(source)) {
+            proposed[key] = Math.max(proposed[key] ?? 0, value);
+        }
     }
-    // Verify migration: count + deduplicate
-    const newIndexes = loadAllIndexes(devstepsDir);
-    let newItemCount = 0;
-    for (const items of newIndexes.byType.values()) {
-        newItemCount += items.length;
+    const updated = updateCounters(devstepsDir, proposed);
+    const counters = updated.counters;
+    const countersWritten = updated.changed;
+    const removed = [];
+    for (const relative of listTrackedIndexPaths(devstepsDir)) {
+        rmSync(join(devstepsDir, relative), { recursive: true, force: true });
+        removed.push(relative);
     }
-    if (newItemCount !== stats.totalItems) {
-        throw new Error(`Item count mismatch! Migrated: ${stats.totalItems}, Verified: ${newItemCount}`);
+    if (hasLegacyIndex(devstepsDir)) {
+        unlinkSync(join(devstepsDir, 'index.json'));
+        removed.push('index.json');
     }
-    const allIds = new Set();
-    for (const items of newIndexes.byType.values()) {
-        for (const id of items) {
-            if (allIds.has(id))
-                throw new Error(`Duplicate item detected: ${id}`);
-            allIds.add(id);
-        }
+    invalidateStore(devstepsDir);
+    if (!silent) {
+        for (const relative of removed)
+            console.log(`   🗑️  Removed ${relative}`);
+        if (countersWritten)
+            console.log('   ✅ Wrote index/counters.json');
     }
-    // Archive old index and return stats
-    const archivePath = `${paths.legacy}.archived-${timestamp}`;
-    renameSync(paths.legacy, archivePath);
-    stats.archivePath = archivePath;
-    return stats;
+    // Progress-silent startup must still surface retained ownership artifacts on stderr.
+    for (const warning of updated.warnings)
+        console.warn(warning);
+    return {
+        removed,
+        counters,
+        countersWritten,
+        ...(updated.warnings.length > 0 ? { warnings: updated.warnings } : {}),
+    };
 }
 /**
  * Migrate from flat directory structure to items/ subdirectory
@@ -89,7 +93,16 @@ export function migrateItemsDirectory(devstepsDir, options = {}) {
     const { silent = false } = options;
     if (!silent)
         console.log('📂 Migrating to items/ directory structure...');
-    const oldDirs = ['epics', 'stories', 'tasks', 'bugs', 'spikes', 'tests', 'requirements', 'features'];
+    const oldDirs = [
+        'epics',
+        'stories',
+        'tasks',
+        'bugs',
+        'spikes',
+        'tests',
+        'requirements',
+        'features',
+    ];
     const stats = { moved: 0, types: {} };
     const itemsDir = join(devstepsDir, 'items');
     if (!existsSync(itemsDir))
@@ -111,7 +124,9 @@ export function migrateItemsDirectory(devstepsDir, options = {}) {
         try {
             rmdirSync(oldPath);
         }
-        catch { /* ignore — not empty or other error */ }
+        catch {
+            /* ignore — not empty or other error */
+        }
     }
     if (!silent)
         console.log(`   ✅ Moved ${stats.moved} files to items/ subdirectories`);

package/dist/core/auto-migrate-impl.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto-migrate-impl.js","sourceRoot":"","sources":["../../src/core/auto-migrate-impl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auto-migrate-impl.js","sourceRoot":"","sources":["../../src/core/auto-migrate-impl.ts"],"names":[],"mappings":"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"}