@lumpcode/recipes 0.3.1 → 0.4.0

package/dist/index.js

@@ -390,26 +390,54 @@ async function listTodoFolderNames(todoDir) {
         throw error;
     }
 }
-/** Path relative to `todo/`, using `/` so it is stable in context variables. */
-async function listTodoRelativeDirs(todoDir) {
+/** Live and completed ticket folder names for an umbrella parent, sorted uniquely. */
+async function listUmbrellaTicketNames(input) {
+    const { todoDir, parentName } = input;
+    const completedDir = path$1.join(path$1.dirname(todoDir), 'completed');
+    const liveTicketNames = await listTodoFolderNames(path$1.join(todoDir, parentName, 'tickets'));
+    const completedTicketNames = await listTodoFolderNames(path$1.join(completedDir, parentName, 'tickets'));
+    return [...new Set([...liveTicketNames, ...completedTicketNames])].sort();
+}
+/**
+ * Path relative to `todo/`, using `/` so it is stable in context variables.
+ * A top-level folder is an umbrella (never itself an item) when it has live
+ * tickets, a leftover `tickets/` directory, or tickets already under
+ * sibling `completed/<name>/tickets/`.
+ */
+async function listTodoRelativeDirs(todoDir, options) {
+    const includeUmbrellaParents = options?.includeUmbrellaParents ?? false;
     const topNames = await listTodoFolderNames(todoDir);
+    const completedDir = path$1.join(path$1.dirname(todoDir), 'completed');
     const relativeDirs = [];
     for (const name of topNames) {
-        const ticketNames = await listTodoFolderNames(path$1.join(todoDir, name, 'tickets'));
-        if (ticketNames.length === 0) {
-            relativeDirs.push(name);
+        const liveTicketsDir = path$1.join(todoDir, name, 'tickets');
+        const liveTicketNames = await listTodoFolderNames(liveTicketsDir);
+        const completedTicketNames = await listTodoFolderNames(path$1.join(completedDir, name, 'tickets'));
+        const hasAnyTicket = liveTicketNames.length > 0 || completedTicketNames.length > 0;
+        if (liveTicketNames.length > 0) {
+            for (const ticketName of liveTicketNames) {
+                relativeDirs.push(`${name}/tickets/${ticketName}`);
+            }
+            if (includeUmbrellaParents && hasAnyTicket) {
+                relativeDirs.push(name);
+            }
             continue;
         }
-        for (const ticketName of ticketNames) {
-            relativeDirs.push(`${name}/tickets/${ticketName}`);
+        const isUmbrella = (await pathExists(liveTicketsDir)) || completedTicketNames.length > 0;
+        if (isUmbrella) {
+            if (includeUmbrellaParents && hasAnyTicket) {
+                relativeDirs.push(name);
+            }
+            continue;
         }
+        relativeDirs.push(name);
     }
     return relativeDirs;
 }
-function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
+function folderBacklogContexts({ backlogItemsDir, includeUmbrellaParents, parseItem, parseContext, }) {
     return async () => {
         const todoDir = path$1.join(backlogItemsDir, 'todo');
-        const folderNames = await listTodoRelativeDirs(todoDir);
+        const folderNames = await listTodoRelativeDirs(todoDir, { includeUmbrellaParents });
         const discovered = await Promise.all(folderNames.map(async (folderName) => {
             const descPath = path$1.join(todoDir, folderName, 'desc.yml');
             let rawText;
@@ -470,6 +498,37 @@ function folderBacklogContexts({ backlogItemsDir, parseItem, parseContext, }) {
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+async function listSubdirNames(dir) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+async function mergeTodoUmbrellaParentIntoCompleted(input) {
+    const { fromDir, toDir, completedDescPath, updatedDesc } = input;
+    await fs.mkdir(toDir, { recursive: true });
+    await fs.writeFile(completedDescPath, dump(updatedDesc));
+    const entries = await fs.readdir(fromDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === 'desc.yml') {
+            continue;
+        }
+        const src = path$1.join(fromDir, entry.name);
+        const dest = path$1.join(toDir, entry.name);
+        if (await pathExists(dest)) {
+            continue;
+        }
+        await fs.rename(src, dest);
+    }
+    await fs.rm(fromDir, { recursive: true, force: true });
+}
 /** Moves a finished backlog item folder from todo/ to the same relative path under completed/. */
 function folderSetTaskDoneStep(input) {
     const nameVarName = input.nameVarName ?? 'TASK_NAME';
@@ -499,10 +558,6 @@ function folderSetTaskDoneStep(input) {
             if (!(await pathExists(fromDir))) {
                 return null;
             }
-            if (await pathExists(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');
             const raw = load(rawText);
             if (!isPlainObject(raw)) {
@@ -512,6 +567,26 @@ function folderSetTaskDoneStep(input) {
                 ...raw,
                 completedAt: new Date().toISOString(),
             };
+            const pathSegments = relativeFromTodo.split(/[/\\]/);
+            const isTopLevelParent = pathSegments.length === 1;
+            const completedTicketsDir = path$1.join(toDir, 'tickets');
+            const hasCompletedTickets = (await listSubdirNames(completedTicketsDir)).length > 0;
+            if (await pathExists(toDir)) {
+                if (isTopLevelParent && hasCompletedTickets) {
+                    await mergeTodoUmbrellaParentIntoCompleted({
+                        fromDir,
+                        toDir,
+                        completedDescPath,
+                        updatedDesc: updated,
+                    });
+                    return {
+                        executable: 'cat',
+                        args: [completedDescPath],
+                    };
+                }
+                console.warn(`[lumpcode/recipes] Cannot move backlog item "${taskName ?? relativeFromTodo}": already exists at ${toDir}`);
+                return null;
+            }
             await fs.mkdir(path$1.dirname(toDir), { recursive: true });
             await fs.rename(fromDir, toDir);
             await fs.writeFile(completedDescPath, dump(updated));
@@ -648,7 +723,7 @@ function buildStageSteps(stages, stageName) {
     return normalized;
 }
 function backlog(options) {
-    const { configUrl, backlogItemsDir: backlogItemsDirOverride, stages, parseItem, resolveItem, ...rest } = options;
+    const { configUrl, backlogItemsDir: backlogItemsDirOverride, includeUmbrellaParents, stages, parseItem, resolveItem, ...rest } = options;
     const paths = resolveBacklogPaths(configUrl, {
         backlogItemsDir: backlogItemsDirOverride,
     });
@@ -658,6 +733,7 @@ function backlog(options) {
         getContextListFn: async (input) => {
             const listFn = folderBacklogContexts({
                 backlogItemsDir: absoluteBacklogItemsDir,
+                includeUmbrellaParents,
                 parseItem,
                 async parseContext(item, folderName) {
                     const resolution = await resolveItem({
@@ -846,32 +922,309 @@ Do not take too much time looking for every possible abstraction. Once you found
     `.trim();
 }
 
-const FEATURE_BACKLOG_WORKFLOWS = [
-    'tdd',
+function featureContextVars(context) {
+    return context.variables;
+}
+const defaultReqPrompt = ({ context }) => {
+    const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, REQ_FILE } = featureContextVars(context);
+    return `
+Write a requirements document for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
+
+Task name: ${TASK_NAME}
+
+Task:
+${TASK}
+
+Save the requirements document to @${REQ_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml.
+
+The requirements document should be self-contained and implementation-ready. Include:
+- Problem statement and motivation
+- Goals and non-goals
+- User stories / use cases
+- Docs updates (if relevant)
+- Proposed behavior and UX (for CLI work, include command syntax where relevant)
+- Technical approach and affected packages or docs
+- Acceptance criteria
+
+Do not implement the feature — only create the requirements markdown file.
+Do not wait the user to answer any questions — make the best assumptions and just write the requirements document.
+The requirements document should not contain any testing strategy details.
+    `.trim();
+};
+function defaultReqFixPrompt(prevValidateCommandResult) {
+    return ({ context }) => {
+        const { BACKLOG_ITEM_DIR, REQ_FILE } = featureContextVars(context);
+        return `
+The requirements document was not created at @${REQ_FILE}.
+
+Create it now at that exact path. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml.
+Do not implement the feature — only write the requirements markdown file.
+The requirements document should not contain any testing strategy details.
+
+Verification output:
+${prevValidateCommandResult ?? '(no output captured)'}
+        `.trim();
+    };
+}
+const defaultTestPlanPrompt = ({ context }) => {
+    const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, REQ_FILE, TEST_PLAN_FILE } = featureContextVars(context);
+    return `
+Write a test plan for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
+
+Task name: ${TASK_NAME}
+Task:
+${TASK}
+
+The requirements for this task are in @${REQ_FILE}. The test plan should match those requirements.
+
+Save the test plan to @${TEST_PLAN_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml nor @${REQ_FILE}.
+
+The test plan should be self-contained and implementation-ready. Include:
+- Test cases
+- Test data
+- Test expectations
+- Test implementation details
+    `.trim();
+};
+function defaultTestPlanFixPrompt(prevValidateCommandResult) {
+    return ({ context }) => {
+        const { BACKLOG_ITEM_DIR, REQ_FILE, TEST_PLAN_FILE } = featureContextVars(context);
+        return `
+The test plan was not created at @${TEST_PLAN_FILE}.
+
+Create it now at that exact path. Match the requirements in @${REQ_FILE}.
+Do not edit @${BACKLOG_ITEM_DIR}/desc.yml nor @${REQ_FILE}.
+
+Verification output:
+${prevValidateCommandResult ?? '(no output captured)'}
+        `.trim();
+    };
+}
+const defaultTestImplPrompt = ({ context }) => {
+    const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, REQ_FILE, TEST_PLAN_FILE } = featureContextVars(context);
+    const planLine = TEST_PLAN_FILE
+        ? `Follow the test plan in @${TEST_PLAN_FILE}.`
+        : 'Write skipped tests from the requirements and your judgement. Do not create a testPlan.md.';
+    return `
+Write a test implementation for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
+
+The new tests should be skipped in order to not break the whole test suite.
+
+Task name: ${TASK_NAME}
+Task:
+${TASK}
+
+${planLine}
+The requirements for this task are in @${REQ_FILE}.
+    `.trim();
+};
+const defaultImplPrompt = ({ context }) => {
+    const { REQ_FILE, TEST_PLAN_FILE, WORKFLOW } = featureContextVars(context);
+    const wantsTestImpl = (WORKFLOW ?? '').split(',').includes('testImpl');
+    if (wantsTestImpl) {
+        return `
+Implement the feature described in @${REQ_FILE}.
+The tests have already been implemented according to the test plan${TEST_PLAN_FILE ? ` in @${TEST_PLAN_FILE}` : ''}.
+Unskip all the tests that were skipped in the tests implementation.
+The implementation should make the tests pass. Do not edit any test file except to unskip them or if absolutely necessary.
+        `.trim();
+    }
+    if (TEST_PLAN_FILE) {
+        return `
+Implement the feature described in @${REQ_FILE}.
+Write or update tests to match the test plan in @${TEST_PLAN_FILE}, and make validation pass.
+Do not edit @${REQ_FILE} unless absolutely necessary.
+        `.trim();
+    }
+    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();
+};
+const defaultDirectImplPrompt = ({ context }) => {
+    const { BACKLOG_ITEM_DIR, REQ_FILE, TEST_PLAN_FILE } = featureContextVars(context);
+    const extras = [
+        REQ_FILE ? `Use the requirements in @${REQ_FILE}.` : '',
+        TEST_PLAN_FILE ? `Use the test plan in @${TEST_PLAN_FILE} for tests.` : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return `
+Implement the feature described in @${BACKLOG_ITEM_DIR}/desc.yml.
+${extras}
+Add tests as needed so the suite covers the change, and make validation pass.
+    `.trim();
+};
+
+const FEATURE_BACKLOG_WORKFLOW_STAGES = [
+    'req',
+    'testPlan',
+    'testImpl',
+    'impl',
     'directImpl',
-    'manual',
 ];
-const RESERVED_NAME_SUFFIXES = ['_req', '_testPlan', '_tests_impl'];
+const DEFAULT_FEATURE_BACKLOG_WORKFLOW = [
+    'req',
+    'testPlan',
+    'testImpl',
+];
+const DEFAULT_PRIMARY_DISCOVERY_BRANCH = 'dev';
+const DEFAULT_ITEM_DISCOVERY_BRANCH_PREFIX = 'feature';
+const FEATURE_BACKLOG_RESERVED_NAME_SUFFIXES = [
+    '_req',
+    '_testPlan',
+    '_testImpl',
+];
+const WORKFLOW_PREFIX_ORDER = ['req', 'testPlan', 'testImpl'];
+
+function assertDiscoveryToken(value, field) {
+    if (value.length === 0 || /\s/.test(value) || value.includes('*') || value.endsWith('/')) {
+        throw new Error(`featureBacklog ${field} must be a non-empty exact name without whitespace, *, or a trailing /`);
+    }
+}
+function resolveFeatureBacklogDiscoveryOptions(options) {
+    const primaryDiscoveryBranch = options.primaryDiscoveryBranch ?? DEFAULT_PRIMARY_DISCOVERY_BRANCH;
+    const itemDiscoveryBranchPrefix = options.itemDiscoveryBranchPrefix ?? DEFAULT_ITEM_DISCOVERY_BRANCH_PREFIX;
+    assertDiscoveryToken(primaryDiscoveryBranch, 'primaryDiscoveryBranch');
+    assertDiscoveryToken(itemDiscoveryBranchPrefix, 'itemDiscoveryBranchPrefix');
+    return { primaryDiscoveryBranch, itemDiscoveryBranchPrefix };
+}
+function campaignBranchPrefix(itemDiscoveryBranchPrefix) {
+    return `${itemDiscoveryBranchPrefix}/`;
+}
+function workflowHasCampaignStages(workflow) {
+    return workflow.includes('testPlan') || workflow.includes('testImpl');
+}
+function classifyDiscoveryScan(discoveryBranch, primaryDiscoveryBranch, itemDiscoveryBranchPrefix) {
+    if (discoveryBranch === primaryDiscoveryBranch) {
+        return 'primary';
+    }
+    if (discoveryBranch.startsWith(campaignBranchPrefix(itemDiscoveryBranchPrefix))) {
+        return 'itemCampaign';
+    }
+    return 'unmatched';
+}
+function itemNameFromCampaignBranch(discoveryBranch, itemDiscoveryBranchPrefix) {
+    return discoveryBranch.slice(campaignBranchPrefix(itemDiscoveryBranchPrefix).length);
+}
+function itemIsEligibleForDiscoveryScan(input) {
+    const kind = classifyDiscoveryScan(input.discoveryBranch, input.primaryDiscoveryBranch, input.itemDiscoveryBranchPrefix);
+    switch (kind) {
+        case 'primary':
+            return input.parentName === undefined && !workflowHasCampaignStages(input.workflow);
+        case 'itemCampaign': {
+            const campaignItemName = itemNameFromCampaignBranch(input.discoveryBranch, input.itemDiscoveryBranchPrefix);
+            return (input.parentName ?? input.itemName) === campaignItemName;
+        }
+        case 'unmatched':
+            return false;
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+
+let warnedManualReq = false;
+function warnManualReqDeprecated() {
+    if (warnedManualReq) {
+        return;
+    }
+    warnedManualReq = true;
+    console.warn('[lumpcode/recipes] featureBacklog: desc.yml field "manualReq" is deprecated and ignored. ' +
+        'Omit "req" from workflow to wait for a human requirements file, or set manual: true to skip the item.');
+}
 function assertValidFeatureItemName(name) {
-    for (const suffix of RESERVED_NAME_SUFFIXES) {
+    for (const suffix of FEATURE_BACKLOG_RESERVED_NAME_SUFFIXES) {
         if (name.endsWith(suffix)) {
             throw new Error(`Backlog item name must not end with reserved suffix ${suffix}: ${name}`);
         }
     }
 }
+function isWorkflowStage(value) {
+    return (typeof value === 'string' &&
+        FEATURE_BACKLOG_WORKFLOW_STAGES.includes(value));
+}
+function normalizeWorkflow(stages) {
+    const unique = new Set(stages);
+    const normalized = [];
+    for (const stage of WORKFLOW_PREFIX_ORDER) {
+        if (unique.has(stage)) {
+            normalized.push(stage);
+        }
+    }
+    if (unique.has('directImpl')) {
+        normalized.push('directImpl');
+    }
+    else if (unique.has('impl')) {
+        normalized.push('impl');
+    }
+    return normalized;
+}
+function parseFeatureWorkflow(itemName, raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    const record = raw;
+    if ('manualReq' in record) {
+        warnManualReqDeprecated();
+    }
+    if (record.workflow === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(record.workflow)) {
+        throw new Error(`Backlog item "${itemName}" field "workflow" must be an array of stages: ${FEATURE_BACKLOG_WORKFLOW_STAGES.join(', ')}`);
+    }
+    if (record.workflow.length !== new Set(record.workflow).size) {
+        throw new Error(`Backlog item "${itemName}" field "workflow" must not contain duplicate stages`);
+    }
+    const stages = [];
+    for (const entry of record.workflow) {
+        if (!isWorkflowStage(entry)) {
+            throw new Error(`Backlog item "${itemName}" field "workflow" contains unknown stage ${JSON.stringify(entry)}`);
+        }
+        stages.push(entry);
+    }
+    return normalizeWorkflow(stages);
+}
+function parseManual(itemName, raw) {
+    if (raw.manual === undefined) {
+        return undefined;
+    }
+    if (typeof raw.manual !== 'boolean') {
+        throw new Error(`Backlog item "${itemName}" field "manual" must be a boolean`);
+    }
+    return raw.manual === true ? true : undefined;
+}
+function resolveTerminal(workflow) {
+    if (workflow.includes('directImpl')) {
+        return 'directImpl';
+    }
+    return 'impl';
+}
+function parentNameFromTodoRelativeDir(todoRelativeDir) {
+    const parts = todoRelativeDir.split('/');
+    if (parts.length === 3 && parts[1] === 'tickets') {
+        return parts[0];
+    }
+    return undefined;
+}
+
 function featureItemContextBaseName(item) {
     return item.parentName ? `${item.parentName}-${item.name}` : item.name;
 }
 function featureContextName(itemName, stage) {
     switch (stage) {
-        case 'makeReq':
+        case 'req':
             return `${itemName}_req`;
-        case 'makeTestPlan':
+        case 'testPlan':
             return `${itemName}_testPlan`;
         case 'testImpl':
-            return `${itemName}_tests_impl`;
-        case 'implementation':
+            return `${itemName}_testImpl`;
+        case 'impl':
         case 'directImpl':
+        case 'completion':
             return itemName;
         default: {
             const _exhaustive = stage;
@@ -879,34 +1232,13 @@ function featureContextName(itemName, stage) {
         }
     }
 }
-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';
+        return DEFAULT_FEATURE_BACKLOG_WORKFLOW;
     }
     const parentDescPath = path$1.join(projectRoot, paths.backlogItemsDir, 'todo', item.parentName, 'desc.yml');
     let rawText;
@@ -916,41 +1248,58 @@ async function resolveItemWorkflow(input) {
     catch (error) {
         const err = error;
         if (err.code === 'ENOENT') {
-            return 'tdd';
+            return DEFAULT_FEATURE_BACKLOG_WORKFLOW;
         }
         throw error;
     }
-    return parseFeatureWorkflow(item.parentName, load(rawText)) ?? 'tdd';
+    return parseFeatureWorkflow(item.parentName, load(rawText)) ?? DEFAULT_FEATURE_BACKLOG_WORKFLOW;
 }
-/**
- * `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;
+function artifactVariables(input) {
+    const variables = {
+        WORKFLOW: input.workflow.join(','),
+    };
+    if (input.hasReq || input.stage === 'req') {
+        variables.REQ_FILE = input.reqFilePath;
     }
-    if (!discoveryBranch.startsWith('feature/')) {
-        return false;
+    if (input.hasTestPlan || input.stage === 'testPlan') {
+        variables.TEST_PLAN_FILE = input.testPlanFilePath;
     }
-    const key = discoveryBranch.slice('feature/'.length);
-    return (parentName ?? itemName) === key;
+    return variables;
 }
 async function resolveFeatureBacklogItem(input) {
-    const { item, paths, projectRoot, discoveryBranch } = input;
+    const { item, paths, projectRoot, discoveryBranch, primaryDiscoveryBranch, itemDiscoveryBranchPrefix, } = input;
+    if (item.parentName === undefined) {
+        const todoDir = path$1.join(projectRoot, paths.backlogItemsDir, 'todo');
+        const ticketNames = await listUmbrellaTicketNames({
+            todoDir,
+            parentName: item.name,
+        });
+        if (ticketNames.length > 0) {
+            if (item.completedAt) {
+                return { ignored: true };
+            }
+            if (classifyDiscoveryScan(discoveryBranch, primaryDiscoveryBranch, itemDiscoveryBranchPrefix) !== 'itemCampaign' ||
+                itemNameFromCampaignBranch(discoveryBranch, itemDiscoveryBranchPrefix) !== item.name) {
+                return { ignored: true };
+            }
+            return {
+                stage: 'completion',
+                contextName: item.name,
+                additionalDependsOnContexts: ticketNames.map((ticketName) => `${item.name}-${ticketName}`),
+            };
+        }
+    }
     const contextBaseName = featureItemContextBaseName(item);
     const workflow = await resolveItemWorkflow({ item, paths, projectRoot });
-    if (workflow === 'manual') {
-        return { ignored: true };
-    }
-    if (!!item.completedAt ||
-        !itemMatchesDiscoveryBranch({
+    if (item.manual === true ||
+        !!item.completedAt ||
+        !itemIsEligibleForDiscoveryScan({
             itemName: item.name,
             parentName: item.parentName,
             discoveryBranch,
             workflow,
+            primaryDiscoveryBranch,
+            itemDiscoveryBranchPrefix,
         })) {
         return { ignored: true };
     }
@@ -958,77 +1307,75 @@ async function resolveFeatureBacklogItem(input) {
     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) {
-            return { ignored: true };
-        }
-        return {
-            stage: 'makeReq',
-            contextName: featureContextName(contextBaseName, 'makeReq'),
-            variables: { REQ_FILE: reqFilePath },
-        };
+    const hasTestPlan = await pathExists(path$1.join(projectRoot, testPlanFilePath));
+    const wants = (stage) => workflow.includes(stage);
+    const terminal = resolveTerminal(workflow);
+    const resolveStage = (stage) => ({
+        stage,
+        contextName: featureContextName(contextBaseName, stage),
+        variables: artifactVariables({
+            stage,
+            workflow,
+            reqFilePath,
+            testPlanFilePath,
+            hasReq,
+            hasTestPlan,
+        }),
+    });
+    if (wants('req') && !hasReq) {
+        return resolveStage('req');
     }
-    if (workflow === 'directImpl') {
-        return {
-            stage: 'directImpl',
-            contextName: featureContextName(contextBaseName, 'directImpl'),
-            variables: { REQ_FILE: reqFilePath },
-        };
+    if (!hasReq && (wants('testPlan') || wants('testImpl'))) {
+        return { ignored: true };
     }
-    const hasTestPlan = await pathExists(path$1.join(projectRoot, testPlanFilePath));
-    if (!hasTestPlan) {
-        return {
-            stage: 'makeTestPlan',
-            contextName: featureContextName(contextBaseName, 'makeTestPlan'),
-            variables: {
-                REQ_FILE: reqFilePath,
-                TEST_PLAN_FILE: testPlanFilePath,
-            },
-        };
+    if (wants('testPlan') && !hasTestPlan) {
+        return resolveStage('testPlan');
     }
-    const testsImplContextName = featureContextName(contextBaseName, 'testImpl');
-    const testsImplStatus = await getContextStatus({
-        projectRoot,
-        contextName: testsImplContextName,
-        lumpName: paths.lumpName,
-        baseBranch: discoveryBranch,
-    });
-    if (testsImplStatus === 'finished') {
-        return {
-            stage: 'implementation',
-            contextName: featureContextName(contextBaseName, 'implementation'),
-            variables: {
-                REQ_FILE: reqFilePath,
-                TEST_PLAN_FILE: testPlanFilePath,
-            },
-        };
+    if (wants('testImpl')) {
+        const testsImplContextName = featureContextName(contextBaseName, 'testImpl');
+        const testsImplStatus = await getContextStatus({
+            projectRoot,
+            contextName: testsImplContextName,
+            lumpName: paths.lumpName,
+            baseBranch: discoveryBranch,
+        });
+        if (testsImplStatus === 'branchPushed') {
+            return { ignored: true };
+        }
+        if (testsImplStatus !== 'finished') {
+            return resolveStage('testImpl');
+        }
     }
-    if (testsImplStatus === 'branchPushed') {
+    if (terminal === 'directImpl') {
+        return resolveStage('directImpl');
+    }
+    if (!hasReq) {
         return { ignored: true };
     }
-    return {
-        stage: 'testImpl',
-        contextName: testsImplContextName,
-        variables: {
-            REQ_FILE: reqFilePath,
-            TEST_PLAN_FILE: testPlanFilePath,
-        },
-    };
+    return resolveStage('impl');
 }
+
 const featureBacklog = defineRecipe(function featureBacklog(options) {
-    const { configUrl, implValidateCommand, backlogItemsDir, ...rest } = options;
+    const { configUrl, implValidateCommand, backlogItemsDir, primaryDiscoveryBranch, itemDiscoveryBranchPrefix, promptFns, ...rest } = options;
+    const discovery = resolveFeatureBacklogDiscoveryOptions({
+        primaryDiscoveryBranch,
+        itemDiscoveryBranchPrefix,
+    });
     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,
+        includeUmbrellaParents: true,
+        ...rest,
+        discoveryBranches: [
+            discovery.primaryDiscoveryBranch,
+            `${discovery.itemDiscoveryBranchPrefix}/*`,
+        ],
         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,
@@ -1037,7 +1384,7 @@ const featureBacklog = defineRecipe(function featureBacklog(options) {
                 dependsOn: parentName
                     ? baseItem.dependsOn?.map((dep) => `${parentName}-${dep}`)
                     : baseItem.dependsOn,
-                manualReq: record.manualReq === true ? true : undefined,
+                manual: parseManual(baseItem.name, record),
                 workflow: parseFeatureWorkflow(baseItem.name, raw),
             };
         },
@@ -1047,177 +1394,55 @@ const featureBacklog = defineRecipe(function featureBacklog(options) {
                 paths,
                 projectRoot,
                 discoveryBranch,
+                primaryDiscoveryBranch: discovery.primaryDiscoveryBranch,
+                itemDiscoveryBranchPrefix: discovery.itemDiscoveryBranchPrefix,
             });
         },
         stages: {
-            makeReq: {
+            req: {
                 completion: 'keepPending',
                 steps: retryUntilGreen({
-                    steps: [
-                        {
-                            promptFn({ context: ctx }) {
-                                const vars = ctx.variables;
-                                const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, REQ_FILE } = vars;
-                                return `
-Write a requirements document for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
-
-Task name: ${TASK_NAME}
-
-Task:
-${TASK}
-
-Save the requirements document to @${REQ_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml.
-
-The requirements document should be self-contained and implementation-ready. Include:
-- Problem statement and motivation
-- Goals and non-goals
-- User stories / use cases
-- Docs updates (if relevant)
-- Proposed behavior and UX (for CLI work, include command syntax where relevant)
-- Technical approach and affected packages or docs
-- Acceptance criteria
-
-Do not implement the feature — only create the requirements markdown file.
-Do not wait the user to answer any questions — make the best assumptions and just write the requirements document.
-The requirements document should not contain any testing strategy details.
-                                `.trim();
-                            },
-                        },
-                    ],
+                    steps: [{ promptFn: promptFns?.req ?? defaultReqPrompt }],
                     validationCommandFn: requireArtifactStep('REQ_FILE'),
                     fixSteps: ({ prevValidateCommandResult }) => [
-                        {
-                            promptFn({ context: ctx }) {
-                                const vars = ctx.variables;
-                                const { BACKLOG_ITEM_DIR, REQ_FILE } = vars;
-                                return `
-The requirements document was not created at @${REQ_FILE}.
-
-Create it now at that exact path. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml.
-Do not implement the feature — only write the requirements markdown file.
-The requirements document should not contain any testing strategy details.
-
-Verification output:
-${prevValidateCommandResult ?? '(no output captured)'}
-                                `.trim();
-                            },
-                        },
+                        { promptFn: defaultReqFixPrompt(prevValidateCommandResult) },
                     ],
                 }),
             },
-            makeTestPlan: {
+            testPlan: {
                 completion: 'keepPending',
                 steps: retryUntilGreen({
-                    steps: [
-                        {
-                            promptFn({ context: ctx }) {
-                                const vars = ctx.variables;
-                                const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, REQ_FILE, TEST_PLAN_FILE } = vars;
-                                return `
-Write a test plan for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
-
-Task name: ${TASK_NAME}
-Task:
-${TASK}
-
-The requirements for this task are in @${REQ_FILE}. The test plan should match those requirements.
-
-Save the test plan to @${TEST_PLAN_FILE}. Do not edit @${BACKLOG_ITEM_DIR}/desc.yml nor @${REQ_FILE}.
-
-The test plan should be self-contained and implementation-ready. Include:
-- Test cases
-- Test data
-- Test expectations
-- Test implementation details
-                                `.trim();
-                            },
-                        },
-                    ],
+                    steps: [{ promptFn: promptFns?.testPlan ?? defaultTestPlanPrompt }],
                     validationCommandFn: requireArtifactStep('TEST_PLAN_FILE'),
                     fixSteps: ({ prevValidateCommandResult }) => [
-                        {
-                            promptFn({ context: ctx }) {
-                                const vars = ctx.variables;
-                                const { BACKLOG_ITEM_DIR, REQ_FILE, TEST_PLAN_FILE } = vars;
-                                return `
-The test plan was not created at @${TEST_PLAN_FILE}.
-
-Create it now at that exact path. Match the requirements in @${REQ_FILE}.
-Do not edit @${BACKLOG_ITEM_DIR}/desc.yml nor @${REQ_FILE}.
-
-Verification output:
-${prevValidateCommandResult ?? '(no output captured)'}
-                                `.trim();
-                            },
-                        },
+                        { promptFn: defaultTestPlanFixPrompt(prevValidateCommandResult) },
                     ],
                 }),
             },
             testImpl: {
                 completion: 'keepPending',
-                steps: [
-                    {
-                        promptFn({ context: ctx }) {
-                            const vars = ctx.variables;
-                            const { BACKLOG_ITEM_DIR, TASK_NAME, TASK, REQ_FILE, TEST_PLAN_FILE } = vars;
-                            return `
-Write a test implementation for the following backlog item from @${BACKLOG_ITEM_DIR}/desc.yml.
-
-The new tests should be skipped in order to not break the whole test suite.
-
-Task name: ${TASK_NAME}
-Task:
-${TASK}
-
-Follow the test plan in @${TEST_PLAN_FILE}.
-The requirements for this task are in @${REQ_FILE}.
-                            `.trim();
-                        },
-                    },
-                ],
+                steps: [{ promptFn: promptFns?.testImpl ?? defaultTestImplPrompt }],
             },
-            implementation: {
+            impl: {
                 completion: 'moveToDone',
                 steps: retryUntilGreen({
-                    steps: [
-                        {
-                            promptFn({ context: ctx }) {
-                                const vars = ctx.variables;
-                                const { REQ_FILE, TEST_PLAN_FILE } = vars;
-                                return `
-Implement the feature described in @${REQ_FILE}.
-The tests have already been implemented according to the test plan in @${TEST_PLAN_FILE}.
-Unskip all the tests that were skipped in the tests implementation.
-The implementation should make the tests pass. Do not edit any test file except to unskip them or if absolutely necessary.
-                                `.trim();
-                            },
-                        },
-                    ],
+                    steps: [{ promptFn: promptFns?.impl ?? defaultImplPrompt }],
                     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();
-                            },
-                        },
-                    ],
+                    steps: [{ promptFn: promptFns?.directImpl ?? defaultDirectImplPrompt }],
                     validationCommandFn: runImplValidation,
                 }),
             },
+            completion: {
+                completion: 'moveToDone',
+                steps: [],
+            },
         },
-        ...rest,
     });
 });
 
-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 { BACKLOG_ITEMS_DIR_VAR, BACKLOG_ITEM_DIR_VAR, BACKLOG_STAGE_VAR, BACKLOG_TASK_NAME_VAR, BACKLOG_TASK_VAR, DEFAULT_FEATURE_BACKLOG_WORKFLOW, DEFAULT_ITEM_DISCOVERY_BRANCH_PREFIX, DEFAULT_PRIMARY_DISCOVERY_BRANCH, FEATURE_BACKLOG_RESERVED_NAME_SUFFIXES, FEATURE_BACKLOG_WORKFLOW_STAGES, OPEN_PR_PROVIDERS, abstractionBacklog, abstractionFinder, backlog, backlogRecipe, defaultDirectImplPrompt, defaultImplPrompt, defaultReqFixPrompt, defaultReqPrompt, defaultTestImplPrompt, defaultTestPlanFixPrompt, defaultTestPlanPrompt, defineRecipe, ephemeralContextListFn, featureBacklog, folderBacklogContexts, folderSetTaskDoneStep, getRecursiveSteps, listTodoRelativeDirs, listUmbrellaTicketNames, lumpPathAndName, normalizeMaybePromGetter, openPrPostTeardown, parseFeatureWorkflow, projectRootFromConfigUrl, requireArtifactStep, resolveBacklogPaths, resolveFeatureBacklogDiscoveryOptions, resolveFeatureBacklogItem, resolveImplValidateCommand, retryUntilGreen, setTaskDoneStep, shellCommand, validateBaseBacklogItem, ymlBacklogContexts };