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

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

@@ -4,37 +4,33 @@
  *
  * Auto-Migration Module — Orchestrator
  *
- * Provides auto-detection and migration for DevSteps projects.
- * Safely migrates from legacy index.json to refs-style distributed index.
+ * Brings a project onto the 2.0 layout on every start of the CLI, the MCP server and
+ * the extension: a flat layout moves into `items/`, every item moves into its own
+ * folder, and the tracked index files the item store replaced are removed.
  *
- * Safe to call repeatedly — only migrates once.
+ * Safe to call repeatedly — only migrates once, and only one process at a time.
  *
  * @see STORY-073 External Project Migration Auto-Detection
- * @see EPIC-018 Index Architecture Refactoring
+ * @see STORY-426 The item files are the index
+ * @see STORY-427 Every item is a folder
  */
-import { type AutoMigrationOptions, type MigrationCheckResult, type MigrationStats, checkMigrationNeeded, getMigrationStatusMessage, needsItemsDirectoryMigration } from './auto-migrate-detect.js';
-import { migrateItemsDirectory, performMigration } from './auto-migrate-impl.js';
-export type { AutoMigrationOptions, MigrationCheckResult, MigrationStats };
-export { checkMigrationNeeded, getMigrationStatusMessage, needsItemsDirectoryMigration };
-export { performMigration, migrateItemsDirectory };
+import { type AutoMigrationOptions, checkMigrationNeeded, type FlatItem, getMigrationStatusMessage, hasLegacyIndex, listFlatItems, listTrackedIndexPaths, type MigrationCheckResult, type MigrationProgress, type MigrationStats, needsIndexRemoval, needsItemFolderMigration, needsItemsDirectoryMigration, TRACKED_INDEX_DIRS } from './auto-migrate-detect.js';
+import { type FolderMigrationResult, MIGRATION_LOCK_FILE, migrateItemFolders, STALE_LOCK_MS, withMigrationLock } from './auto-migrate-folders.js';
+import { migrateItemsDirectory, removeTrackedIndexes } from './auto-migrate-impl.js';
+export type { AutoMigrationOptions, FlatItem, FolderMigrationResult, MigrationCheckResult, MigrationProgress, MigrationStats, };
+export { checkMigrationNeeded, getMigrationStatusMessage, hasLegacyIndex, listFlatItems, listTrackedIndexPaths, MIGRATION_LOCK_FILE, migrateItemFolders, migrateItemsDirectory, needsIndexRemoval, needsItemFolderMigration, needsItemsDirectoryMigration, removeTrackedIndexes, STALE_LOCK_MS, TRACKED_INDEX_DIRS, withMigrationLock, };
 /**
- * Automatically migrate if needed — safe to call repeatedly.
+ * Bring the project onto the 2.0 layout if it is not there yet — safe to call on
+ * every start. Returns true when something was migrated; the caller then tells the
+ * user that Git shows the moves as renames to commit.
  *
- * @param devstepsDir Path to .devsteps directory
- * @param options Migration options
- * @returns True if migration was performed, false if not needed
  * @throws Error if migration fails
  */
 export declare function ensureIndexMigrated(devstepsDir: string, options?: AutoMigrationOptions): Promise<boolean>;
 /**
- * Ensure index is migrated AND items are in correct directory structure.
- *
- * Combines:
- * 1. Legacy index.json → refs-style index/ (if needed)
- * 2. Flat structure → items/ subdirectory (if needed)
- * 3. Cleanup orphaned legacy index.json if refs-style is valid
+ * Ensure the 2.0 layout and the `items/docs/` scaffold for the DOC item type.
  *
  * Safe to call on every operation — only migrates when needed.
  */
-export declare function ensureFullMigration(devstepsDir: string, options?: AutoMigrationOptions): Promise<void>;
+export declare function ensureFullMigration(devstepsDir: string, options?: AutoMigrationOptions): Promise<boolean>;
 //# sourceMappingURL=auto-migrate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auto-migrate.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,4BAA4B,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGjF,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,cAAc,EAAE,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,CAAC;AAEzF,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CAuClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"auto-migrate.d.ts","sourceRoot":"","sources":["../../src/core/auto-migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EACL,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,KAAK,QAAQ,EACb,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC5B,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAIrF,YAAY,EACV,oBAAoB,EACpB,QAAQ,EACR,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,GACf,CAAC;AACF,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC5B,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,CAAC;AAsBF;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CA8ClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,OAAO,CAAC,CAelB"}

