@lumpcode/recipes 0.0.13 → 0.0.14

package/README.md

@@ -8,10 +8,26 @@ Private monorepo workspace for now (same rollout path as `@lumpcode/cli-utils`).
 
 | Recipe | Export | Use when |
 |--------|--------|----------|
-| **backlog** | `backlog` | Generic YAML backlog with a typed stage map and per-item stage resolution |
+| **backlog** | `backlog` | Generic folder backlog with a typed stage map and per-item stage resolution |
 | **featureBacklog** | `featureBacklog` | Feature items with PRD → test plan → test implementation → implementation |
 | **abstractionFinder** | `abstractionFinder` | Ephemeral contexts that scan for duplicated CLI utils and append one backlog item + PRD per run |
-| **abstractionBacklog** | `abstractionBacklog` | YAML backlog items with PRDs — implement abstraction with verify-until-green, then move item to DONE |
+| **abstractionBacklog** | `abstractionBacklog` | Folder backlog items with PRDs — implement abstraction with verify-until-green, then move item to completed/ |
+
+## Backlog layout
+
+Each lump stores backlog items under `backlogItems/`:
+
+```
+.lumpcode/lumps/<lump>/backlogItems/
+  todo/<name>/desc.yml
+  todo/<name>/prd.md          # optional until makePrd / finder writes it
+  todo/<name>/testPlan.md     # featureBacklog only; optional until makeTestPlan
+  completed/<name>/desc.yml   # includes completedAt after move-to-done
+  completed/<name>/prd.md     # moves with the folder
+  completed/<name>/testPlan.md
+```
+
+`desc.yml` is a single YAML object with `name`, `task`, `priority`, optional `dependsOn`, and recipe-specific fields (e.g. `manualPrd` for featureBacklog).
 
 ## Kit
 
@@ -21,8 +37,9 @@ Flat helpers under `src/kit/` (re-exported from the package root):
 - `getRecursiveSteps` — agent step(s) + validation command, retry until pass
 - `retryUntilGreen` — opinionated wrapper over `getRecursiveSteps` with default fix prompt
 - `ephemeralContextListFn` — N fresh synthetic contexts per run (`contextCount`, index-aware names)
-- `ymlBacklogContexts` — `getContextListFn` from a YAML backlog file with optional per-item parsing
-- `setTaskDoneStep` — move finished item from BACKLOG to DONE after a context completes
+- `folderBacklogContexts` — `getContextListFn` from `backlogItems/todo/` with optional per-item parsing
+- `folderSetTaskDoneStep` — move finished item folder from `todo/` to `completed/` after a context completes
+- `ymlBacklogContexts` / `setTaskDoneStep` — **deprecated** YAML-list helpers (warn once, still work)
 - `resolveImplValidateCommand` — string, descriptor, or fn → `ValidationCommandFn`
 - `shellCommand` — `sh -c` helper for validation commands
 
