@lumpcode/recipes 0.2.0 → 0.3.1

package/README.md

@@ -15,8 +15,8 @@ npm install @lumpcode/recipes
 | Recipe | Export | Use when |
 |--------|--------|----------|
 | **backlog** | `backlog` | Generic folder backlog with a typed stage map and per-item stage resolution |
-| **featureBacklog** | `featureBacklog` | Feature items with requirements → test plan → test implementation → implementation |
-| **abstractionFinder** | `abstractionFinder` | Ephemeral contexts that scan for duplicated CLI utils and append one backlog item + requirements doc per run |
+| **featureBacklog** | `featureBacklog` | Folder feature campaign: TDD stages, optional `directImpl`, tickets, and `dev` / `feature/*` discovery |
+| **abstractionFinder** | `abstractionFinder` | One ephemeral context per tick that appends a backlog item + requirements doc while `todo/` is under `maxPendingAbstractions` |
 | **abstractionBacklog** | `abstractionBacklog` | Folder backlog items with requirements — implement abstraction with verify-until-green, then move item to completed/ |
 
 Recipe factories and variable-carrying kit helpers accept the same dual generics as `defineConfig` from `@lumpcode/cli-utils`: `<V extends LumpVariables, SV extends StepVariables>`, with defaults equal to the unbound bags. Pass explicit type args when refining preset contracts; omit them for classic untyped configs.
@@ -29,13 +29,14 @@ The backlog recipes (`backlog`, `featureBacklog`, `abstractionBacklog`) use a fo
 .lumpcode/lumps/<lump>/backlogItems/
   todo/<name>/desc.yml
   todo/<name>/requirements.md # optional until makeReq / finder writes it
-  todo/<name>/testPlan.md     # featureBacklog only; optional until makeTestPlan
+  todo/<name>/testPlan.md     # featureBacklog TDD; optional until makeTestPlan
+  todo/<parent>/tickets/<ticket>/desc.yml  # featureBacklog: parent skipped when tickets/ is non-empty
   completed/<name>/desc.yml   # includes completedAt after move-to-done
   completed/<name>/requirements.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. `manualReq` for featureBacklog).
+`desc.yml` is a single YAML object with `name`, `task`, `priority`, optional `dependsOn`, and recipe-specific fields (`manualReq`, `workflow` for featureBacklog).
 
 ## Kit
 
@@ -45,11 +46,21 @@ Flat helpers under `src/kit/` (re-exported from the package root):
 - `getRecursiveSteps` — agent step(s) + validation command, retry until pass (retries via `postCommandExecFn` returned steps)
 - `retryUntilGreen` — opinionated wrapper over `getRecursiveSteps` with default fix prompt
 - `ephemeralContextListFn` — N fresh synthetic contexts per run (`contextCount`, index-aware names)
-- `folderBacklogContexts` — `getContextListFn` from `backlogItems/todo/` with optional per-item parsing
+- `folderBacklogContexts` — `getContextListFn` from `backlogItems/todo/` with optional per-item parsing (`listTodoRelativeDirs` lists todo-relative item folders, including tickets)
 - `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
+- `openPrPostTeardown` — `postTeardownWorkspaceFn` that opens a PR from `branchName` into resolved `baseBranch`. Pass `{ provider: 'github' }` (`gh` on PATH). Skips when the branch was not pushed or a PR already exists; create failures are logged and do not fail the run.
+
+```ts
+import { featureBacklog, openPrPostTeardown } from '@lumpcode/recipes';
+
+export default featureBacklog({
+  configUrl: import.meta.url,
+  postTeardownWorkspaceFn: openPrPostTeardown({ provider: 'github' }),
+});
+```
 
 ## Generic backlog stage map
 
@@ -92,15 +103,14 @@ export default featureBacklog<
     CursorPresetLumpVariables,
     CursorPresetStepVariables
 >({
-    baseBranch: 'dev',
     command: 'cursor',
     configUrl: import.meta.url,
     registerCommands: ['cursor'],
-    maximumNumberOfConcurrentBranches: 5,
+    maximumNumberOfConcurrentBranches: 1,
     verbose: true,
     keepHistory: true,
     lumpVariables: { model: 'composer-2.5' },
-    discoveryBranch: 'dev',
+    discoveryBranches: ['dev', 'feature/*'],
     implValidateCommand: [
         'npm run build -w=@lumpcode/cli',
         'npm run test -w=@lumpcode/cli',
@@ -108,6 +118,8 @@ export default featureBacklog<
 });
 ```
 
+`desc.yml` `workflow`: omit ≡ `tdd` (`makeReq` → `makeTestPlan` → `testImpl` → `implementation`); `directImpl` skips the test-plan stages; `manual` is ignored. On `dev` only top-level `directImpl` items run (tickets never run on `dev`, even if `directImpl`); on `feature/<key>` the matching item (or parent, for tickets). Ticket context names are `<parent>-<ticket>`; `manualReq: true` waits for a human requirements file. Status reads use the concrete `discoveryBranch`.
+
 ### abstractionFinder + abstractionBacklog
 
 Two-lump pipeline: finder tops up the implementer backlog; implementer runs items that already have requirements documents.