package/dist/core/auto-migrate.js

@@ -4,62 +4,87 @@
  *
  * Auto-Migration Module — Orchestrator
  *
- * Provides auto-detection and migration for DevSteps projects.
- * Safely migrates from legacy index.json to refs-style distributed index.
+ * Brings a project onto the 2.0 layout on every start of the CLI, the MCP server and
+ * the extension: a flat layout moves into `items/`, every item moves into its own
+ * folder, and the tracked index files the item store replaced are removed.
  *
- * Safe to call repeatedly — only migrates once.
+ * Safe to call repeatedly — only migrates once, and only one process at a time.
  *
  * @see STORY-073 External Project Migration Auto-Detection
- * @see EPIC-018 Index Architecture Refactoring
+ * @see STORY-426 The item files are the index
+ * @see STORY-427 Every item is a folder
  */
-import { existsSync, renameSync } from 'node:fs';
-import { getIndexPaths, hasRefsStyleIndex, loadAllIndexes } from './index-refs.js';
-import { checkMigrationNeeded, getMigrationStatusMessage, needsItemsDirectoryMigration, } from './auto-migrate-detect.js';
-import { migrateItemsDirectory, performMigration } from './auto-migrate-impl.js';
-export { checkMigrationNeeded, getMigrationStatusMessage, needsItemsDirectoryMigration };
-// Re-export impl functions (callers may import directly from auto-migrate)
-export { performMigration, migrateItemsDirectory };
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { checkMigrationNeeded, getMigrationStatusMessage, hasLegacyIndex, listFlatItems, listTrackedIndexPaths, needsIndexRemoval, needsItemFolderMigration, needsItemsDirectoryMigration, TRACKED_INDEX_DIRS, } from './auto-migrate-detect.js';
+import { MIGRATION_LOCK_FILE, migrateItemFolders, STALE_LOCK_MS, withMigrationLock, } from './auto-migrate-folders.js';
+import { migrateItemsDirectory, removeTrackedIndexes } from './auto-migrate-impl.js';
+import { appendGitignoreEntries } from './init-project.js';
+export { checkMigrationNeeded, getMigrationStatusMessage, hasLegacyIndex, listFlatItems, listTrackedIndexPaths, MIGRATION_LOCK_FILE, migrateItemFolders, migrateItemsDirectory, needsIndexRemoval, needsItemFolderMigration, needsItemsDirectoryMigration, removeTrackedIndexes, STALE_LOCK_MS, TRACKED_INDEX_DIRS, withMigrationLock, };
 /**
- * Automatically migrate if needed — safe to call repeatedly.
+ * Run every pending migration step in order, under the migration lock. The check is
+ * repeated once the lock is held: a process that waited finds the work already done.
+ */
+async function migrateUnderLock(devstepsDir, options) {
+    return withMigrationLock(devstepsDir, async () => {
+        const itemsDirNeeded = needsItemsDirectoryMigration(devstepsDir);
+        if (!itemsDirNeeded && !checkMigrationNeeded(devstepsDir).needed)
+            return false;
+        if (itemsDirNeeded)
+            migrateItemsDirectory(devstepsDir, options);
+        // Folders before the index removal: the counters are derived from the folder layout.
+        if (needsItemFolderMigration(devstepsDir))
+            migrateItemFolders(devstepsDir, options);
+        if (needsIndexRemoval(devstepsDir))
+            removeTrackedIndexes(devstepsDir, options);
+        return true;
+    });
+}
+/**
+ * Bring the project onto the 2.0 layout if it is not there yet — safe to call on
+ * every start. Returns true when something was migrated; the caller then tells the
+ * user that Git shows the moves as renames to commit.
  *
- * @param devstepsDir Path to .devsteps directory
- * @param options Migration options
- * @returns True if migration was performed, false if not needed
  * @throws Error if migration fails
  */
 export async function ensureIndexMigrated(devstepsDir, options = {}) {
     const { silent = false, dryRun = false } = options;
+    if (!existsSync(devstepsDir))
+        return false;
+    // Runtime-state ignores also apply to projects that already have the current layout.
+    if (!dryRun) {
+        appendGitignoreEntries(join(dirname(devstepsDir), '.gitignore'), [
+            '.devsteps/import-sessions/',
+            '.devsteps/index/counters.lock/',
+            '.devsteps/index/.counters-lock.*.candidate/',
+            '.devsteps/index/.counters-lock.*.retired/',
+            '.devsteps/index/.counters-lock.*.quarantine/',
+        ]);
+    }
     const check = checkMigrationNeeded(devstepsDir);
-    if (!check.needed) {
-        if (!silent && check.hasRefs)
-            console.log('✅ Project already using refs-style index');
+    if (!check.needed && !needsItemsDirectoryMigration(devstepsDir)) {
+        if (!silent && check.hasCounters)
+            console.log('✅ Project on the 2.0 layout');
         return false;
     }
     if (dryRun) {
         if (!silent) {
             console.log('🔍 Migration Check (Dry-Run)');
-            console.log(`   Legacy index.json: ${check.hasLegacy ? '✓' : '✗'}`);
-            console.log(`   Refs-style index:  ${check.hasRefs ? '✓' : '✗'}`);
-            console.log(`   Items to migrate:  ${check.itemCount ?? 'unknown'}`);
+            console.log(`   ${check.message}`);
             console.log('\n✅ Migration would proceed');
         }
         return true;
     }
     if (!silent) {
         console.log('📦 DevSteps Project Detected');
-        console.log(`🔍 Legacy index.json found (${check.itemCount ?? 'unknown'} items)`);
-        console.log('🆕 Refs-style index not found');
-        console.log('🔄 Auto-migrating...\n');
+        console.log(`🔄 ${check.message}`);
     }
     try {
-        const stats = await performMigration(devstepsDir, options);
-        if (!silent) {
-            if (stats.backupPath)
-                console.log(`   ✅ Backed up to: ${stats.backupPath}`);
-            console.log(`   ✅ Verified: ${stats.totalItems} items migrated`);
-            console.log('✨ Migration complete!\n');
+        const migrated = await migrateUnderLock(devstepsDir, options);
+        if (!silent && migrated) {
+            console.log('✨ Migration complete — Git shows the moves as renames; commit .devsteps.\n');
         }
-        return true;
+        return migrated;
     }
     catch (error) {
         if (!silent)
@@ -68,38 +93,22 @@ export async function ensureIndexMigrated(devstepsDir, options = {}) {
     }
 }
 /**
- * Ensure index is migrated AND items are in correct directory structure.
- *
- * Combines:
- * 1. Legacy index.json → refs-style index/ (if needed)
- * 2. Flat structure → items/ subdirectory (if needed)
- * 3. Cleanup orphaned legacy index.json if refs-style is valid
+ * Ensure the 2.0 layout and the `items/docs/` scaffold for the DOC item type.
  *
  * Safe to call on every operation — only migrates when needed.
  */
 export async function ensureFullMigration(devstepsDir, options = {}) {
     const { silent = false } = options;
-    await ensureIndexMigrated(devstepsDir, options);
-    if (needsItemsDirectoryMigration(devstepsDir)) {
-        migrateItemsDirectory(devstepsDir, options);
-    }
-    // Cleanup: archive stale legacy index.json if refs-style is valid
-    const paths = getIndexPaths(devstepsDir);
-    if (hasRefsStyleIndex(devstepsDir) && existsSync(paths.legacy)) {
-        try {
-            const indexes = loadAllIndexes(devstepsDir);
-            if (indexes.byType.size > 0) {
-                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-                const archivePath = `${paths.legacy}.archived-${timestamp}`;
-                renameSync(paths.legacy, archivePath);
-                if (!silent)
-                    console.log(`   🗑️  Archived legacy index: ${archivePath}`);
-            }
-        }
-        catch (_error) {
+    const migrated = await ensureIndexMigrated(devstepsDir, options);
+    // Idempotent scaffold for the DOC item type (TASK-391 / BUG-075)
+    if (existsSync(join(devstepsDir, 'index', 'counters.json'))) {
+        const docsItemsDir = join(devstepsDir, 'items', 'docs');
+        if (!existsSync(docsItemsDir)) {
+            mkdirSync(docsItemsDir, { recursive: true });
             if (!silent)
-                console.warn('   ⚠️  Keeping legacy index.json (refs-style index validation failed)');
+                console.log('   📁 Created items/docs/ directory for DOC item type');
         }
     }
+    return migrated;
 }
 //# sourceMappingURL=auto-migrate.js.map

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

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

package/dist/core/board.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Coordination board view
+ * Derives a snapshot of the project board from current item state and tags.
+ *
+ * @see STORY-310 BUG-166
+ */
+export interface BoardItem {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    eisenhower: string | null;
+    tags: string[];
+    updated: string;
+}
+export interface BoardResult {
+    now: BoardItem[];
+    next: BoardItem[];
+    later_count: number;
+    delivered_since_7d: BoardItem[];
+    blocked_count: number;
+    wip_limit: number;
+    wip_violated: boolean;
+    arch_snapshot: string | null;
+    generated_at: string;
+}
+/**
+ * Generate a coordination board view from current item state.
+ */
+export declare function getBoard(devstepsDir: string): Promise<BoardResult>;
+//# sourceMappingURL=board.d.ts.map

package/dist/core/board.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../src/core/board.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,SAAS,EAAE,CAAC;IACjB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,SAAS,EAAE,CAAC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;CACtB;AAsBD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwCxE"}

package/dist/core/board.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Coordination board view
+ * Derives a snapshot of the project board from current item state and tags.
+ *
+ * @see STORY-310 BUG-166
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { WIP_LIMIT } from './focus-work.js';
+import { listItems } from './list.js';
+function toItem(e) {
+    return {
+        id: e.id,
+        type: e.type,
+        title: e.title,
+        status: e.status,
+        eisenhower: e.eisenhower ?? null,
+        tags: e.tags ?? [],
+        updated: e.updated,
+    };
+}
+/**
+ * Generate a coordination board view from current item state.
+ */
+export async function getBoard(devstepsDir) {
+    if (!existsSync(devstepsDir)) {
+        throw new Error('DevSteps project not initialized. Run: devsteps init');
+    }
+    const [nowResult, nextResult, laterResult, doneResult, blockedResult] = await Promise.all([
+        listItems(devstepsDir, { tags: ['focus:now'] }),
+        listItems(devstepsDir, { tags: ['focus:next'] }),
+        listItems(devstepsDir, { tags: ['focus:later'] }),
+        listItems(devstepsDir, { status: 'done' }),
+        listItems(devstepsDir, { status: 'blocked' }),
+    ]);
+    const [now, next, later, done, blocked] = [
+        nowResult,
+        nextResult,
+        laterResult,
+        doneResult,
+        blockedResult,
+    ].map((result) => result.items);
+    const sevenDaysMs = 7 * 24 * 3600 * 1000;
+    const deliveredSince7d = done
+        .filter((i) => Date.now() - new Date(i.updated).getTime() < sevenDaysMs)
+        .map(toItem);
+    const archPath = path.join(devstepsDir, 'context/architecture.md');
+    const archSnapshot = existsSync(archPath) ? readFileSync(archPath, 'utf8').slice(0, 300) : null;
+    return {
+        now: now.map(toItem),
+        next: next.map(toItem),
+        later_count: later.length,
+        delivered_since_7d: deliveredSince7d,
+        blocked_count: blocked.length,
+        wip_limit: WIP_LIMIT,
+        wip_violated: now.length > WIP_LIMIT,
+        arch_snapshot: archSnapshot,
+        generated_at: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=board.js.map

package/dist/core/board.js.map

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

package/dist/core/bulk-update.d.ts

@@ -13,6 +13,8 @@ export interface BulkUpdateResult {
         error: string;
     }>;
     total: number;
+    /** The reminders of the updated items, and one batch reminder for the whole call (EPIC-059). */
+    warnings?: string[];
 }
 /**
  * Bulk update multiple items at once

package/dist/core/bulk-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulk-update.d.ts","sourceRoot":"","sources":["../../src/core/bulk-update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKxD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CAuB3B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAiD3B;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,gBAAgB,CAAC,CA4C3B"}
+{"version":3,"file":"bulk-update.d.ts","sourceRoot":"","sources":["../../src/core/bulk-update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAUxD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA6B3B;AA6CD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAI3B"}

package/dist/core/bulk-update.js

@@ -5,11 +5,15 @@
  * Bulk update operations
  * Batch tag management and field patching across multiple work items.
  */
-import { existsSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { getCurrentTimestamp } from '../utils/index.js';
 import { getItem } from './get.js';
+import { itemPaths } from './item-paths.js';
+import { writeItemMetadata } from './item-store.js';
+import { assertValidItemMetadata } from './item-validation.js';
 import { updateItem } from './update.js';
+import { bulkBatchReminder } from './update-reminders.js';
+import { isBatchWorkItem } from './write-diagnostics.js';
 /**
  * Bulk update multiple items at once
  * @param devstepsDir Path to .devsteps directory
@@ -23,13 +27,17 @@ export async function bulkUpdateItems(devstepsDir, itemIds, updates) {
         failed: [],
         total: itemIds.length,
     };
+    const warnings = [];
+    let movedToReview = false;
     for (const id of itemIds) {
         try {
-            await updateItem(devstepsDir, {
-                id,
-                ...updates,
-            });
+            const updated = await updateItem(devstepsDir, { id, ...updates }, { batchReminder: false });
             result.success.push(id);
+            warnings.push(...(updated.warnings ?? []));
+            movedToReview ||=
+                isBatchWorkItem(updated.metadata.type) &&
+                    updated.oldStatus !== 'review' &&
+                    updated.metadata.status === 'review';
         }
         catch (error) {
             result.failed.push({
@@ -38,45 +46,30 @@ export async function bulkUpdateItems(devstepsDir, itemIds, updates) {
             });
         }
     }
-    return result;
+    const batch = bulkBatchReminder(devstepsDir, movedToReview);
+    if (batch)
+        warnings.push(batch);
+    return warnings.length > 0 ? { ...result, warnings } : result;
 }
 /**
- * Bulk add tags to multiple items
- * @param devstepsDir Path to .devsteps directory
- * @param itemIds Array of item IDs
- * @param tagsToAdd Tags to add
- * @returns Result with success and failure lists
+ * Patch one item's tags: read it, apply `patch`, validate, and write it back guarded
+ * by the stamp that was read (STORY-428), so a concurrent writer is never overwritten.
  */
-export async function bulkAddTags(devstepsDir, itemIds, tagsToAdd) {
-    const result = {
-        success: [],
-        failed: [],
-        total: itemIds.length,
-    };
+async function patchTags(devstepsDir, id, patch) {
+    if (!existsSync(itemPaths(devstepsDir, id).metadata)) {
+        throw new Error(`Item ${id} not found`);
+    }
+    const { metadata, stamp } = await getItem(devstepsDir, id);
+    metadata.tags = patch(metadata.tags);
+    metadata.updated = getCurrentTimestamp();
+    assertValidItemMetadata(metadata);
+    writeItemMetadata(devstepsDir, metadata, stamp);
+}
+async function forEachItem(devstepsDir, itemIds, patch) {
+    const result = { success: [], failed: [], total: itemIds.length };
     for (const id of itemIds) {
         try {
-            const { type, folder } = await import('../utils/index.js').then((m) => ({
-                type: m.parseItemId(id)?.type,
-                folder: m.TYPE_TO_DIRECTORY[m.parseItemId(id)?.type || 'task'],
-            }));
-            if (!type) {
-                throw new Error(`Invalid item ID: ${id}`);
-            }
-            const metadataPath = join(devstepsDir, folder, `${id}.json`);
-            if (!existsSync(metadataPath)) {
-                throw new Error(`Item ${id} not found`);
-            }
-            const { metadata } = await getItem(devstepsDir, id);
-            // Add new tags (avoid duplicates)
-            const existingTags = new Set(metadata.tags);
-            for (const tag of tagsToAdd) {
-                existingTags.add(tag);
-            }
-            metadata.tags = Array.from(existingTags);
-            metadata.updated = getCurrentTimestamp();
-            writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
-            // Note: Tags are stored in metadata only (refs-style index has no tags field)
-            // No index update needed with auto-migration
+            await patchTags(devstepsDir, id, patch);
             result.success.push(id);
         }
         catch (error) {
@@ -88,6 +81,16 @@ export async function bulkAddTags(devstepsDir, itemIds, tagsToAdd) {
     }
     return result;
 }
+/**
+ * Bulk add tags to multiple items
+ * @param devstepsDir Path to .devsteps directory
+ * @param itemIds Array of item IDs
+ * @param tagsToAdd Tags to add
+ * @returns Result with success and failure lists
+ */
+export function bulkAddTags(devstepsDir, itemIds, tagsToAdd) {
+    return forEachItem(devstepsDir, itemIds, (tags) => Array.from(new Set([...tags, ...tagsToAdd])));
+}
 /**
  * Bulk remove tags from multiple items
  * @param devstepsDir Path to .devsteps directory
@@ -95,41 +98,7 @@ export async function bulkAddTags(devstepsDir, itemIds, tagsToAdd) {
  * @param tagsToRemove Tags to remove
  * @returns Result with success and failure lists
  */
-export async function bulkRemoveTags(devstepsDir, itemIds, tagsToRemove) {
-    const result = {
-        success: [],
-        failed: [],
-        total: itemIds.length,
-    };
-    for (const id of itemIds) {
-        try {
-            const { type, folder } = await import('../utils/index.js').then((m) => ({
-                type: m.parseItemId(id)?.type,
-                folder: m.TYPE_TO_DIRECTORY[m.parseItemId(id)?.type || 'task'],
-            }));
-            if (!type) {
-                throw new Error(`Invalid item ID: ${id}`);
-            }
-            const metadataPath = join(devstepsDir, folder, `${id}.json`);
-            if (!existsSync(metadataPath)) {
-                throw new Error(`Item ${id} not found`);
-            }
-            const { metadata } = await getItem(devstepsDir, id);
-            // Remove tags
-            metadata.tags = metadata.tags.filter((tag) => !tagsToRemove.includes(tag));
-            metadata.updated = getCurrentTimestamp();
-            writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
-            // Note: Tags are stored in metadata only (refs-style index has no tags field)
-            // No index update needed with auto-migration
-            result.success.push(id);
-        }
-        catch (error) {
-            result.failed.push({
-                id,
-                error: error instanceof Error ? error.message : 'Unknown error',
-            });
-        }
-    }
-    return result;
+export function bulkRemoveTags(devstepsDir, itemIds, tagsToRemove) {
+    return forEachItem(devstepsDir, itemIds, (tags) => tags.filter((tag) => !tagsToRemove.includes(tag)));
 }
 //# sourceMappingURL=bulk-update.js.map

package/dist/core/bulk-update.js.map

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

package/dist/core/child-relations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The types a new item can take when it is created under a parent item, each with the relation
+ * from the new item to the parent. Which pairs are allowed comes from `validateRelationship`,
+ * the one source of the relationship rules; this module only names the relation each kind of
+ * child uses.
+ * @see STORY-535
+ */
+import { ItemType, type Methodology } from '../schemas/index.js';
+/** The relation from a new item to the parent it was created under. */
+export type ChildRelation = 'implements' | 'tests' | 'relates-to' | 'documents';
+export interface ChildRelationOption {
+    /** The type of the new item. */
+    type: ItemType;
+    /** The relation from the new item to the parent. */
+    relation: ChildRelation;
+}
+/**
+ * The types a new item can take under an item of `parentType`, in the order of the item type
+ * enum, each with the relation that links the new item to the parent. Empty when nothing can be
+ * created under the parent.
+ */
+export declare function childRelationsFor(parentType: ItemType, methodology: Methodology): ChildRelationOption[];
+//# sourceMappingURL=child-relations.d.ts.map

package/dist/core/child-relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-relations.d.ts","sourceRoot":"","sources":["../../src/core/child-relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIjE,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,OAAO,GAAG,YAAY,GAAG,WAAW,CAAC;AAEhF,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,oDAAoD;IACpD,QAAQ,EAAE,aAAa,CAAC;CACzB;AAiCD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,QAAQ,EACpB,WAAW,EAAE,WAAW,GACvB,mBAAmB,EAAE,CAOvB"}