@@ -47,7 +64,9 @@ export default backlog({
 });
 ```
 
-`resolveItem` returns `{ stage, contextName?, variables?, additionalDependsOnContexts? }` or `{ ignored: true }`. Terminal stages with `completion: 'moveToDone'` append `setTaskDoneStep`.
+`resolveItem` returns `{ stage, contextName?, variables?, additionalDependsOnContexts? }` or `{ ignored: true }`. Terminal stages with `completion: 'moveToDone'` append `folderSetTaskDoneStep`.
+
+Context variables injected by `backlog`: `TASK_NAME`, `TASK`, `BACKLOG_ITEMS_DIR`, `BACKLOG_ITEM_DIR`, `BACKLOG_STAGE`.
 
 ## Examples
 
@@ -90,9 +109,7 @@ export default {
     ...abstractionFinder({
         maxPendingAbstractions: 5,
         scanDirectories: ['packages/apps/cli'],
-        backlogFilePath: '.lumpcode/lumps/abstractionImplementer/BACKLOG.yml',
-        doneFilePath: '.lumpcode/lumps/abstractionImplementer/DONE.yml',
-        prdDirPath: '.lumpcode/lumps/abstractionImplementer/prds',
+        backlogItemsDir: '.lumpcode/lumps/abstractionImplementer/backlogItems',
         command: 'cursor',
         lumpVariables: { model: 'composer-2.5' },
         discoveryBranch: 'dev',

package/dist/index.cjs

@@ -225,22 +225,188 @@ function assertProjectRelativePath(filePath, label) {
 }
 function resolveBacklogPaths(configUrl, overrides) {
     const [lumpPath, lumpName] = lumpPathAndName(configUrl);
-    const backlogFilePath = overrides?.backlogFilePath ?? path$1.join(lumpPath, 'BACKLOG.yml');
-    const doneFilePath = overrides?.doneFilePath ?? path$1.join(lumpPath, 'DONE.yml');
-    assertProjectRelativePath(backlogFilePath, 'backlogFilePath');
-    assertProjectRelativePath(doneFilePath, 'doneFilePath');
+    const backlogItemsDir = overrides?.backlogItemsDir ?? path$1.join(lumpPath, 'backlogItems');
+    assertProjectRelativePath(backlogItemsDir, 'backlogItemsDir');
     return {
         lumpPath,
         lumpName,
-        backlogFilePath,
-        doneFilePath,
+        backlogItemsDir,
     };
 }
 
+const CONTEXT_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function assertRecord(value, location) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Backlog item ${location} must be an object`);
+    }
+}
+function assertStringField(record, field, location) {
+    const value = record[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Backlog item ${location} requires non-empty string field "${field}"`);
+    }
+}
+function assertNumberField(record, field, location) {
+    const value = record[field];
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new Error(`Backlog item ${location} requires numeric field "${field}"`);
+    }
+}
+/** Validates and normalizes one backlog item; throws on invalid input. */
+function validateBaseBacklogItem(raw, location) {
+    assertRecord(raw, location);
+    assertStringField(raw, 'name', location);
+    assertStringField(raw, 'task', location);
+    assertNumberField(raw, 'priority', location);
+    if (!CONTEXT_NAME_PATTERN.test(raw.name)) {
+        throw new Error(`Backlog item ${location} has invalid name "${raw.name}" (expected ^[a-zA-Z0-9_-]+$)`);
+    }
+    let dependsOn;
+    if (raw.dependsOn !== undefined) {
+        if (!Array.isArray(raw.dependsOn)) {
+            throw new Error(`Backlog item ${location} field "dependsOn" must be an array`);
+        }
+        for (const dep of raw.dependsOn) {
+            if (typeof dep !== 'string' || dep.trim() === '') {
+                throw new Error(`Backlog item ${location} field "dependsOn" must contain non-empty strings`);
+            }
+        }
+        dependsOn = raw.dependsOn;
+    }
+    return {
+        name: raw.name,
+        task: raw.task,
+        priority: raw.priority,
+        dependsOn,
+    };
+}
+
+async function listTodoFolderNames(todoDir) {
+    try {
+        const entries = await fs.readdir(todoDir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
+    return async () => {
+        const todoDir = path$1.join(backlogItemsDir, 'todo');
+        const folderNames = await listTodoFolderNames(todoDir);
+        const discovered = await Promise.all(folderNames.map(async (folderName) => {
+            const descPath = path$1.join(todoDir, folderName, 'desc.yml');
+            let rawText;
+            try {
+                rawText = await fs.readFile(descPath, 'utf-8');
+            }
+            catch (error) {
+                const err = error;
+                if (err.code === 'ENOENT') {
+                    throw new Error(`Backlog item folder "${folderName}" is missing desc.yml at ${descPath}`);
+                }
+                throw error;
+            }
+            const raw = jsYaml.load(rawText);
+            const baseItem = validateBaseBacklogItem(raw, `in folder "${folderName}"`);
+            if (baseItem.name !== folderName) {
+                throw new Error(`Backlog item folder "${folderName}" desc.yml name "${baseItem.name}" must match folder name`);
+            }
+            const item = parseItem ? parseItem(baseItem, folderName, raw) : baseItem;
+            return { item, folderName };
+        }));
+        discovered.sort((a, b) => {
+            if (a.item.priority !== b.item.priority) {
+                return a.item.priority - b.item.priority;
+            }
+            return a.item.name.localeCompare(b.item.name);
+        });
+        const allCtxs = await Promise.all(discovered.map(async ({ item, folderName }) => {
+            const { parsed, ignored } = parseContext
+                ? await parseContext(item, folderName)
+                : { parsed: undefined, ignored: false };
+            if (ignored) {
+                return null;
+            }
+            return {
+                name: item.name,
+                options: {
+                    priority: item.priority,
+                    dependsOnContexts: item.dependsOn,
+                },
+                variables: parsed?.variables ?? {},
+                ...parsed,
+            };
+        }));
+        return allCtxs.filter((ctx) => !!ctx);
+    };
+}
+
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Moves a finished backlog item folder from todo/ to completed/ after the context completes. */
+const folderSetTaskDoneStep = (input) => {
+    const nameVarName = input.nameVarName ?? 'TASK_NAME';
+    return {
+        async commandFn({ context, workspacePath }) {
+            const variables = context.variables;
+            const itemsDirRelative = variables[input.itemsDirVarName];
+            const taskName = variables[nameVarName];
+            if (!itemsDirRelative || !taskName) {
+                throw new Error('Backlog items directory and task name are required');
+            }
+            const itemsDir = path$1.join(workspacePath, itemsDirRelative);
+            const fromDir = path$1.join(itemsDir, 'todo', taskName);
+            const toDir = path$1.join(itemsDir, 'completed', taskName);
+            const descPath = path$1.join(fromDir, 'desc.yml');
+            const completedDescPath = path$1.join(toDir, 'desc.yml');
+            if (!(await core.pathExists(fromDir))) {
+                return null;
+            }
+            if (await core.pathExists(toDir)) {
+                console.warn(`[lumpcode/recipes] Cannot move backlog item "${taskName}": already exists at ${toDir}`);
+                return null;
+            }
+            const rawText = await fs.readFile(descPath, 'utf-8');
+            const raw = jsYaml.load(rawText);
+            if (!isPlainObject(raw)) {
+                throw new Error(`Backlog desc.yml at ${descPath} must contain a YAML object`);
+            }
+            const updated = {
+                ...raw,
+                completedAt: new Date().toISOString(),
+            };
+            await fs.mkdir(path$1.join(itemsDir, 'completed'), { recursive: true });
+            await fs.rename(fromDir, toDir);
+            await fs.writeFile(completedDescPath, jsYaml.dump(updated));
+            return {
+                executable: 'cat',
+                args: [completedDescPath],
+            };
+        },
+        continueOnError: true,
+    };
+};
+
+let setTaskDoneDeprecatedWarned = false;
+function warnSetTaskDoneDeprecated() {
+    if (setTaskDoneDeprecatedWarned) {
+        return;
+    }
+    setTaskDoneDeprecatedWarned = true;
+    console.warn('[lumpcode/recipes] setTaskDoneStep is deprecated; use folderSetTaskDoneStep. ' +
+        'YAML backlog helpers will be removed in a future major version.');
+}
 /** Moves a finished backlog item from BACKLOG.yml to DONE.yml after the context completes. */
 const setTaskDoneStep = (input) => {
     return {
         async commandFn({ context, workspacePath }) {
+            warnSetTaskDoneDeprecated();
             const variables = context.variables;
             const { backlogVarName, doneVarName } = input;
             const baseBacklogFilePath = variables[backlogVarName];
@@ -278,62 +444,25 @@ function resolveImplValidateCommand(implValidateCommand) {
     return (_input) => implValidateCommand;
 }
 
-const CONTEXT_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
-function assertRecord(value, index) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new Error(`Backlog item at index ${index} must be an object`);
-    }
-}
-function assertStringField(record, field, index) {
-    const value = record[field];
-    if (typeof value !== 'string' || value.trim() === '') {
-        throw new Error(`Backlog item at index ${index} requires non-empty string field "${field}"`);
-    }
-}
-function assertNumberField(record, field, index) {
-    const value = record[field];
-    if (typeof value !== 'number' || Number.isNaN(value)) {
-        throw new Error(`Backlog item at index ${index} requires numeric field "${field}"`);
+let ymlBacklogDeprecatedWarned = false;
+function warnYmlBacklogDeprecated() {
+    if (ymlBacklogDeprecatedWarned) {
+        return;
     }
+    ymlBacklogDeprecatedWarned = true;
+    console.warn('[lumpcode/recipes] ymlBacklogContexts is deprecated; use folderBacklogContexts. ' +
+        'YAML backlog helpers will be removed in a future major version.');
 }
-/** Validates and normalizes one YAML backlog row; throws on invalid input. */
-function validateBaseBacklogItem(raw, index) {
-    assertRecord(raw, index);
-    assertStringField(raw, 'name', index);
-    assertStringField(raw, 'task', index);
-    assertNumberField(raw, 'priority', index);
-    if (!CONTEXT_NAME_PATTERN.test(raw.name)) {
-        throw new Error(`Backlog item at index ${index} has invalid name "${raw.name}" (expected ^[a-zA-Z0-9_-]+$)`);
-    }
-    let dependsOn;
-    if (raw.dependsOn !== undefined) {
-        if (!Array.isArray(raw.dependsOn)) {
-            throw new Error(`Backlog item at index ${index} field "dependsOn" must be an array`);
-        }
-        for (const dep of raw.dependsOn) {
-            if (typeof dep !== 'string' || dep.trim() === '') {
-                throw new Error(`Backlog item at index ${index} field "dependsOn" must contain non-empty strings`);
-            }
-        }
-        dependsOn = raw.dependsOn;
-    }
-    return {
-        name: raw.name,
-        task: raw.task,
-        priority: raw.priority,
-        dependsOn,
-    };
-}
-
 function ymlBacklogContexts({ backlogFilePath, parseItem, parseContext, }) {
     return async () => {
+        warnYmlBacklogDeprecated();
         const raw = await fs.readFile(backlogFilePath, 'utf-8');
         const doc = jsYaml.load(raw);
         if (!Array.isArray(doc)) {
             throw new Error(`Backlog file ${backlogFilePath} must contain a YAML list`);
         }
         const allCtxs = await Promise.all(doc.map(async (rawItem, index) => {
-            const baseItem = validateBaseBacklogItem(rawItem, index);
+            const baseItem = validateBaseBacklogItem(rawItem, `at index ${index}`);
             const item = parseItem ? parseItem(baseItem, index, rawItem) : baseItem;
             const { parsed, ignored } = parseContext
                 ? await parseContext(item, index)
@@ -361,8 +490,8 @@ function defineRecipe(recipe) {
 const BACKLOG_STAGE_VAR = 'BACKLOG_STAGE';
 const BACKLOG_TASK_NAME_VAR = 'TASK_NAME';
 const BACKLOG_TASK_VAR = 'TASK';
-const BACKLOG_FILE_VAR = 'BACKLOG_FILE';
-const BACKLOG_DONE_FILE_VAR = 'DONE_FILE';
+const BACKLOG_ITEMS_DIR_VAR = 'BACKLOG_ITEMS_DIR';
+const BACKLOG_ITEM_DIR_VAR = 'BACKLOG_ITEM_DIR';
 
 function isIgnoredResolution(resolution) {
     return 'ignored' in resolution && resolution.ignored === true;
@@ -379,27 +508,25 @@ function buildStageSteps(stages, stageName) {
     if (stageDef.completion === 'moveToDone') {
         return [
             ...normalized,
-            setTaskDoneStep({
-                backlogVarName: BACKLOG_FILE_VAR,
-                doneVarName: BACKLOG_DONE_FILE_VAR,
+            folderSetTaskDoneStep({
+                itemsDirVarName: BACKLOG_ITEMS_DIR_VAR,
             }),
         ];
     }
     return normalized;
 }
 function backlog(options) {
-    const { configUrl, backlogFilePath: backlogFilePathOverride, doneFilePath: doneFilePathOverride, stages, parseItem, resolveItem, ...rest } = options;
+    const { configUrl, backlogItemsDir: backlogItemsDirOverride, stages, parseItem, resolveItem, ...rest } = options;
     const paths = resolveBacklogPaths(configUrl, {
-        backlogFilePath: backlogFilePathOverride,
-        doneFilePath: doneFilePathOverride,
+        backlogItemsDir: backlogItemsDirOverride,
     });
     const projectRoot = projectRootFromConfigUrl(configUrl);
-    const absoluteBacklogPath = path$1.join(projectRoot, paths.backlogFilePath);
+    const absoluteBacklogItemsDir = path$1.join(projectRoot, paths.backlogItemsDir);
     return cliUtils.defineConfig({
-        getContextListFn: ymlBacklogContexts({
-            backlogFilePath: absoluteBacklogPath,
+        getContextListFn: folderBacklogContexts({
+            backlogItemsDir: absoluteBacklogItemsDir,
             parseItem,
-            async parseContext(item) {
+            async parseContext(item, folderName) {
                 const resolution = await resolveItem({ item, paths });
                 if (isIgnoredResolution(resolution)) {
                     return { ignored: true };
@@ -409,14 +536,15 @@ function backlog(options) {
                     ...(item.dependsOn ?? []),
                     ...(additionalDependsOnContexts ?? []),
                 ];
+                const backlogItemDir = path$1.join(paths.backlogItemsDir, 'todo', folderName);
                 return {
                     parsed: {
                         name: contextName ?? item.name,
                         variables: {
                             [BACKLOG_TASK_NAME_VAR]: item.name,
                             [BACKLOG_TASK_VAR]: item.task,
-                            [BACKLOG_FILE_VAR]: paths.backlogFilePath,
-                            [BACKLOG_DONE_FILE_VAR]: paths.doneFilePath,
+                            [BACKLOG_ITEMS_DIR_VAR]: paths.backlogItemsDir,
+                            [BACKLOG_ITEM_DIR_VAR]: backlogItemDir,
                             [BACKLOG_STAGE_VAR]: stage,
                             ...variables,
                         },
@@ -446,11 +574,11 @@ const backlogRecipe = defineRecipe((options) => backlog(options));
 const abstractionBacklog = defineRecipe((options) => {
     const { implValidateCommand, configUrl, implSteps, ...rest } = options;
     const projectRoot = projectRootFromConfigUrl(configUrl);
-    const runImplValidation = resolveImplValidateCommand(implValidateCommand);
+    const runImplValidation = resolveImplValidateCommand(implValidateCommand ?? 'echo "No implementation validation command provided. I say, trust but verify, but well..."');
     return backlog({
         configUrl,
         async resolveItem({ item, paths }) {
-            const itemPrdPath = path$1.join(paths.lumpPath, 'prds', `${item.name}.prd.md`);
+            const itemPrdPath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'prd.md');
             const hasPrd = await core.pathExists(path$1.join(projectRoot, itemPrdPath));
             if (!hasPrd) {
                 return { ignored: true };
@@ -494,43 +622,44 @@ const abstractionBacklog = defineRecipe((options) => {
 });
 
 const abstractionFinder = defineRecipe((options) => {
-    const { maxPendingAbstractions = 5, scanDirectories, customPrompt, backlogFilePath, prdDirPath, doneFilePath, } = options;
+    const { maxPendingAbstractions = 5, scanDirectories, customPrompt, backlogItemsDir, } = options; // TODO : check if pending abstcations in backlog are less than maxPendingAbstractions
     return cliUtils.defineConfig({
         ...options,
         getContextListFn: ephemeralContextListFn({
             contextCount: maxPendingAbstractions,
             variables: {
-                PRD_DIR_PATH: prdDirPath ?? '',
-                BACKLOG_FILE_PATH: backlogFilePath ?? '',
-                DONE_FILE_PATH: doneFilePath ?? '',
+                BACKLOG_ITEMS_DIR: backlogItemsDir,
             },
         }),
-        steps: buildFinderPrompt({ prdDirPath, backlogFilePath, doneFilePath, scanDirectories, customPrompt }),
+        steps: buildFinderPrompt({ backlogItemsDir, scanDirectories, customPrompt }),
     });
 });
-function buildFinderPrompt({ prdDirPath, backlogFilePath, doneFilePath, scanDirectories, customPrompt, }) {
+function buildFinderPrompt({ backlogItemsDir, scanDirectories, customPrompt, }) {
     return customPrompt ? customPrompt() : `
 Scan ${(scanDirectories || []).map((dir) => `@${dir}`).join(' and ') || 'the codebase'} for duplicated logic that appears in multiple places (same pattern, not merely similar file structure).
 
-Read @${backlogFilePath} and @${doneFilePath}. Do not propose abstractions whose util name already appears in either file.
+List existing backlog item names under @${backlogItemsDir}/todo/ and @${backlogItemsDir}/completed/. Do not propose abstractions whose util name already appears in either directory.
 
 Pick exactly one new abstraction that:
 - Has a clear util name matching ^[a-zA-Z0-9_-]+$ that describes the pattern it captures.
 - Would materialize as a new util under packages/apps/cli/src/utils/<utilName>/.
 - Would shrink the codebase: refactoring all call sites in packages/apps/cli should reduce net line count (excluding new unit tests).
 
-Add exactly one entry to @${backlogFilePath} with:
-- task: a concise summary of the repeated pattern, proposed util name, and affected areas
-- priority: max existing priority in BACKLOG.yml plus 1 (or 1 if the backlog is empty)
-- dependsOn: optional list of util names from BACKLOG.yml or DONE.yml that must land first (only when clearly needed)
-
-Write an implementation-ready PRD to @${prdDirPath}/<utilName>.prd.md for the same util name. The PRD should be self-contained and include:
-- Problem statement and repeated pattern
-- Goals and non-goals
-- Proposed util API and affected files
-- Acceptance criteria (including net line reduction and unit tests)
-
-Do not implement code. Only edit @${backlogFilePath} (append one item) and create the PRD file.
+Create exactly one new backlog item folder at @${backlogItemsDir}/todo/<utilName>/ with:
+- desc.yml containing:
+  - name: <utilName> (must match folder name)
+  - task: a concise summary of the repeated pattern, proposed util name, and affected areas
+  - priority: max existing priority in todo/ plus 1 (or 1 if todo/ is empty)
+  - dependsOn: optional list of util names from todo/ or completed/ that must land first (only when clearly needed)
+- prd.md: an implementation-ready PRD for the same util name. The PRD should be self-contained and include:
+  - Problem statement and repeated pattern
+  - Goals and non-goals
+  - Proposed util API and affected files
+  - Acceptance criteria (including net line reduction and unit tests)
+
+Do not implement code. Only create @${backlogItemsDir}/todo/<utilName>/desc.yml and @${backlogItemsDir}/todo/<utilName>/prd.md.
+
+Do not take too much time looking for every possible abstraction. Once you found a good abstraction, stop and create the backlog item.
     `.trim();
 }
 
@@ -559,8 +688,8 @@ function featureContextName(itemName, stage) {
     }
 }
 async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, baseBranch) {
-    const prdFilePath = path$1.join(paths.lumpPath, 'prds', `${item.name}.prd.md`);
-    const testPlanFilePath = path$1.join(paths.lumpPath, 'testPlans', `${item.name}.test.md`);
+    const prdFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'prd.md');
+    const testPlanFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'testPlan.md');
     const hasPrd = await core.pathExists(path$1.join(projectRoot, prdFilePath));
     if (!hasPrd) {
         if (item.manualPrd === true) {
@@ -613,15 +742,14 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
     };
 }
 const featureBacklog = defineRecipe((options) => {
-    const { configUrl, baseBranch, implValidateCommand, backlogFilePath, doneFilePath, ...rest } = options;
+    const { configUrl, baseBranch, implValidateCommand, backlogItemsDir, ...rest } = options;
     const projectRoot = projectRootFromConfigUrl(configUrl);
-    const runImplValidation = resolveImplValidateCommand(implValidateCommand);
+    const runImplValidation = resolveImplValidateCommand(implValidateCommand ?? 'echo "No implementation validation command provided. I say, trust but verify, but well..."');
     return backlog({
         configUrl,
-        backlogFilePath,
-        doneFilePath,
+        backlogItemsDir,
         baseBranch,
-        parseItem(baseItem, _index, raw) {
+        parseItem(baseItem, _folderName, raw) {
             assertValidFeatureItemName(baseItem.name);
             const record = raw;
             if (record.manualPrd !== undefined && typeof record.manualPrd !== 'boolean') {
@@ -642,16 +770,16 @@ const featureBacklog = defineRecipe((options) => {
                     {
                         promptFn({ context: ctx }) {
                             const vars = ctx.variables;
-                            const { BACKLOG_FILE, TASK_NAME, TASK, PRD_FILE } = vars;
+                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, PRD_FILE } = vars;
                             return `
-Write a product requirements document (PRD) for the following Lumpcode backlog item from @${BACKLOG_FILE}.
+Write a product requirements document (PRD) for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
 
 Task name: ${TASK_NAME}
 
 Task:
 ${TASK}
 
-Save the PRD to @${PRD_FILE}. Do not edit @${BACKLOG_FILE}.
+Save the PRD to @${PRD_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml.
 
 The PRD should be self-contained and implementation-ready. Include:
 - Problem statement and motivation
@@ -676,9 +804,9 @@ The PRD should not contain any testing strategy details.
                     {
                         promptFn({ context: ctx }) {
                             const vars = ctx.variables;
-                            const { BACKLOG_FILE, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
+                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
                             return `
-Write a test plan for the following Lumpcode backlog item from @${BACKLOG_FILE}.
+Write a test plan for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
 
 Task name: ${TASK_NAME}
 Task:
@@ -686,7 +814,7 @@ ${TASK}
 
 The PRD for this task is @${PRD_FILE}. The test plan should match the requirements of the PRD.
 
-Save the test plan to @${TEST_PLAN_FILE}. Do not edit @${BACKLOG_FILE} nor @${PRD_FILE}.
+Save the test plan to @${TEST_PLAN_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml nor @${PRD_FILE}.
 
 The test plan should be self-contained and implementation-ready. Include:
 - Test cases
@@ -705,9 +833,9 @@ The test plan should be self-contained and implementation-ready. Include:
                     {
                         promptFn({ context: ctx }) {
                             const vars = ctx.variables;
-                            const { BACKLOG_FILE, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
+                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
                             return `
-Write a test implementation for the following Lumpcode backlog item from @${BACKLOG_FILE}.
+Write a test implementation for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
 
 Task name: ${TASK_NAME}
 Task:
@@ -744,8 +872,8 @@ The implementation should make the tests pass. Do not edit any test file.
     });
 });
 
-exports.BACKLOG_DONE_FILE_VAR = BACKLOG_DONE_FILE_VAR;
-exports.BACKLOG_FILE_VAR = BACKLOG_FILE_VAR;
+exports.BACKLOG_ITEMS_DIR_VAR = BACKLOG_ITEMS_DIR_VAR;
+exports.BACKLOG_ITEM_DIR_VAR = BACKLOG_ITEM_DIR_VAR;
 exports.BACKLOG_STAGE_VAR = BACKLOG_STAGE_VAR;
 exports.BACKLOG_TASK_NAME_VAR = BACKLOG_TASK_NAME_VAR;
 exports.BACKLOG_TASK_VAR = BACKLOG_TASK_VAR;
@@ -756,6 +884,8 @@ exports.backlogRecipe = backlogRecipe;
 exports.defineRecipe = defineRecipe;
 exports.ephemeralContextListFn = ephemeralContextListFn;
 exports.featureBacklog = featureBacklog;
+exports.folderBacklogContexts = folderBacklogContexts;
+exports.folderSetTaskDoneStep = folderSetTaskDoneStep;
 exports.getRecursiveSteps = getRecursiveSteps;
 exports.lumpPathAndName = lumpPathAndName;
 exports.normalizeMaybePromGetter = normalizeMaybePromGetter;

package/dist/index.d.ts

@@ -71,25 +71,14 @@ declare function projectRootFromConfigUrl(configUrl: string | URL): string;
 /** Fails the context when the artifact referenced by a context variable was not created. */
 declare function requireArtifactStep(artifactPathVarName: string): Step;
 
-type BacklogPaths$1 = {
+type BacklogPaths = {
     lumpPath: string;
     lumpName: string;
-    backlogFilePath: string;
-    doneFilePath: string;
+    backlogItemsDir: string;
 };
 declare function resolveBacklogPaths(configUrl: string | URL, overrides?: {
-    backlogFilePath?: string;
-    doneFilePath?: string;
-}): BacklogPaths$1;
-
-/** Moves a finished backlog item from BACKLOG.yml to DONE.yml after the context completes. */
-declare const setTaskDoneStep: (input: {
-    backlogVarName: string;
-    doneVarName: string;
-}) => Step;
-
-type ImplValidateCommand = string | CommandDescriptor | ValidationCommandFn;
-declare function resolveImplValidateCommand(implValidateCommand: ImplValidateCommand): ValidationCommandFn;
+    backlogItemsDir?: string;
+}): BacklogPaths;
 
 type Recipe<Options, V extends LumpVariables = LumpVariables> = (options: Options) => LumpJsConfig<V>;
 declare function defineRecipe<Options, V extends LumpVariables = LumpVariables>(recipe: Recipe<Options, V>): Recipe<Options, V>;
@@ -104,6 +93,31 @@ type DoneBacklogItem<T extends BaseBacklogItem = BaseBacklogItem> = T & {
     completedAt: string;
 };
 
+type FolderBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem> = {
+    backlogItemsDir: string;
+    parseItem?: (item: BaseBacklogItem, folderName: string, raw: unknown) => Item;
+    parseContext?: (item: Item, folderName: string) => MaybePromise$1<{
+        parsed?: Partial<Context>;
+        ignored?: boolean;
+    }>;
+};
+declare function folderBacklogContexts<Item extends BaseBacklogItem = BaseBacklogItem>({ backlogItemsDir, parseItem, parseContext, }: FolderBacklogContextsOptions<Item>): GetContextListFn;
+
+/** Moves a finished backlog item folder from todo/ to completed/ after the context completes. */
+declare const folderSetTaskDoneStep: (input: {
+    itemsDirVarName: string;
+    nameVarName?: string;
+}) => Step;
+
+/** Moves a finished backlog item from BACKLOG.yml to DONE.yml after the context completes. */
+declare const setTaskDoneStep: (input: {
+    backlogVarName: string;
+    doneVarName: string;
+}) => Step;
+
+type ImplValidateCommand = string | CommandDescriptor | ValidationCommandFn;
+declare function resolveImplValidateCommand(implValidateCommand: ImplValidateCommand): ValidationCommandFn;
+
 type YmlBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem> = {
     backlogFilePath: string;
     parseItem?: (item: BaseBacklogItem, index: number, raw: unknown) => Item;
@@ -114,11 +128,11 @@ type YmlBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem> =
 };
 declare function ymlBacklogContexts<Item extends BaseBacklogItem = BaseBacklogItem>({ backlogFilePath, parseItem, parseContext, }: YmlBacklogContextsOptions<Item>): GetContextListFn;
 
-/** Validates and normalizes one YAML backlog row; throws on invalid input. */
-declare function validateBaseBacklogItem(raw: unknown, index: number): BaseBacklogItem;
+/** Validates and normalizes one backlog item; throws on invalid input. */
+declare function validateBaseBacklogItem(raw: unknown, location: string): BaseBacklogItem;
 
 type AbstractionBacklogOptions = {
-    implValidateCommand: ValidationCommandFn | string;
+    implValidateCommand?: ValidationCommandFn | string;
     /** Lump config module URL — pass `import.meta.url` from `config.ts`. */
     configUrl: string | URL;
     implSteps?: LumpJsConfig['steps'];
@@ -129,9 +143,7 @@ type AbstractionFinderOptions = {
     scanDirectories?: string[];
     customPrompt?(): string;
     maxPendingAbstractions?: number;
-    backlogFilePath: string;
-    doneFilePath?: string;
-    prdDirPath?: string;
+    backlogItemsDir: string;
 } & LumpJsConfig;
 declare const abstractionFinder: Recipe<AbstractionFinderOptions>;
 
@@ -139,12 +151,6 @@ type BacklogStageDefinition = {
     steps: NonNullable<LumpJsConfig['steps']>;
     completion: 'keepPending' | 'moveToDone';
 };
-type BacklogPaths = {
-    lumpPath: string;
-    lumpName: string;
-    backlogFilePath: string;
-    doneFilePath: string;
-};
 type BacklogItemResolution<StageName extends string> = {
     ignored: true;
 } | {
@@ -155,10 +161,9 @@ type BacklogItemResolution<StageName extends string> = {
 };
 type BacklogOptions<Item extends BaseBacklogItem, Stages extends Record<string, BacklogStageDefinition>> = {
     configUrl: string | URL;
-    backlogFilePath?: string;
-    doneFilePath?: string;
+    backlogItemsDir?: string;
     stages: Stages;
-    parseItem?: (item: BaseBacklogItem, index: number, raw: unknown) => Item;
+    parseItem?: (item: BaseBacklogItem, folderName: string, raw: unknown) => Item;
     resolveItem(input: {
         item: Item;
         paths: BacklogPaths;
@@ -167,8 +172,8 @@ type BacklogOptions<Item extends BaseBacklogItem, Stages extends Record<string,
 declare const BACKLOG_STAGE_VAR = "BACKLOG_STAGE";
 declare const BACKLOG_TASK_NAME_VAR = "TASK_NAME";
 declare const BACKLOG_TASK_VAR = "TASK";
-declare const BACKLOG_FILE_VAR = "BACKLOG_FILE";
-declare const BACKLOG_DONE_FILE_VAR = "DONE_FILE";
+declare const BACKLOG_ITEMS_DIR_VAR = "BACKLOG_ITEMS_DIR";
+declare const BACKLOG_ITEM_DIR_VAR = "BACKLOG_ITEM_DIR";
 
 declare function backlog<Item extends BaseBacklogItem, Stages extends Record<string, BacklogStageDefinition>>(options: BacklogOptions<Item, Stages>): LumpJsConfig;
 declare const backlogRecipe: Recipe<BacklogOptions<BaseBacklogItem, Record<string, BacklogStageDefinition>>>;
@@ -180,8 +185,8 @@ type FeatureBacklogStage = 'makePrd' | 'makeTestPlan' | 'testImpl' | 'implementa
 type FeatureBacklogContextVariables = {
     TASK_NAME: string;
     TASK: string;
-    BACKLOG_FILE: string;
-    DONE_FILE: string;
+    BACKLOG_ITEMS_DIR: string;
+    BACKLOG_ITEM_DIR: string;
     BACKLOG_STAGE: FeatureBacklogStage;
     PRD_FILE?: string;
     TEST_PLAN_FILE?: string;
@@ -189,12 +194,11 @@ type FeatureBacklogContextVariables = {
 type FeatureBacklogOptions = {
     configUrl: string | URL;
     baseBranch: string;
-    implValidateCommand: ValidationCommandFn | string;
-    backlogFilePath?: string;
-    doneFilePath?: string;
+    implValidateCommand?: ValidationCommandFn | string;
+    backlogItemsDir?: string;
 } & Omit<LumpJsConfig, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps' | 'baseBranch'>;
-declare function resolveFeatureBacklogItem(item: FeatureBacklogItem, paths: BacklogPaths$1, projectRoot: string, lumpName: string, baseBranch: string): Promise<BacklogItemResolution<FeatureBacklogStage>>;
+declare function resolveFeatureBacklogItem(item: FeatureBacklogItem, paths: BacklogPaths, projectRoot: string, lumpName: string, baseBranch: string): Promise<BacklogItemResolution<FeatureBacklogStage>>;
 declare const featureBacklog: Recipe<FeatureBacklogOptions>;
 
-export { BACKLOG_DONE_FILE_VAR, BACKLOG_FILE_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, getRecursiveSteps, lumpPathAndName, normalizeMaybePromGetter, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
-export type { AbstractionBacklogOptions, AbstractionFinderOptions, BacklogItemResolution, BacklogOptions, BacklogPaths$1 as BacklogPaths, BacklogStageDefinition, BaseBacklogItem, DoneBacklogItem, EphemeralContextListFnOptions, FeatureBacklogContextVariables, FeatureBacklogItem, FeatureBacklogOptions, FeatureBacklogStage, GetFirstStepsInput, GetRecursiveStepsOptions, ImplValidateCommand, IsValidationCommandResultOkInput, MaybePromGetter, Recipe, RetryUntilGreenInput, StepIndex, ValidationCommandFn, ValidationCommandFnInput, YmlBacklogContextsOptions };
+export { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, lumpPathAndName, normalizeMaybePromGetter, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
+export type { AbstractionBacklogOptions, AbstractionFinderOptions, BacklogItemResolution, BacklogOptions, BacklogPaths, BacklogStageDefinition, BaseBacklogItem, DoneBacklogItem, EphemeralContextListFnOptions, FeatureBacklogContextVariables, FeatureBacklogItem, FeatureBacklogOptions, FeatureBacklogStage, FolderBacklogContextsOptions, GetFirstStepsInput, GetRecursiveStepsOptions, ImplValidateCommand, IsValidationCommandResultOkInput, MaybePromGetter, Recipe, RetryUntilGreenInput, StepIndex, ValidationCommandFn, ValidationCommandFnInput, YmlBacklogContextsOptions };

package/dist/index.js

@@ -5,7 +5,7 @@ import path from 'path';
 import path$1 from 'node:path';
 import { fileURLToPath as fileURLToPath$1 } from 'node:url';
 import fs from 'fs/promises';
-import { dump, load } from 'js-yaml';
+import { load, dump } from 'js-yaml';
 
 /** Run a shell script via `sh -c` (portable on Unix-like systems and Git Bash on Windows). */
 function shellCommand(script) {
@@ -223,22 +223,188 @@ function assertProjectRelativePath(filePath, label) {
 }
 function resolveBacklogPaths(configUrl, overrides) {
     const [lumpPath, lumpName] = lumpPathAndName(configUrl);
-    const backlogFilePath = overrides?.backlogFilePath ?? path$1.join(lumpPath, 'BACKLOG.yml');
-    const doneFilePath = overrides?.doneFilePath ?? path$1.join(lumpPath, 'DONE.yml');
-    assertProjectRelativePath(backlogFilePath, 'backlogFilePath');
-    assertProjectRelativePath(doneFilePath, 'doneFilePath');
+    const backlogItemsDir = overrides?.backlogItemsDir ?? path$1.join(lumpPath, 'backlogItems');
+    assertProjectRelativePath(backlogItemsDir, 'backlogItemsDir');
     return {
         lumpPath,
         lumpName,
-        backlogFilePath,
-        doneFilePath,
+        backlogItemsDir,
     };
 }
 
+const CONTEXT_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function assertRecord(value, location) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Backlog item ${location} must be an object`);
+    }
+}
+function assertStringField(record, field, location) {
+    const value = record[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Backlog item ${location} requires non-empty string field "${field}"`);
+    }
+}
+function assertNumberField(record, field, location) {
+    const value = record[field];
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new Error(`Backlog item ${location} requires numeric field "${field}"`);
+    }
+}
+/** Validates and normalizes one backlog item; throws on invalid input. */
+function validateBaseBacklogItem(raw, location) {
+    assertRecord(raw, location);
+    assertStringField(raw, 'name', location);
+    assertStringField(raw, 'task', location);
+    assertNumberField(raw, 'priority', location);
+    if (!CONTEXT_NAME_PATTERN.test(raw.name)) {
+        throw new Error(`Backlog item ${location} has invalid name "${raw.name}" (expected ^[a-zA-Z0-9_-]+$)`);
+    }
+    let dependsOn;
+    if (raw.dependsOn !== undefined) {
+        if (!Array.isArray(raw.dependsOn)) {
+            throw new Error(`Backlog item ${location} field "dependsOn" must be an array`);
+        }
+        for (const dep of raw.dependsOn) {
+            if (typeof dep !== 'string' || dep.trim() === '') {
+                throw new Error(`Backlog item ${location} field "dependsOn" must contain non-empty strings`);
+            }
+        }
+        dependsOn = raw.dependsOn;
+    }
+    return {
+        name: raw.name,
+        task: raw.task,
+        priority: raw.priority,
+        dependsOn,
+    };
+}
+
+async function listTodoFolderNames(todoDir) {
+    try {
+        const entries = await fs.readdir(todoDir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
+    return async () => {
+        const todoDir = path$1.join(backlogItemsDir, 'todo');
+        const folderNames = await listTodoFolderNames(todoDir);
+        const discovered = await Promise.all(folderNames.map(async (folderName) => {
+            const descPath = path$1.join(todoDir, folderName, 'desc.yml');
+            let rawText;
+            try {
+                rawText = await fs.readFile(descPath, 'utf-8');
+            }
+            catch (error) {
+                const err = error;
+                if (err.code === 'ENOENT') {
+                    throw new Error(`Backlog item folder "${folderName}" is missing desc.yml at ${descPath}`);
+                }
+                throw error;
+            }
+            const raw = load(rawText);
+            const baseItem = validateBaseBacklogItem(raw, `in folder "${folderName}"`);
+            if (baseItem.name !== folderName) {
+                throw new Error(`Backlog item folder "${folderName}" desc.yml name "${baseItem.name}" must match folder name`);
+            }
+            const item = parseItem ? parseItem(baseItem, folderName, raw) : baseItem;
+            return { item, folderName };
+        }));
+        discovered.sort((a, b) => {
+            if (a.item.priority !== b.item.priority) {
+                return a.item.priority - b.item.priority;
+            }
+            return a.item.name.localeCompare(b.item.name);
+        });
+        const allCtxs = await Promise.all(discovered.map(async ({ item, folderName }) => {
+            const { parsed, ignored } = parseContext
+                ? await parseContext(item, folderName)
+                : { parsed: undefined, ignored: false };
+            if (ignored) {
+                return null;
+            }
+            return {
+                name: item.name,
+                options: {
+                    priority: item.priority,
+                    dependsOnContexts: item.dependsOn,
+                },
+                variables: parsed?.variables ?? {},
+                ...parsed,
+            };
+        }));
+        return allCtxs.filter((ctx) => !!ctx);
+    };
+}
+
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Moves a finished backlog item folder from todo/ to completed/ after the context completes. */
+const folderSetTaskDoneStep = (input) => {
+    const nameVarName = input.nameVarName ?? 'TASK_NAME';
+    return {
+        async commandFn({ context, workspacePath }) {
+            const variables = context.variables;
+            const itemsDirRelative = variables[input.itemsDirVarName];
+            const taskName = variables[nameVarName];
+            if (!itemsDirRelative || !taskName) {
+                throw new Error('Backlog items directory and task name are required');
+            }
+            const itemsDir = path$1.join(workspacePath, itemsDirRelative);
+            const fromDir = path$1.join(itemsDir, 'todo', taskName);
+            const toDir = path$1.join(itemsDir, 'completed', taskName);
+            const descPath = path$1.join(fromDir, 'desc.yml');
+            const completedDescPath = path$1.join(toDir, 'desc.yml');
+            if (!(await pathExists(fromDir))) {
+                return null;
+            }
+            if (await pathExists(toDir)) {
+                console.warn(`[lumpcode/recipes] Cannot move backlog item "${taskName}": already exists at ${toDir}`);
+                return null;
+            }
+            const rawText = await fs.readFile(descPath, 'utf-8');
+            const raw = load(rawText);
+            if (!isPlainObject(raw)) {
+                throw new Error(`Backlog desc.yml at ${descPath} must contain a YAML object`);
+            }
+            const updated = {
+                ...raw,
+                completedAt: new Date().toISOString(),
+            };
+            await fs.mkdir(path$1.join(itemsDir, 'completed'), { recursive: true });
+            await fs.rename(fromDir, toDir);
+            await fs.writeFile(completedDescPath, dump(updated));
+            return {
+                executable: 'cat',
+                args: [completedDescPath],
+            };
+        },
+        continueOnError: true,
+    };
+};
+
+let setTaskDoneDeprecatedWarned = false;
+function warnSetTaskDoneDeprecated() {
+    if (setTaskDoneDeprecatedWarned) {
+        return;
+    }
+    setTaskDoneDeprecatedWarned = true;
+    console.warn('[lumpcode/recipes] setTaskDoneStep is deprecated; use folderSetTaskDoneStep. ' +
+        'YAML backlog helpers will be removed in a future major version.');
+}
 /** Moves a finished backlog item from BACKLOG.yml to DONE.yml after the context completes. */
 const setTaskDoneStep = (input) => {
     return {
         async commandFn({ context, workspacePath }) {
+            warnSetTaskDoneDeprecated();
             const variables = context.variables;
             const { backlogVarName, doneVarName } = input;
             const baseBacklogFilePath = variables[backlogVarName];
@@ -276,62 +442,25 @@ function resolveImplValidateCommand(implValidateCommand) {
     return (_input) => implValidateCommand;
 }
 
-const CONTEXT_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
-function assertRecord(value, index) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new Error(`Backlog item at index ${index} must be an object`);
-    }
-}
-function assertStringField(record, field, index) {
-    const value = record[field];
-    if (typeof value !== 'string' || value.trim() === '') {
-        throw new Error(`Backlog item at index ${index} requires non-empty string field "${field}"`);
-    }
-}
-function assertNumberField(record, field, index) {
-    const value = record[field];
-    if (typeof value !== 'number' || Number.isNaN(value)) {
-        throw new Error(`Backlog item at index ${index} requires numeric field "${field}"`);
+let ymlBacklogDeprecatedWarned = false;
+function warnYmlBacklogDeprecated() {
+    if (ymlBacklogDeprecatedWarned) {
+        return;
     }
+    ymlBacklogDeprecatedWarned = true;
+    console.warn('[lumpcode/recipes] ymlBacklogContexts is deprecated; use folderBacklogContexts. ' +
+        'YAML backlog helpers will be removed in a future major version.');
 }
-/** Validates and normalizes one YAML backlog row; throws on invalid input. */
-function validateBaseBacklogItem(raw, index) {
-    assertRecord(raw, index);
-    assertStringField(raw, 'name', index);
-    assertStringField(raw, 'task', index);
-    assertNumberField(raw, 'priority', index);
-    if (!CONTEXT_NAME_PATTERN.test(raw.name)) {
-        throw new Error(`Backlog item at index ${index} has invalid name "${raw.name}" (expected ^[a-zA-Z0-9_-]+$)`);
-    }
-    let dependsOn;
-    if (raw.dependsOn !== undefined) {
-        if (!Array.isArray(raw.dependsOn)) {
-            throw new Error(`Backlog item at index ${index} field "dependsOn" must be an array`);
-        }
-        for (const dep of raw.dependsOn) {
-            if (typeof dep !== 'string' || dep.trim() === '') {
-                throw new Error(`Backlog item at index ${index} field "dependsOn" must contain non-empty strings`);
-            }
-        }
-        dependsOn = raw.dependsOn;
-    }
-    return {
-        name: raw.name,
-        task: raw.task,
-        priority: raw.priority,
-        dependsOn,
-    };
-}
-
 function ymlBacklogContexts({ backlogFilePath, parseItem, parseContext, }) {
     return async () => {
+        warnYmlBacklogDeprecated();
         const raw = await fs.readFile(backlogFilePath, 'utf-8');
         const doc = load(raw);
         if (!Array.isArray(doc)) {
             throw new Error(`Backlog file ${backlogFilePath} must contain a YAML list`);
         }
         const allCtxs = await Promise.all(doc.map(async (rawItem, index) => {
-            const baseItem = validateBaseBacklogItem(rawItem, index);
+            const baseItem = validateBaseBacklogItem(rawItem, `at index ${index}`);
             const item = parseItem ? parseItem(baseItem, index, rawItem) : baseItem;
             const { parsed, ignored } = parseContext
                 ? await parseContext(item, index)
@@ -359,8 +488,8 @@ function defineRecipe(recipe) {
 const BACKLOG_STAGE_VAR = 'BACKLOG_STAGE';
 const BACKLOG_TASK_NAME_VAR = 'TASK_NAME';
 const BACKLOG_TASK_VAR = 'TASK';
-const BACKLOG_FILE_VAR = 'BACKLOG_FILE';
-const BACKLOG_DONE_FILE_VAR = 'DONE_FILE';
+const BACKLOG_ITEMS_DIR_VAR = 'BACKLOG_ITEMS_DIR';
+const BACKLOG_ITEM_DIR_VAR = 'BACKLOG_ITEM_DIR';
 
 function isIgnoredResolution(resolution) {
     return 'ignored' in resolution && resolution.ignored === true;
@@ -377,27 +506,25 @@ function buildStageSteps(stages, stageName) {
     if (stageDef.completion === 'moveToDone') {
         return [
             ...normalized,
-            setTaskDoneStep({
-                backlogVarName: BACKLOG_FILE_VAR,
-                doneVarName: BACKLOG_DONE_FILE_VAR,
+            folderSetTaskDoneStep({
+                itemsDirVarName: BACKLOG_ITEMS_DIR_VAR,
             }),
         ];
     }
     return normalized;
 }
 function backlog(options) {
-    const { configUrl, backlogFilePath: backlogFilePathOverride, doneFilePath: doneFilePathOverride, stages, parseItem, resolveItem, ...rest } = options;
+    const { configUrl, backlogItemsDir: backlogItemsDirOverride, stages, parseItem, resolveItem, ...rest } = options;
     const paths = resolveBacklogPaths(configUrl, {
-        backlogFilePath: backlogFilePathOverride,
-        doneFilePath: doneFilePathOverride,
+        backlogItemsDir: backlogItemsDirOverride,
     });
     const projectRoot = projectRootFromConfigUrl(configUrl);
-    const absoluteBacklogPath = path$1.join(projectRoot, paths.backlogFilePath);
+    const absoluteBacklogItemsDir = path$1.join(projectRoot, paths.backlogItemsDir);
     return defineConfig({
-        getContextListFn: ymlBacklogContexts({
-            backlogFilePath: absoluteBacklogPath,
+        getContextListFn: folderBacklogContexts({
+            backlogItemsDir: absoluteBacklogItemsDir,
             parseItem,
-            async parseContext(item) {
+            async parseContext(item, folderName) {
                 const resolution = await resolveItem({ item, paths });
                 if (isIgnoredResolution(resolution)) {
                     return { ignored: true };
@@ -407,14 +534,15 @@ function backlog(options) {
                     ...(item.dependsOn ?? []),
                     ...(additionalDependsOnContexts ?? []),
                 ];
+                const backlogItemDir = path$1.join(paths.backlogItemsDir, 'todo', folderName);
                 return {
                     parsed: {
                         name: contextName ?? item.name,
                         variables: {
                             [BACKLOG_TASK_NAME_VAR]: item.name,
                             [BACKLOG_TASK_VAR]: item.task,
-                            [BACKLOG_FILE_VAR]: paths.backlogFilePath,
-                            [BACKLOG_DONE_FILE_VAR]: paths.doneFilePath,
+                            [BACKLOG_ITEMS_DIR_VAR]: paths.backlogItemsDir,
+                            [BACKLOG_ITEM_DIR_VAR]: backlogItemDir,
                             [BACKLOG_STAGE_VAR]: stage,
                             ...variables,
                         },
@@ -444,11 +572,11 @@ const backlogRecipe = defineRecipe((options) => backlog(options));
 const abstractionBacklog = defineRecipe((options) => {
     const { implValidateCommand, configUrl, implSteps, ...rest } = options;
     const projectRoot = projectRootFromConfigUrl(configUrl);
-    const runImplValidation = resolveImplValidateCommand(implValidateCommand);
+    const runImplValidation = resolveImplValidateCommand(implValidateCommand ?? 'echo "No implementation validation command provided. I say, trust but verify, but well..."');
     return backlog({
         configUrl,
         async resolveItem({ item, paths }) {
-            const itemPrdPath = path$1.join(paths.lumpPath, 'prds', `${item.name}.prd.md`);
+            const itemPrdPath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'prd.md');
             const hasPrd = await pathExists(path$1.join(projectRoot, itemPrdPath));
             if (!hasPrd) {
                 return { ignored: true };
@@ -492,43 +620,44 @@ const abstractionBacklog = defineRecipe((options) => {
 });
 
 const abstractionFinder = defineRecipe((options) => {
-    const { maxPendingAbstractions = 5, scanDirectories, customPrompt, backlogFilePath, prdDirPath, doneFilePath, } = options;
+    const { maxPendingAbstractions = 5, scanDirectories, customPrompt, backlogItemsDir, } = options; // TODO : check if pending abstcations in backlog are less than maxPendingAbstractions
     return defineConfig({
         ...options,
         getContextListFn: ephemeralContextListFn({
             contextCount: maxPendingAbstractions,
             variables: {
-                PRD_DIR_PATH: prdDirPath ?? '',
-                BACKLOG_FILE_PATH: backlogFilePath ?? '',
-                DONE_FILE_PATH: doneFilePath ?? '',
+                BACKLOG_ITEMS_DIR: backlogItemsDir,
             },
         }),
-        steps: buildFinderPrompt({ prdDirPath, backlogFilePath, doneFilePath, scanDirectories, customPrompt }),
+        steps: buildFinderPrompt({ backlogItemsDir, scanDirectories, customPrompt }),
     });
 });
-function buildFinderPrompt({ prdDirPath, backlogFilePath, doneFilePath, scanDirectories, customPrompt, }) {
+function buildFinderPrompt({ backlogItemsDir, scanDirectories, customPrompt, }) {
     return customPrompt ? customPrompt() : `
 Scan ${(scanDirectories || []).map((dir) => `@${dir}`).join(' and ') || 'the codebase'} for duplicated logic that appears in multiple places (same pattern, not merely similar file structure).
 
-Read @${backlogFilePath} and @${doneFilePath}. Do not propose abstractions whose util name already appears in either file.
+List existing backlog item names under @${backlogItemsDir}/todo/ and @${backlogItemsDir}/completed/. Do not propose abstractions whose util name already appears in either directory.
 
 Pick exactly one new abstraction that:
 - Has a clear util name matching ^[a-zA-Z0-9_-]+$ that describes the pattern it captures.
 - Would materialize as a new util under packages/apps/cli/src/utils/<utilName>/.
 - Would shrink the codebase: refactoring all call sites in packages/apps/cli should reduce net line count (excluding new unit tests).
 
-Add exactly one entry to @${backlogFilePath} with:
-- task: a concise summary of the repeated pattern, proposed util name, and affected areas
-- priority: max existing priority in BACKLOG.yml plus 1 (or 1 if the backlog is empty)
-- dependsOn: optional list of util names from BACKLOG.yml or DONE.yml that must land first (only when clearly needed)
-
-Write an implementation-ready PRD to @${prdDirPath}/<utilName>.prd.md for the same util name. The PRD should be self-contained and include:
-- Problem statement and repeated pattern
-- Goals and non-goals
-- Proposed util API and affected files
-- Acceptance criteria (including net line reduction and unit tests)
-
-Do not implement code. Only edit @${backlogFilePath} (append one item) and create the PRD file.
+Create exactly one new backlog item folder at @${backlogItemsDir}/todo/<utilName>/ with:
+- desc.yml containing:
+  - name: <utilName> (must match folder name)
+  - task: a concise summary of the repeated pattern, proposed util name, and affected areas
+  - priority: max existing priority in todo/ plus 1 (or 1 if todo/ is empty)
+  - dependsOn: optional list of util names from todo/ or completed/ that must land first (only when clearly needed)
+- prd.md: an implementation-ready PRD for the same util name. The PRD should be self-contained and include:
+  - Problem statement and repeated pattern
+  - Goals and non-goals
+  - Proposed util API and affected files
+  - Acceptance criteria (including net line reduction and unit tests)
+
+Do not implement code. Only create @${backlogItemsDir}/todo/<utilName>/desc.yml and @${backlogItemsDir}/todo/<utilName>/prd.md.
+
+Do not take too much time looking for every possible abstraction. Once you found a good abstraction, stop and create the backlog item.
     `.trim();
 }
 
@@ -557,8 +686,8 @@ function featureContextName(itemName, stage) {
     }
 }
 async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, baseBranch) {
-    const prdFilePath = path$1.join(paths.lumpPath, 'prds', `${item.name}.prd.md`);
-    const testPlanFilePath = path$1.join(paths.lumpPath, 'testPlans', `${item.name}.test.md`);
+    const prdFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'prd.md');
+    const testPlanFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'testPlan.md');
     const hasPrd = await pathExists(path$1.join(projectRoot, prdFilePath));
     if (!hasPrd) {
         if (item.manualPrd === true) {
@@ -611,15 +740,14 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
     };
 }
 const featureBacklog = defineRecipe((options) => {
-    const { configUrl, baseBranch, implValidateCommand, backlogFilePath, doneFilePath, ...rest } = options;
+    const { configUrl, baseBranch, implValidateCommand, backlogItemsDir, ...rest } = options;
     const projectRoot = projectRootFromConfigUrl(configUrl);
-    const runImplValidation = resolveImplValidateCommand(implValidateCommand);
+    const runImplValidation = resolveImplValidateCommand(implValidateCommand ?? 'echo "No implementation validation command provided. I say, trust but verify, but well..."');
     return backlog({
         configUrl,
-        backlogFilePath,
-        doneFilePath,
+        backlogItemsDir,
         baseBranch,
-        parseItem(baseItem, _index, raw) {
+        parseItem(baseItem, _folderName, raw) {
             assertValidFeatureItemName(baseItem.name);
             const record = raw;
             if (record.manualPrd !== undefined && typeof record.manualPrd !== 'boolean') {
@@ -640,16 +768,16 @@ const featureBacklog = defineRecipe((options) => {
                     {
                         promptFn({ context: ctx }) {
                             const vars = ctx.variables;
-                            const { BACKLOG_FILE, TASK_NAME, TASK, PRD_FILE } = vars;
+                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, PRD_FILE } = vars;
                             return `
-Write a product requirements document (PRD) for the following Lumpcode backlog item from @${BACKLOG_FILE}.
+Write a product requirements document (PRD) for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
 
 Task name: ${TASK_NAME}
 
 Task:
 ${TASK}
 
-Save the PRD to @${PRD_FILE}. Do not edit @${BACKLOG_FILE}.
+Save the PRD to @${PRD_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml.
 
 The PRD should be self-contained and implementation-ready. Include:
 - Problem statement and motivation
@@ -674,9 +802,9 @@ The PRD should not contain any testing strategy details.
                     {
                         promptFn({ context: ctx }) {
                             const vars = ctx.variables;
-                            const { BACKLOG_FILE, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
+                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
                             return `
-Write a test plan for the following Lumpcode backlog item from @${BACKLOG_FILE}.
+Write a test plan for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
 
 Task name: ${TASK_NAME}
 Task:
@@ -684,7 +812,7 @@ ${TASK}
 
 The PRD for this task is @${PRD_FILE}. The test plan should match the requirements of the PRD.
 
-Save the test plan to @${TEST_PLAN_FILE}. Do not edit @${BACKLOG_FILE} nor @${PRD_FILE}.
+Save the test plan to @${TEST_PLAN_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml nor @${PRD_FILE}.
 
 The test plan should be self-contained and implementation-ready. Include:
 - Test cases
@@ -703,9 +831,9 @@ The test plan should be self-contained and implementation-ready. Include:
                     {
                         promptFn({ context: ctx }) {
                             const vars = ctx.variables;
-                            const { BACKLOG_FILE, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
+                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, PRD_FILE, TEST_PLAN_FILE } = vars;
                             return `
-Write a test implementation for the following Lumpcode backlog item from @${BACKLOG_FILE}.
+Write a test implementation for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
 
 Task name: ${TASK_NAME}
 Task:
@@ -742,4 +870,4 @@ The implementation should make the tests pass. Do not edit any test file.
     });
 });
 
-export { BACKLOG_DONE_FILE_VAR, BACKLOG_FILE_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, getRecursiveSteps, lumpPathAndName, normalizeMaybePromGetter, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
+export { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, lumpPathAndName, normalizeMaybePromGetter, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumpcode/recipes",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Lumpcode lump recipes and kit helpers",
   "keywords": [
     "lumpcode",