@@ -124,15 +136,19 @@ export default abstractionFinder<
     CursorPresetLumpVariables,
     CursorPresetStepVariables
 >({
+    configUrl: import.meta.url,
     maxPendingAbstractions: 5,
-    scanDirectories: ['packages/apps/cli'],
+    scanDirectories: ['src'],
     backlogItemsDir: '.lumpcode/lumps/abstractionImplementer/backlogItems',
     command: 'cursor',
     lumpVariables: { model: 'composer-2.5' },
     discoveryBranch: 'dev',
+    scanCommand: 'npx fallow dupes --mode semantic --format json > .lumpcode/dupes.json',
 });
 ```
 
+`maxPendingAbstractions` caps unmerged `todo/` items (one finder context per tick while under the cap). `scanCommand` runs before the default prompt. Pass `steps` to replace the prompt (the scanner still prepends). `configUrl: import.meta.url` is required so the recipe can count pending items from the project root.
+
 ```ts
 // .lumpcode/lumps/abstractionImplementer/config.ts
 import {

package/dist/index.cjs

@@ -8,6 +8,7 @@ var path$1 = require('node:path');
 var node_url = require('node:url');
 var fs = require('fs/promises');
 var jsYaml = require('js-yaml');
+var fs$1 = require('node:fs/promises');
 
 /** Run a shell script via `sh -c` (portable on Unix-like systems and Git Bash on Windows). */
 function shellCommand(script) {
@@ -17,6 +18,111 @@ function shellCommand(script) {
     };
 }
 
+const LOG_PREFIX = '[lumpcode/recipes]';
+async function openGithubPr(input) {
+    const { workspacePath, baseBranch, branchName, title, body } = input;
+    const cwd = workspacePath;
+    const listed = await core.execBinary({
+        binaryPath: 'gh',
+        args: ['pr', 'list', '--head', branchName, '--base', baseBranch, '--json', 'number'],
+        cwd,
+    });
+    if (listed.success && githubPrListHasItems(listed.data.stdout)) {
+        return;
+    }
+    const created = await core.execBinary({
+        binaryPath: 'gh',
+        args: [
+            'pr',
+            'create',
+            '--base',
+            baseBranch,
+            '--head',
+            branchName,
+            '--title',
+            title,
+            '--body',
+            body,
+        ],
+        cwd,
+    });
+    if (!created.success) {
+        console.error(`${LOG_PREFIX} gh pr create failed: ${created.data.message}`);
+    }
+}
+function githubPrListHasItems(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) && parsed.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+
+const LUMP_BRANCH_PREFIX = 'lump/';
+const OPEN_PR_PROVIDERS = ['github'];
+function openPrPostTeardown(options) {
+    const { provider, lumpName: lumpNameOption, title, body } = options;
+    return async (input) => {
+        const { baseBranch, branchName, contextList, workspacePath } = input;
+        if (!branchName || branchName === baseBranch) {
+            return;
+        }
+        const remote = await core.execBinary({
+            binaryPath: 'git',
+            args: ['ls-remote', '--heads', 'origin', branchName],
+            cwd: workspacePath,
+        });
+        if (!remote.success || !remote.data.stdout.trim()) {
+            return;
+        }
+        const names = contextList.map((ctx) => ctx.name).filter((name) => name.length > 0);
+        const label = names.length > 0 ? names.join(', ') : branchName;
+        const lumpName = lumpNameOption ?? lumpNameFromBranch(branchName);
+        const resolvedTitle = title?.(input) ?? defaultPrTitle({ lumpName, label });
+        const resolvedBody = body?.(input) ?? `LUMP contexts: ${label}`;
+        await openPrWithProvider({
+            provider,
+            workspacePath,
+            baseBranch,
+            branchName,
+            title: resolvedTitle,
+            body: resolvedBody,
+        });
+    };
+}
+function defaultPrTitle(input) {
+    const { lumpName, label } = input;
+    if (lumpName) {
+        return cliUtils.getGitCommitMessage({ lumpName, contextName: label });
+    }
+    return `LUMP: ${label}`;
+}
+function lumpNameFromBranch(branchName) {
+    if (!branchName.startsWith(LUMP_BRANCH_PREFIX)) {
+        return undefined;
+    }
+    const rest = branchName.slice(LUMP_BRANCH_PREFIX.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0) {
+        return undefined;
+    }
+    return rest.slice(0, slash);
+}
+async function openPrWithProvider(input) {
+    const { provider, ...prInput } = input;
+    switch (provider) {
+        case 'github':
+            await openGithubPr(prInput);
+            return;
+        default: {
+            const _exhaustive = provider;
+            throw new Error(`Unhandled PR provider: ${_exhaustive}`);
+        }
+    }
+}
+
 function normalizeMaybePromGetter(maybePromGetter, defaultValue) {
     if (typeof maybePromGetter === 'function') {
         return maybePromGetter;
@@ -286,10 +392,26 @@ async function listTodoFolderNames(todoDir) {
         throw error;
     }
 }
+/** Path relative to `todo/`, using `/` so it is stable in context variables. */
+async function listTodoRelativeDirs(todoDir) {
+    const topNames = await listTodoFolderNames(todoDir);
+    const relativeDirs = [];
+    for (const name of topNames) {
+        const ticketNames = await listTodoFolderNames(path$1.join(todoDir, name, 'tickets'));
+        if (ticketNames.length === 0) {
+            relativeDirs.push(name);
+            continue;
+        }
+        for (const ticketName of ticketNames) {
+            relativeDirs.push(`${name}/tickets/${ticketName}`);
+        }
+    }
+    return relativeDirs;
+}
 function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
     return async () => {
         const todoDir = path$1.join(backlogItemsDir, 'todo');
-        const folderNames = await listTodoFolderNames(todoDir);
+        const folderNames = await listTodoRelativeDirs(todoDir);
         const discovered = await Promise.all(folderNames.map(async (folderName) => {
             const descPath = path$1.join(todoDir, folderName, 'desc.yml');
             let rawText;
@@ -304,13 +426,22 @@ function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
                 throw error;
             }
             const raw = jsYaml.load(rawText);
+            const itemFolderName = path$1.basename(folderName);
             const baseItem = validateBaseBacklogItem(raw, `in folder "${folderName}"`);
-            if (baseItem.name !== folderName) {
+            if (baseItem.name !== itemFolderName) {
                 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 };
         }));
+        const seenNames = new Map();
+        for (const { item, folderName } of discovered) {
+            const previous = seenNames.get(item.name);
+            if (previous !== undefined) {
+                throw new Error(`Duplicate backlog item name "${item.name}" in folders "${previous}" and "${folderName}"`);
+            }
+            seenNames.set(item.name, folderName);
+        }
         discovered.sort((a, b) => {
             if (a.item.priority !== b.item.priority) {
                 return a.item.priority - b.item.priority;
@@ -341,7 +472,7 @@ function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
 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. */
+/** Moves a finished backlog item folder from todo/ to the same relative path under completed/. */
 function folderSetTaskDoneStep(input) {
     const nameVarName = input.nameVarName ?? 'TASK_NAME';
     return {
@@ -349,19 +480,29 @@ function folderSetTaskDoneStep(input) {
             const variables = context.variables;
             const itemsDirRelative = variables[input.itemsDirVarName];
             const taskName = variables[nameVarName];
-            if (!itemsDirRelative || !taskName) {
+            const itemDirRelative = variables.BACKLOG_ITEM_DIR;
+            if (!itemsDirRelative || (!itemDirRelative && !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 todoDir = path$1.join(itemsDir, 'todo');
+            const fromDir = itemDirRelative
+                ? path$1.join(workspacePath, itemDirRelative)
+                : path$1.join(todoDir, taskName);
+            const relativeFromTodo = path$1.relative(todoDir, fromDir);
+            if (relativeFromTodo === '' ||
+                relativeFromTodo.startsWith('..') ||
+                path$1.isAbsolute(relativeFromTodo)) {
+                throw new Error(`BACKLOG_ITEM_DIR must be a folder under ${todoDir}: ${itemDirRelative ?? fromDir}`);
+            }
+            const toDir = path$1.join(itemsDir, 'completed', relativeFromTodo);
             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}`);
+                console.warn(`[lumpcode/recipes] Cannot move backlog item "${taskName ?? relativeFromTodo}": already exists at ${toDir}`);
                 return null;
             }
             const rawText = await fs.readFile(descPath, 'utf-8');
@@ -373,7 +514,7 @@ function folderSetTaskDoneStep(input) {
                 ...raw,
                 completedAt: new Date().toISOString(),
             };
-            await fs.mkdir(path$1.join(itemsDir, 'completed'), { recursive: true });
+            await fs.mkdir(path$1.dirname(toDir), { recursive: true });
             await fs.rename(fromDir, toDir);
             await fs.writeFile(completedDescPath, jsYaml.dump(updated));
             return {
@@ -622,29 +763,72 @@ const abstractionBacklog = defineRecipe(function abstractionBacklog(options) {
     });
 });
 
+function scanCommandStep(scanCommand) {
+    if (typeof scanCommand === 'function') {
+        return { commandFn: scanCommand };
+    }
+    if (typeof scanCommand === 'string') {
+        return { commandFn: () => shellCommand(scanCommand) };
+    }
+    return { commandFn: () => scanCommand };
+}
 const abstractionFinder = defineRecipe(function abstractionFinder(options) {
-    const { maxPendingAbstractions = 5, scanDirectories, customPrompt, backlogItemsDir, } = options; // TODO : check if pending abstcations in backlog are less than maxPendingAbstractions
+    const { configUrl, maxPendingAbstractions = 5, scanDirectories, utilDir, customPrompt, backlogItemsDir, scanCommand, steps: stepsOverride, ...rest } = options;
+    if (path$1.isAbsolute(backlogItemsDir)) {
+        throw new Error(`backlogItemsDir must be project-root-relative, not absolute: ${backlogItemsDir}`);
+    }
+    const projectRoot = projectRootFromConfigUrl(configUrl);
+    const todoDir = path$1.join(projectRoot, backlogItemsDir, 'todo');
+    const agentSteps = stepsOverride ?? buildFinderPrompt({
+        backlogItemsDir,
+        scanDirectories,
+        utilDir,
+        customPrompt,
+    });
+    const steps = [
+        ...(scanCommand === undefined ? [] : [scanCommandStep(scanCommand)]),
+        ...cliUtils.normalizeSteps({
+            prompt: undefined,
+            jsSteps: agentSteps,
+        }),
+    ];
     return cliUtils.defineConfig({
-        ...options,
+        ...rest,
         getContextListFn: ephemeralContextListFn({
-            contextCount: maxPendingAbstractions,
+            async contextCount() {
+                const pending = (await listTodoRelativeDirs(todoDir)).length;
+                return pending >= maxPendingAbstractions ? 0 : 1;
+            },
             variables: {
                 BACKLOG_ITEMS_DIR: backlogItemsDir,
             },
         }),
-        steps: buildFinderPrompt({ backlogItemsDir, scanDirectories, customPrompt }),
+        steps,
     });
 });
-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).
+function buildFinderPrompt({ backlogItemsDir, scanDirectories, utilDir, customPrompt, }) {
+    if (customPrompt) {
+        return customPrompt();
+    }
+    const scanLabel = scanDirectories && scanDirectories.length > 0
+        ? scanDirectories.map((dir) => `@${dir}`).join(' and ')
+        : 'the codebase';
+    const materializeDir = utilDir ?? scanDirectories?.[0];
+    const materializeLine = materializeDir
+        ? `- Would materialize as a new util under @${materializeDir}/<utilName>/, following existing conventions there.`
+        : '- Would materialize as a new util in the scanned tree, following existing conventions there.';
+    const refactorScope = scanDirectories && scanDirectories.length > 0
+        ? scanDirectories.join(' and ')
+        : 'the scanned tree';
+    return `
+Scan ${scanLabel} for duplicated logic that appears in multiple places (same pattern, not merely similar file structure).
 
 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).
+${materializeLine}
+- Would shrink the codebase: refactoring all call sites in ${refactorScope} should reduce net line count (excluding new unit tests).
 
 Create exactly one new backlog item folder at @${backlogItemsDir}/todo/<utilName>/ with:
 - desc.yml containing:
@@ -664,6 +848,11 @@ Do not take too much time looking for every possible abstraction. Once you found
     `.trim();
 }
 
+const FEATURE_BACKLOG_WORKFLOWS = [
+    'tdd',
+    'directImpl',
+    'manual',
+];
 const RESERVED_NAME_SUFFIXES = ['_req', '_testPlan', '_tests_impl'];
 function assertValidFeatureItemName(name) {
     for (const suffix of RESERVED_NAME_SUFFIXES) {
@@ -672,6 +861,9 @@ function assertValidFeatureItemName(name) {
         }
     }
 }
+function featureItemContextBaseName(item) {
+    return item.parentName ? `${item.parentName}-${item.name}` : item.name;
+}
 function featureContextName(itemName, stage) {
     switch (stage) {
         case 'makeReq':
@@ -681,6 +873,7 @@ function featureContextName(itemName, stage) {
         case 'testImpl':
             return `${itemName}_tests_impl`;
         case 'implementation':
+        case 'directImpl':
             return itemName;
         default: {
             const _exhaustive = stage;
@@ -688,9 +881,84 @@ function featureContextName(itemName, stage) {
         }
     }
 }
-async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, baseBranch) {
-    const reqFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'requirements.md');
-    const testPlanFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'testPlan.md');
+function parentNameFromTodoRelativeDir(todoRelativeDir) {
+    const parts = todoRelativeDir.split('/');
+    if (parts.length === 3 && parts[1] === 'tickets') {
+        return parts[0];
+    }
+    return undefined;
+}
+function parseFeatureWorkflow(itemName, raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    if (record.workflow === undefined) {
+        return undefined;
+    }
+    if (typeof record.workflow !== 'string' ||
+        !FEATURE_BACKLOG_WORKFLOWS.includes(record.workflow)) {
+        throw new Error(`Backlog item "${itemName}" field "workflow" must be one of: ${FEATURE_BACKLOG_WORKFLOWS.join(', ')}`);
+    }
+    return record.workflow;
+}
+async function resolveItemWorkflow(input) {
+    const { item, paths, projectRoot } = input;
+    if (item.workflow !== undefined) {
+        return item.workflow;
+    }
+    if (item.parentName === undefined) {
+        return 'tdd';
+    }
+    const parentDescPath = path$1.join(projectRoot, paths.backlogItemsDir, 'todo', item.parentName, 'desc.yml');
+    let rawText;
+    try {
+        rawText = await fs$1.readFile(parentDescPath, 'utf-8');
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return 'tdd';
+        }
+        throw error;
+    }
+    return parseFeatureWorkflow(item.parentName, jsYaml.load(rawText)) ?? 'tdd';
+}
+/**
+ * `dev` → only top-level `directImpl` (tickets never run on `dev`, even if `directImpl`).
+ * `feature/<key>` → exact item name, or the parent todo name for tickets.
+ * `manual` never reaches here (`resolveFeatureBacklogItem` ignores it first).
+ */
+function itemMatchesDiscoveryBranch(input) {
+    const { itemName, parentName, discoveryBranch, workflow } = input;
+    if (discoveryBranch === 'dev') {
+        return workflow === 'directImpl' && parentName === undefined;
+    }
+    if (!discoveryBranch.startsWith('feature/')) {
+        return false;
+    }
+    const key = discoveryBranch.slice('feature/'.length);
+    return (parentName ?? itemName) === key;
+}
+async function resolveFeatureBacklogItem(input) {
+    const { item, paths, projectRoot, discoveryBranch } = input;
+    const contextBaseName = featureItemContextBaseName(item);
+    const workflow = await resolveItemWorkflow({ item, paths, projectRoot });
+    if (workflow === 'manual') {
+        return { ignored: true };
+    }
+    if (!!item.completedAt ||
+        !itemMatchesDiscoveryBranch({
+            itemName: item.name,
+            parentName: item.parentName,
+            discoveryBranch,
+            workflow,
+        })) {
+        return { ignored: true };
+    }
+    const itemDir = path$1.join(paths.backlogItemsDir, 'todo', item.todoRelativeDir);
+    const reqFilePath = path$1.join(itemDir, 'requirements.md');
+    const testPlanFilePath = path$1.join(itemDir, 'testPlan.md');
     const hasReq = await core.pathExists(path$1.join(projectRoot, reqFilePath));
     if (!hasReq) {
         if (item.manualReq === true) {
@@ -698,7 +966,14 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
         }
         return {
             stage: 'makeReq',
-            contextName: featureContextName(item.name, 'makeReq'),
+            contextName: featureContextName(contextBaseName, 'makeReq'),
+            variables: { REQ_FILE: reqFilePath },
+        };
+    }
+    if (workflow === 'directImpl') {
+        return {
+            stage: 'directImpl',
+            contextName: featureContextName(contextBaseName, 'directImpl'),
             variables: { REQ_FILE: reqFilePath },
         };
     }
@@ -706,24 +981,24 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
     if (!hasTestPlan) {
         return {
             stage: 'makeTestPlan',
-            contextName: featureContextName(item.name, 'makeTestPlan'),
+            contextName: featureContextName(contextBaseName, 'makeTestPlan'),
             variables: {
                 REQ_FILE: reqFilePath,
                 TEST_PLAN_FILE: testPlanFilePath,
             },
         };
     }
-    const testsImplContextName = featureContextName(item.name, 'testImpl');
+    const testsImplContextName = featureContextName(contextBaseName, 'testImpl');
     const testsImplStatus = await cliUtils.getContextStatus({
         projectRoot,
         contextName: testsImplContextName,
-        lumpName,
-        baseBranch,
+        lumpName: paths.lumpName,
+        baseBranch: discoveryBranch,
     });
     if (testsImplStatus === 'finished') {
         return {
             stage: 'implementation',
-            contextName: featureContextName(item.name, 'implementation'),
+            contextName: featureContextName(contextBaseName, 'implementation'),
             variables: {
                 REQ_FILE: reqFilePath,
                 TEST_PLAN_FILE: testPlanFilePath,
@@ -743,27 +1018,38 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
     };
 }
 const featureBacklog = defineRecipe(function featureBacklog(options) {
-    const { configUrl, baseBranch, implValidateCommand, backlogItemsDir, ...rest } = options;
+    const { configUrl, implValidateCommand, backlogItemsDir, ...rest } = options;
     const projectRoot = projectRootFromConfigUrl(configUrl);
     const runImplValidation = resolveImplValidateCommand(implValidateCommand ??
         'echo "No implementation validation command provided. I say, trust but verify, but well..."');
     return backlog({
         configUrl,
         backlogItemsDir,
-        baseBranch,
-        parseItem(baseItem, _folderName, raw) {
+        parseItem(baseItem, folderName, raw) {
             assertValidFeatureItemName(baseItem.name);
             const record = raw;
             if (record.manualReq !== undefined && typeof record.manualReq !== 'boolean') {
                 throw new Error(`Backlog item "${baseItem.name}" field "manualReq" must be a boolean`);
             }
+            const parentName = parentNameFromTodoRelativeDir(folderName);
             return {
                 ...baseItem,
+                todoRelativeDir: folderName,
+                parentName,
+                dependsOn: parentName
+                    ? baseItem.dependsOn?.map((dep) => `${parentName}-${dep}`)
+                    : baseItem.dependsOn,
                 manualReq: record.manualReq === true ? true : undefined,
+                workflow: parseFeatureWorkflow(baseItem.name, raw),
             };
         },
-        async resolveItem({ item, paths }) {
-            return resolveFeatureBacklogItem(item, paths, projectRoot, paths.lumpName, baseBranch);
+        async resolveItem({ item, paths, discoveryBranch }) {
+            return resolveFeatureBacklogItem({
+                item,
+                paths,
+                projectRoot,
+                discoveryBranch,
+            });
         },
         stages: {
             makeReq: {
@@ -912,6 +1198,25 @@ The implementation should make the tests pass. Do not edit any test file except
                     validationCommandFn: runImplValidation,
                 }),
             },
+            directImpl: {
+                completion: 'moveToDone',
+                steps: retryUntilGreen({
+                    steps: [
+                        {
+                            promptFn({ context: ctx }) {
+                                const vars = ctx.variables;
+                                const { REQ_FILE } = vars;
+                                return `
+Implement the feature described in @${REQ_FILE}.
+Add or update tests as needed so the suite covers the change, and make validation pass.
+Do not edit @${REQ_FILE} unless absolutely necessary.
+                                `.trim();
+                            },
+                        },
+                    ],
+                    validationCommandFn: runImplValidation,
+                }),
+            },
         },
         ...rest,
     });
@@ -922,6 +1227,8 @@ 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;
+exports.FEATURE_BACKLOG_WORKFLOWS = FEATURE_BACKLOG_WORKFLOWS;
+exports.OPEN_PR_PROVIDERS = OPEN_PR_PROVIDERS;
 exports.abstractionBacklog = abstractionBacklog;
 exports.abstractionFinder = abstractionFinder;
 exports.backlog = backlog;
@@ -932,8 +1239,11 @@ exports.featureBacklog = featureBacklog;
 exports.folderBacklogContexts = folderBacklogContexts;
 exports.folderSetTaskDoneStep = folderSetTaskDoneStep;
 exports.getRecursiveSteps = getRecursiveSteps;
+exports.listTodoRelativeDirs = listTodoRelativeDirs;
 exports.lumpPathAndName = lumpPathAndName;
 exports.normalizeMaybePromGetter = normalizeMaybePromGetter;
+exports.openPrPostTeardown = openPrPostTeardown;
+exports.parseFeatureWorkflow = parseFeatureWorkflow;
 exports.projectRootFromConfigUrl = projectRootFromConfigUrl;
 exports.requireArtifactStep = requireArtifactStep;
 exports.resolveBacklogPaths = resolveBacklogPaths;

package/dist/index.d.ts

@@ -1,9 +1,20 @@
 import { CommandDescriptor, MaybePromise, PostCommandExecFn, Step } from '@lumpcode/core';
-import { LumpVariables, GetContextListFnInput, GetContextListFn, StepVariables, CommandFn, LumpJsConfig, LumpJsConfigSteps, MaybePromise as MaybePromise$1, Context } from '@lumpcode/cli-utils';
+import { LumpVariables, PostSetupWorkspaceFnInput, PostTeardownWorkspaceFn, GetContextListFnInput, GetContextListFn, StepVariables, CommandFn, LumpJsConfig, LumpJsConfigSteps, MaybePromise as MaybePromise$1, Context } from '@lumpcode/cli-utils';
 
 /** Run a shell script via `sh -c` (portable on Unix-like systems and Git Bash on Windows). */
 declare function shellCommand(script: string): CommandDescriptor;
 
+declare const OPEN_PR_PROVIDERS: readonly ["github"];
+type OpenPrProvider = (typeof OPEN_PR_PROVIDERS)[number];
+type OpenPrPostTeardownOptions<V extends LumpVariables = LumpVariables> = {
+    provider: OpenPrProvider;
+    /** Overrides the lump name parsed from `lump/<lumpName>/…` branches. */
+    lumpName?: string;
+    title?: (input: PostSetupWorkspaceFnInput<V>) => string;
+    body?: (input: PostSetupWorkspaceFnInput<V>) => string;
+};
+declare function openPrPostTeardown<V extends LumpVariables = LumpVariables>(options: OpenPrPostTeardownOptions<V>): PostTeardownWorkspaceFn<V>;
+
 type MaybePromGetter<T, P = void> = T | ((input: P) => MaybePromise<T>);
 declare function normalizeMaybePromGetter<T, P = void>(maybePromGetter: MaybePromGetter<T, P>): (input: P) => MaybePromise<T>;
 declare function normalizeMaybePromGetter<T, P = void>(maybePromGetter: MaybePromGetter<T, P> | undefined, defaultValue: T): (input?: P) => MaybePromise<T>;
@@ -92,15 +103,21 @@ type DoneBacklogItem<T extends BaseBacklogItem = BaseBacklogItem> = T & {
 
 type FolderBacklogContextsOptions<Item extends BaseBacklogItem = BaseBacklogItem> = {
     backlogItemsDir: string;
+    /**
+     * `folderName` is the path relative to `todo/`: the item folder, or
+     * `<parent>/tickets/<ticket>` when the parent has a `tickets/` directory.
+     */
     parseItem?: (item: BaseBacklogItem, folderName: string, raw: unknown) => Item;
     parseContext?: (item: Item, folderName: string) => MaybePromise$1<{
         parsed?: Partial<Context>;
         ignored?: boolean;
     }>;
 };
+/** Path relative to `todo/`, using `/` so it is stable in context variables. */
+declare function listTodoRelativeDirs(todoDir: string): Promise<string[]>;
 declare function folderBacklogContexts<Item extends BaseBacklogItem = BaseBacklogItem, V extends LumpVariables = LumpVariables>({ backlogItemsDir, parseItem, parseContext, }: FolderBacklogContextsOptions<Item>): GetContextListFn<V>;
 
-/** Moves a finished backlog item folder from todo/ to completed/ after the context completes. */
+/** Moves a finished backlog item folder from todo/ to the same relative path under completed/. */
 declare function folderSetTaskDoneStep<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>(input: {
     itemsDirVarName: string;
     nameVarName?: string;
@@ -136,12 +153,20 @@ type AbstractionBacklogOptions<V extends LumpVariables = LumpVariables, SV exten
 } & Omit<LumpJsConfig<V, SV>, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps'>;
 declare const abstractionBacklog: <V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>(options: AbstractionBacklogOptions<V, SV>) => LumpJsConfig<V, SV>;
 
+type AbstractionFinderScanCommand<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = string | CommandDescriptor | CommandFn<V, SV>;
 type AbstractionFinderOptions<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = {
+    /** Lump config module URL — pass `import.meta.url` from `config.ts`. */
+    configUrl: string | URL;
     scanDirectories?: string[];
+    /** Optional util output directory (project-root-relative). Defaults to the first scan directory. */
+    utilDir?: string;
     customPrompt?(): string;
+    /** Max unmerged items under `backlogItemsDir/todo/`. Finder emits one context per tick while under the cap. */
     maxPendingAbstractions?: number;
     backlogItemsDir: string;
-} & LumpJsConfig<V, SV>;
+    /** Optional scanner command prepended before the prompt (e.g. a dupes report). */
+    scanCommand?: AbstractionFinderScanCommand<V, SV>;
+} & Omit<LumpJsConfig<V, SV>, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt'>;
 declare const abstractionFinder: <V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>(options: AbstractionFinderOptions<V, SV>) => LumpJsConfig<V, SV>;
 
 type BacklogStageDefinition<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = {
@@ -178,10 +203,18 @@ declare const BACKLOG_ITEM_DIR_VAR = "BACKLOG_ITEM_DIR";
 declare function backlog<Item extends BaseBacklogItem, V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables, Stages extends Record<string, BacklogStageDefinition<V, SV>> = Record<string, BacklogStageDefinition<V, SV>>>(options: BacklogOptions<Item, V, SV, Stages>): LumpJsConfig<V, SV>;
 declare const backlogRecipe: typeof backlog;
 
+type FeatureBacklogWorkflow = 'tdd' | 'directImpl' | 'manual';
+type FeatureBacklogRunnableWorkflow = Exclude<FeatureBacklogWorkflow, 'manual'>;
 type FeatureBacklogItem = BaseBacklogItem & {
     manualReq?: boolean;
+    workflow?: FeatureBacklogWorkflow;
+    completedAt?: string;
+    /** Path relative to `backlogItems/todo/`; tickets live at `<parent>/tickets/<name>`. */
+    todoRelativeDir: string;
+    /** Parent todo folder name when this item is a ticket. */
+    parentName?: string;
 };
-type FeatureBacklogStage = 'makeReq' | 'makeTestPlan' | 'testImpl' | 'implementation';
+type FeatureBacklogStage = 'makeReq' | 'makeTestPlan' | 'testImpl' | 'implementation' | 'directImpl';
 type FeatureBacklogContextVariables = {
     TASK_NAME: string;
     TASK: string;
@@ -193,12 +226,18 @@ type FeatureBacklogContextVariables = {
 };
 type FeatureBacklogOptions<V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables> = {
     configUrl: string | URL;
-    baseBranch: string;
     implValidateCommand?: ValidationCommandFn<V, SV> | string;
     backlogItemsDir?: string;
-} & Omit<LumpJsConfig<V, SV>, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps' | 'baseBranch'>;
-declare function resolveFeatureBacklogItem(item: FeatureBacklogItem, paths: BacklogPaths, projectRoot: string, lumpName: string, baseBranch: string): Promise<BacklogItemResolution<FeatureBacklogStage>>;
+} & Omit<LumpJsConfig<V, SV>, 'contextListJson' | 'contextMatchFn' | 'getContextListFn' | 'prompt' | 'steps'>;
+declare const FEATURE_BACKLOG_WORKFLOWS: readonly ["tdd", "directImpl", "manual"];
+declare function parseFeatureWorkflow(itemName: string, raw: unknown): FeatureBacklogWorkflow | undefined;
+declare function resolveFeatureBacklogItem(input: {
+    item: FeatureBacklogItem;
+    paths: BacklogPaths;
+    projectRoot: string;
+    discoveryBranch: string;
+}): Promise<BacklogItemResolution<FeatureBacklogStage>>;
 declare const featureBacklog: <V extends LumpVariables = LumpVariables, SV extends StepVariables = StepVariables>(options: FeatureBacklogOptions<V, SV>) => LumpJsConfig<V, SV>;
 
-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 };
+export { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, FEATURE_BACKLOG_WORKFLOWS, OPEN_PR_PROVIDERS, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, listTodoRelativeDirs, lumpPathAndName, normalizeMaybePromGetter, openPrPostTeardown, parseFeatureWorkflow, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };
+export type { AbstractionBacklogOptions, AbstractionFinderOptions, AbstractionFinderScanCommand, BacklogItemResolution, BacklogOptions, BacklogPaths, BacklogStageDefinition, BaseBacklogItem, DoneBacklogItem, EphemeralContextListFnOptions, FeatureBacklogContextVariables, FeatureBacklogItem, FeatureBacklogOptions, FeatureBacklogRunnableWorkflow, FeatureBacklogStage, FeatureBacklogWorkflow, FolderBacklogContextsOptions, GetFirstStepsInput, GetRecursiveStepsOptions, ImplValidateCommand, IsValidationCommandResultOkInput, MaybePromGetter, OpenPrPostTeardownOptions, OpenPrProvider, Recipe, RetryUntilGreenInput, StepIndex, ValidationCommandFn, ValidationCommandFnInput, YmlBacklogContextsOptions };

package/dist/index.js

@@ -1,11 +1,12 @@
-import { normalizeSteps, readYamlList, defineConfig, getContextStatus } from '@lumpcode/cli-utils';
-import { shellSingleQuote, pathExists } from '@lumpcode/core';
+import { getGitCommitMessage, normalizeSteps, readYamlList, defineConfig, getContextStatus } from '@lumpcode/cli-utils';
+import { execBinary, shellSingleQuote, pathExists } from '@lumpcode/core';
 import { fileURLToPath } from 'url';
 import path from 'path';
 import path$1 from 'node:path';
 import { fileURLToPath as fileURLToPath$1 } from 'node:url';
 import fs from 'fs/promises';
 import { load, dump } from 'js-yaml';
+import fs$1 from 'node:fs/promises';
 
 /** Run a shell script via `sh -c` (portable on Unix-like systems and Git Bash on Windows). */
 function shellCommand(script) {
@@ -15,6 +16,111 @@ function shellCommand(script) {
     };
 }
 
+const LOG_PREFIX = '[lumpcode/recipes]';
+async function openGithubPr(input) {
+    const { workspacePath, baseBranch, branchName, title, body } = input;
+    const cwd = workspacePath;
+    const listed = await execBinary({
+        binaryPath: 'gh',
+        args: ['pr', 'list', '--head', branchName, '--base', baseBranch, '--json', 'number'],
+        cwd,
+    });
+    if (listed.success && githubPrListHasItems(listed.data.stdout)) {
+        return;
+    }
+    const created = await execBinary({
+        binaryPath: 'gh',
+        args: [
+            'pr',
+            'create',
+            '--base',
+            baseBranch,
+            '--head',
+            branchName,
+            '--title',
+            title,
+            '--body',
+            body,
+        ],
+        cwd,
+    });
+    if (!created.success) {
+        console.error(`${LOG_PREFIX} gh pr create failed: ${created.data.message}`);
+    }
+}
+function githubPrListHasItems(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return Array.isArray(parsed) && parsed.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+
+const LUMP_BRANCH_PREFIX = 'lump/';
+const OPEN_PR_PROVIDERS = ['github'];
+function openPrPostTeardown(options) {
+    const { provider, lumpName: lumpNameOption, title, body } = options;
+    return async (input) => {
+        const { baseBranch, branchName, contextList, workspacePath } = input;
+        if (!branchName || branchName === baseBranch) {
+            return;
+        }
+        const remote = await execBinary({
+            binaryPath: 'git',
+            args: ['ls-remote', '--heads', 'origin', branchName],
+            cwd: workspacePath,
+        });
+        if (!remote.success || !remote.data.stdout.trim()) {
+            return;
+        }
+        const names = contextList.map((ctx) => ctx.name).filter((name) => name.length > 0);
+        const label = names.length > 0 ? names.join(', ') : branchName;
+        const lumpName = lumpNameOption ?? lumpNameFromBranch(branchName);
+        const resolvedTitle = title?.(input) ?? defaultPrTitle({ lumpName, label });
+        const resolvedBody = body?.(input) ?? `LUMP contexts: ${label}`;
+        await openPrWithProvider({
+            provider,
+            workspacePath,
+            baseBranch,
+            branchName,
+            title: resolvedTitle,
+            body: resolvedBody,
+        });
+    };
+}
+function defaultPrTitle(input) {
+    const { lumpName, label } = input;
+    if (lumpName) {
+        return getGitCommitMessage({ lumpName, contextName: label });
+    }
+    return `LUMP: ${label}`;
+}
+function lumpNameFromBranch(branchName) {
+    if (!branchName.startsWith(LUMP_BRANCH_PREFIX)) {
+        return undefined;
+    }
+    const rest = branchName.slice(LUMP_BRANCH_PREFIX.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0) {
+        return undefined;
+    }
+    return rest.slice(0, slash);
+}
+async function openPrWithProvider(input) {
+    const { provider, ...prInput } = input;
+    switch (provider) {
+        case 'github':
+            await openGithubPr(prInput);
+            return;
+        default: {
+            const _exhaustive = provider;
+            throw new Error(`Unhandled PR provider: ${_exhaustive}`);
+        }
+    }
+}
+
 function normalizeMaybePromGetter(maybePromGetter, defaultValue) {
     if (typeof maybePromGetter === 'function') {
         return maybePromGetter;
@@ -284,10 +390,26 @@ async function listTodoFolderNames(todoDir) {
         throw error;
     }
 }
+/** Path relative to `todo/`, using `/` so it is stable in context variables. */
+async function listTodoRelativeDirs(todoDir) {
+    const topNames = await listTodoFolderNames(todoDir);
+    const relativeDirs = [];
+    for (const name of topNames) {
+        const ticketNames = await listTodoFolderNames(path$1.join(todoDir, name, 'tickets'));
+        if (ticketNames.length === 0) {
+            relativeDirs.push(name);
+            continue;
+        }
+        for (const ticketName of ticketNames) {
+            relativeDirs.push(`${name}/tickets/${ticketName}`);
+        }
+    }
+    return relativeDirs;
+}
 function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
     return async () => {
         const todoDir = path$1.join(backlogItemsDir, 'todo');
-        const folderNames = await listTodoFolderNames(todoDir);
+        const folderNames = await listTodoRelativeDirs(todoDir);
         const discovered = await Promise.all(folderNames.map(async (folderName) => {
             const descPath = path$1.join(todoDir, folderName, 'desc.yml');
             let rawText;
@@ -302,13 +424,22 @@ function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
                 throw error;
             }
             const raw = load(rawText);
+            const itemFolderName = path$1.basename(folderName);
             const baseItem = validateBaseBacklogItem(raw, `in folder "${folderName}"`);
-            if (baseItem.name !== folderName) {
+            if (baseItem.name !== itemFolderName) {
                 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 };
         }));
+        const seenNames = new Map();
+        for (const { item, folderName } of discovered) {
+            const previous = seenNames.get(item.name);
+            if (previous !== undefined) {
+                throw new Error(`Duplicate backlog item name "${item.name}" in folders "${previous}" and "${folderName}"`);
+            }
+            seenNames.set(item.name, folderName);
+        }
         discovered.sort((a, b) => {
             if (a.item.priority !== b.item.priority) {
                 return a.item.priority - b.item.priority;
@@ -339,7 +470,7 @@ function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
 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. */
+/** Moves a finished backlog item folder from todo/ to the same relative path under completed/. */
 function folderSetTaskDoneStep(input) {
     const nameVarName = input.nameVarName ?? 'TASK_NAME';
     return {
@@ -347,19 +478,29 @@ function folderSetTaskDoneStep(input) {
             const variables = context.variables;
             const itemsDirRelative = variables[input.itemsDirVarName];
             const taskName = variables[nameVarName];
-            if (!itemsDirRelative || !taskName) {
+            const itemDirRelative = variables.BACKLOG_ITEM_DIR;
+            if (!itemsDirRelative || (!itemDirRelative && !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 todoDir = path$1.join(itemsDir, 'todo');
+            const fromDir = itemDirRelative
+                ? path$1.join(workspacePath, itemDirRelative)
+                : path$1.join(todoDir, taskName);
+            const relativeFromTodo = path$1.relative(todoDir, fromDir);
+            if (relativeFromTodo === '' ||
+                relativeFromTodo.startsWith('..') ||
+                path$1.isAbsolute(relativeFromTodo)) {
+                throw new Error(`BACKLOG_ITEM_DIR must be a folder under ${todoDir}: ${itemDirRelative ?? fromDir}`);
+            }
+            const toDir = path$1.join(itemsDir, 'completed', relativeFromTodo);
             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}`);
+                console.warn(`[lumpcode/recipes] Cannot move backlog item "${taskName ?? relativeFromTodo}": already exists at ${toDir}`);
                 return null;
             }
             const rawText = await fs.readFile(descPath, 'utf-8');
@@ -371,7 +512,7 @@ function folderSetTaskDoneStep(input) {
                 ...raw,
                 completedAt: new Date().toISOString(),
             };
-            await fs.mkdir(path$1.join(itemsDir, 'completed'), { recursive: true });
+            await fs.mkdir(path$1.dirname(toDir), { recursive: true });
             await fs.rename(fromDir, toDir);
             await fs.writeFile(completedDescPath, dump(updated));
             return {
@@ -620,29 +761,72 @@ const abstractionBacklog = defineRecipe(function abstractionBacklog(options) {
     });
 });
 
+function scanCommandStep(scanCommand) {
+    if (typeof scanCommand === 'function') {
+        return { commandFn: scanCommand };
+    }
+    if (typeof scanCommand === 'string') {
+        return { commandFn: () => shellCommand(scanCommand) };
+    }
+    return { commandFn: () => scanCommand };
+}
 const abstractionFinder = defineRecipe(function abstractionFinder(options) {
-    const { maxPendingAbstractions = 5, scanDirectories, customPrompt, backlogItemsDir, } = options; // TODO : check if pending abstcations in backlog are less than maxPendingAbstractions
+    const { configUrl, maxPendingAbstractions = 5, scanDirectories, utilDir, customPrompt, backlogItemsDir, scanCommand, steps: stepsOverride, ...rest } = options;
+    if (path$1.isAbsolute(backlogItemsDir)) {
+        throw new Error(`backlogItemsDir must be project-root-relative, not absolute: ${backlogItemsDir}`);
+    }
+    const projectRoot = projectRootFromConfigUrl(configUrl);
+    const todoDir = path$1.join(projectRoot, backlogItemsDir, 'todo');
+    const agentSteps = stepsOverride ?? buildFinderPrompt({
+        backlogItemsDir,
+        scanDirectories,
+        utilDir,
+        customPrompt,
+    });
+    const steps = [
+        ...(scanCommand === undefined ? [] : [scanCommandStep(scanCommand)]),
+        ...normalizeSteps({
+            prompt: undefined,
+            jsSteps: agentSteps,
+        }),
+    ];
     return defineConfig({
-        ...options,
+        ...rest,
         getContextListFn: ephemeralContextListFn({
-            contextCount: maxPendingAbstractions,
+            async contextCount() {
+                const pending = (await listTodoRelativeDirs(todoDir)).length;
+                return pending >= maxPendingAbstractions ? 0 : 1;
+            },
             variables: {
                 BACKLOG_ITEMS_DIR: backlogItemsDir,
             },
         }),
-        steps: buildFinderPrompt({ backlogItemsDir, scanDirectories, customPrompt }),
+        steps,
     });
 });
-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).
+function buildFinderPrompt({ backlogItemsDir, scanDirectories, utilDir, customPrompt, }) {
+    if (customPrompt) {
+        return customPrompt();
+    }
+    const scanLabel = scanDirectories && scanDirectories.length > 0
+        ? scanDirectories.map((dir) => `@${dir}`).join(' and ')
+        : 'the codebase';
+    const materializeDir = utilDir ?? scanDirectories?.[0];
+    const materializeLine = materializeDir
+        ? `- Would materialize as a new util under @${materializeDir}/<utilName>/, following existing conventions there.`
+        : '- Would materialize as a new util in the scanned tree, following existing conventions there.';
+    const refactorScope = scanDirectories && scanDirectories.length > 0
+        ? scanDirectories.join(' and ')
+        : 'the scanned tree';
+    return `
+Scan ${scanLabel} for duplicated logic that appears in multiple places (same pattern, not merely similar file structure).
 
 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).
+${materializeLine}
+- Would shrink the codebase: refactoring all call sites in ${refactorScope} should reduce net line count (excluding new unit tests).
 
 Create exactly one new backlog item folder at @${backlogItemsDir}/todo/<utilName>/ with:
 - desc.yml containing:
@@ -662,6 +846,11 @@ Do not take too much time looking for every possible abstraction. Once you found
     `.trim();
 }
 
+const FEATURE_BACKLOG_WORKFLOWS = [
+    'tdd',
+    'directImpl',
+    'manual',
+];
 const RESERVED_NAME_SUFFIXES = ['_req', '_testPlan', '_tests_impl'];
 function assertValidFeatureItemName(name) {
     for (const suffix of RESERVED_NAME_SUFFIXES) {
@@ -670,6 +859,9 @@ function assertValidFeatureItemName(name) {
         }
     }
 }
+function featureItemContextBaseName(item) {
+    return item.parentName ? `${item.parentName}-${item.name}` : item.name;
+}
 function featureContextName(itemName, stage) {
     switch (stage) {
         case 'makeReq':
@@ -679,6 +871,7 @@ function featureContextName(itemName, stage) {
         case 'testImpl':
             return `${itemName}_tests_impl`;
         case 'implementation':
+        case 'directImpl':
             return itemName;
         default: {
             const _exhaustive = stage;
@@ -686,9 +879,84 @@ function featureContextName(itemName, stage) {
         }
     }
 }
-async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, baseBranch) {
-    const reqFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'requirements.md');
-    const testPlanFilePath = path$1.join(paths.backlogItemsDir, 'todo', item.name, 'testPlan.md');
+function parentNameFromTodoRelativeDir(todoRelativeDir) {
+    const parts = todoRelativeDir.split('/');
+    if (parts.length === 3 && parts[1] === 'tickets') {
+        return parts[0];
+    }
+    return undefined;
+}
+function parseFeatureWorkflow(itemName, raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    if (record.workflow === undefined) {
+        return undefined;
+    }
+    if (typeof record.workflow !== 'string' ||
+        !FEATURE_BACKLOG_WORKFLOWS.includes(record.workflow)) {
+        throw new Error(`Backlog item "${itemName}" field "workflow" must be one of: ${FEATURE_BACKLOG_WORKFLOWS.join(', ')}`);
+    }
+    return record.workflow;
+}
+async function resolveItemWorkflow(input) {
+    const { item, paths, projectRoot } = input;
+    if (item.workflow !== undefined) {
+        return item.workflow;
+    }
+    if (item.parentName === undefined) {
+        return 'tdd';
+    }
+    const parentDescPath = path$1.join(projectRoot, paths.backlogItemsDir, 'todo', item.parentName, 'desc.yml');
+    let rawText;
+    try {
+        rawText = await fs$1.readFile(parentDescPath, 'utf-8');
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return 'tdd';
+        }
+        throw error;
+    }
+    return parseFeatureWorkflow(item.parentName, load(rawText)) ?? 'tdd';
+}
+/**
+ * `dev` → only top-level `directImpl` (tickets never run on `dev`, even if `directImpl`).
+ * `feature/<key>` → exact item name, or the parent todo name for tickets.
+ * `manual` never reaches here (`resolveFeatureBacklogItem` ignores it first).
+ */
+function itemMatchesDiscoveryBranch(input) {
+    const { itemName, parentName, discoveryBranch, workflow } = input;
+    if (discoveryBranch === 'dev') {
+        return workflow === 'directImpl' && parentName === undefined;
+    }
+    if (!discoveryBranch.startsWith('feature/')) {
+        return false;
+    }
+    const key = discoveryBranch.slice('feature/'.length);
+    return (parentName ?? itemName) === key;
+}
+async function resolveFeatureBacklogItem(input) {
+    const { item, paths, projectRoot, discoveryBranch } = input;
+    const contextBaseName = featureItemContextBaseName(item);
+    const workflow = await resolveItemWorkflow({ item, paths, projectRoot });
+    if (workflow === 'manual') {
+        return { ignored: true };
+    }
+    if (!!item.completedAt ||
+        !itemMatchesDiscoveryBranch({
+            itemName: item.name,
+            parentName: item.parentName,
+            discoveryBranch,
+            workflow,
+        })) {
+        return { ignored: true };
+    }
+    const itemDir = path$1.join(paths.backlogItemsDir, 'todo', item.todoRelativeDir);
+    const reqFilePath = path$1.join(itemDir, 'requirements.md');
+    const testPlanFilePath = path$1.join(itemDir, 'testPlan.md');
     const hasReq = await pathExists(path$1.join(projectRoot, reqFilePath));
     if (!hasReq) {
         if (item.manualReq === true) {
@@ -696,7 +964,14 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
         }
         return {
             stage: 'makeReq',
-            contextName: featureContextName(item.name, 'makeReq'),
+            contextName: featureContextName(contextBaseName, 'makeReq'),
+            variables: { REQ_FILE: reqFilePath },
+        };
+    }
+    if (workflow === 'directImpl') {
+        return {
+            stage: 'directImpl',
+            contextName: featureContextName(contextBaseName, 'directImpl'),
             variables: { REQ_FILE: reqFilePath },
         };
     }
@@ -704,24 +979,24 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
     if (!hasTestPlan) {
         return {
             stage: 'makeTestPlan',
-            contextName: featureContextName(item.name, 'makeTestPlan'),
+            contextName: featureContextName(contextBaseName, 'makeTestPlan'),
             variables: {
                 REQ_FILE: reqFilePath,
                 TEST_PLAN_FILE: testPlanFilePath,
             },
         };
     }
-    const testsImplContextName = featureContextName(item.name, 'testImpl');
+    const testsImplContextName = featureContextName(contextBaseName, 'testImpl');
     const testsImplStatus = await getContextStatus({
         projectRoot,
         contextName: testsImplContextName,
-        lumpName,
-        baseBranch,
+        lumpName: paths.lumpName,
+        baseBranch: discoveryBranch,
     });
     if (testsImplStatus === 'finished') {
         return {
             stage: 'implementation',
-            contextName: featureContextName(item.name, 'implementation'),
+            contextName: featureContextName(contextBaseName, 'implementation'),
             variables: {
                 REQ_FILE: reqFilePath,
                 TEST_PLAN_FILE: testPlanFilePath,
@@ -741,27 +1016,38 @@ async function resolveFeatureBacklogItem(item, paths, projectRoot, lumpName, bas
     };
 }
 const featureBacklog = defineRecipe(function featureBacklog(options) {
-    const { configUrl, baseBranch, implValidateCommand, backlogItemsDir, ...rest } = options;
+    const { configUrl, implValidateCommand, backlogItemsDir, ...rest } = options;
     const projectRoot = projectRootFromConfigUrl(configUrl);
     const runImplValidation = resolveImplValidateCommand(implValidateCommand ??
         'echo "No implementation validation command provided. I say, trust but verify, but well..."');
     return backlog({
         configUrl,
         backlogItemsDir,
-        baseBranch,
-        parseItem(baseItem, _folderName, raw) {
+        parseItem(baseItem, folderName, raw) {
             assertValidFeatureItemName(baseItem.name);
             const record = raw;
             if (record.manualReq !== undefined && typeof record.manualReq !== 'boolean') {
                 throw new Error(`Backlog item "${baseItem.name}" field "manualReq" must be a boolean`);
             }
+            const parentName = parentNameFromTodoRelativeDir(folderName);
             return {
                 ...baseItem,
+                todoRelativeDir: folderName,
+                parentName,
+                dependsOn: parentName
+                    ? baseItem.dependsOn?.map((dep) => `${parentName}-${dep}`)
+                    : baseItem.dependsOn,
                 manualReq: record.manualReq === true ? true : undefined,
+                workflow: parseFeatureWorkflow(baseItem.name, raw),
             };
         },
-        async resolveItem({ item, paths }) {
-            return resolveFeatureBacklogItem(item, paths, projectRoot, paths.lumpName, baseBranch);
+        async resolveItem({ item, paths, discoveryBranch }) {
+            return resolveFeatureBacklogItem({
+                item,
+                paths,
+                projectRoot,
+                discoveryBranch,
+            });
         },
         stages: {
             makeReq: {
@@ -910,9 +1196,28 @@ The implementation should make the tests pass. Do not edit any test file except
                     validationCommandFn: runImplValidation,
                 }),
             },
+            directImpl: {
+                completion: 'moveToDone',
+                steps: retryUntilGreen({
+                    steps: [
+                        {
+                            promptFn({ context: ctx }) {
+                                const vars = ctx.variables;
+                                const { REQ_FILE } = vars;
+                                return `
+Implement the feature described in @${REQ_FILE}.
+Add or update tests as needed so the suite covers the change, and make validation pass.
+Do not edit @${REQ_FILE} unless absolutely necessary.
+                                `.trim();
+                            },
+                        },
+                    ],
+                    validationCommandFn: runImplValidation,
+                }),
+            },
         },
         ...rest,
     });
 });
 
-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 { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, FEATURE_BACKLOG_WORKFLOWS, OPEN_PR_PROVIDERS, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, listTodoRelativeDirs, lumpPathAndName, normalizeMaybePromGetter, openPrPostTeardown, parseFeatureWorkflow, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumpcode/recipes",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Lumpcode lump recipes and kit helpers",
   "keywords": [
     "lumpcode",
@@ -44,8 +44,8 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@lumpcode/cli-utils": "^0.2.0",
-    "@lumpcode/core": "^0.2.0",
+    "@lumpcode/cli-utils": "^0.3.1",
+    "@lumpcode/core": "^0.3.1",
     "js-yaml": "^5.0.0"
   },
   "devDependencies": {