@nyxa/nyx-agent 0.9.1 → 0.9.3

package/dist/runtime/prompts.js

@@ -6,15 +6,17 @@
  * prompt is pure guidance — NyxAgent prepends an engine-owned context block and,
  * for review-style phases, appends the required-result contract + JSON Schema.
  */
-export const SELECTION_PROMPT = `Select and order the GitHub issues to work on in this run.
+export const SELECTION_PROMPT = `Select the GitHub issue series to work on in this run.
 
-The available open issues (candidates) are listed in the context above. Choose the
-ones that form a coherent unit of work for this run and order them so prerequisites
-come first. You may select a subset; skip issues that are unclear, blocked, or out
-of scope. Do not invent keys — only use keys present in the candidates.
+The context lists recommended executable series, blockers, and available open
+issues by PRD/Plan section. Choose the coherent series or issue set that should be
+started now. Prefer the recommended executable order when it matches the intent.
+Skip issues with open blockers. Closed blockers are satisfied. Do not invent keys
+— only use keys present in the candidates.
 
-Return outcome "selected" with the ordered keys in a work_item_keys array. If
-nothing is worth working on, return outcome "no_work" instead.`;
+Return outcome "selected" with the chosen intent keys in a work_item_keys array;
+the engine will expand PRD/Plan series and prerequisites safely. If nothing is
+worth working on, return outcome "no_work" instead.`;
 export const EXECUTION_PROMPT = `Implement the selected work item described in the context above.
 
 Work only on this item. Keep changes focused and coherent. Use a

package/dist/runtime/runPipeline.js

@@ -11,7 +11,8 @@ import { createRunReporter } from "./reporter.js";
 import { runAgentPhase, } from "./runPhase.js";
 import { REVIEW_CHALLENGE_SCHEMA, REVIEW_DISCOVERY_SCHEMA, GLOBAL_REVIEW_SCHEMA, REVIEW_VALIDATION_SCHEMA, SELECTION_SCHEMA, } from "./schemas.js";
 import { commitAll, commitsAhead, createPullRequest, pushBranch, rangeDiff, stageAllAndDiff, } from "./scm.js";
-import { buildSelectionSections, confirmWorkItemSelection, } from "./selectionConfirmation.js";
+import { confirmWorkItemSelection, } from "./selectionConfirmation.js";
+import { buildWorkItemSelectionPlan, formatSelectionBlockers, isDependencySatisfied, normalizeWorkItemSelection, } from "./selectionPlanner.js";
 import { createRunId } from "./time.js";
 import { filterAvailable, listGitHubWorkItemInventory, resolveSelectedQueue, } from "./workItems.js";
 const MAX_CANDIDATES = 50;
@@ -73,12 +74,18 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         reporter.info("No open work items available. Nothing to do.");
         return;
     }
+    const selectionPlan = buildWorkItemSelectionPlan({
+        candidates,
+        maxItems: config.max_iterations,
+        completedKeys: ledger.completed_work_item_keys,
+    });
     const proposed = await runSelection({
         projectRoot,
         runDir,
         cliHarness: input.harness,
         config,
         candidates,
+        completedKeys: ledger.completed_work_item_keys,
         runPhase: deps.runPhase,
         reporter,
     });
@@ -87,7 +94,7 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         return;
     }
     const selected = await deps.confirmSelection({
-        candidates,
+        candidates: selectionPlan.candidateOrder,
         proposed,
         maxItems: config.max_iterations,
         autoAccept: input.autoAcceptSelection ?? false,
@@ -96,7 +103,31 @@ export async function runPipeline(input = {}, deps = defaultPipelineDependencies
         reporter.info("No work items selected. Nothing to do.");
         return;
     }
-    const planned = selected.slice(0, config.max_iterations);
+    const finalSelection = normalizeWorkItemSelection({
+        candidates,
+        selected,
+        maxItems: config.max_iterations,
+        expandGroups: false,
+        strictMax: true,
+        completedKeys: ledger.completed_work_item_keys,
+    });
+    if (!finalSelection.ok) {
+        throw new Error(finalSelection.error);
+    }
+    if (finalSelection.blockedCandidates.length > 0) {
+        reporter.warn(`Skipping blocked work item(s): ${formatSelectionBlockers(finalSelection.blockedCandidates)}`);
+    }
+    if (finalSelection.queue.length === 0) {
+        reporter.info("No executable work items selected. Nothing to do.");
+        return;
+    }
+    if (finalSelection.cycleKeys.length > 0) {
+        reporter.detail(`Dependency cycle detected among selected work items; preserving confirmed order inside cycle(s): ${formatDependencyCycles({
+            cycles: finalSelection.cycleKeys,
+            items: selected,
+        })}`);
+    }
+    const planned = finalSelection.queue;
     reporter.info(`Selected ${planned.length} work item(s):`);
     for (const item of planned) {
         reporter.info(`  - ${item.title} (#${item.number})`);
@@ -280,14 +311,30 @@ async function runSelection(input) {
         config: input.config,
         cliHarness: input.cliHarness,
     });
+    const selectionPlan = buildWorkItemSelectionPlan({
+        candidates: input.candidates,
+        maxItems: input.config.max_iterations,
+        completedKeys: input.completedKeys,
+    });
+    const candidateKeys = new Set(input.candidates.map((candidate) => candidate.key));
+    const completedKeys = new Set(input.completedKeys);
     const context = buildContextBlock([
         ["Repository", input.config.tracker.repo],
         ["Max work items this run", input.config.max_iterations],
+        [
+            "Recommended executable series",
+            selectionPlan.recommendedSeries.map(selectionSeriesSummary),
+        ],
+        [
+            "Blocked candidates",
+            selectionPlan.blockedCandidates.map(selectionBlockerSummary),
+        ],
         [
             "Available candidates",
-            buildSelectionSections(input.candidates).map((section) => ({
+            selectionPlan.sections.map((section) => ({
                 section: section.label ?? "Ungrouped issues",
-                candidates: section.candidates.map(selectionCandidateSummary),
+                recommended_order: section.recommended.map(workItemReference),
+                candidates: section.candidates.map((candidate) => selectionCandidateSummary(candidate, candidateKeys, completedKeys)),
             })),
         ],
     ]);
@@ -321,7 +368,23 @@ async function runSelection(input) {
     if (!resolved.ok) {
         throw new Error(`Selection produced an invalid queue: ${resolved.error}`);
     }
-    return resolved.queue;
+    const normalized = normalizeWorkItemSelection({
+        candidates: input.candidates,
+        selected: resolved.queue,
+        maxItems: input.config.max_iterations,
+        expandGroups: true,
+        completedKeys: input.completedKeys,
+    });
+    if (!normalized.ok) {
+        throw new Error(normalized.error);
+    }
+    if (normalized.blockedCandidates.length > 0) {
+        input.reporter.detail(`Selection omitted blocked work item(s): ${formatSelectionBlockers(normalized.blockedCandidates)}`);
+    }
+    if (normalized.truncated) {
+        input.reporter.detail(`Selection truncated to ${input.config.max_iterations} work item(s) after dependency planning.`);
+    }
+    return normalized.queue;
 }
 async function runExecution(input) {
     const agent = resolveAgentProfile({
@@ -874,18 +937,76 @@ function workItemSummary(item) {
         url: item.url,
         labels: item.labels,
         parent: item.parent,
+        blocked_by: item.blocked_by,
     };
 }
-function selectionCandidateSummary(candidate) {
+function selectionSeriesSummary(series) {
+    return {
+        section: series.section ?? "Ungrouped issues",
+        work_item_keys: series.candidates.map((candidate) => candidate.key),
+        order: series.candidates.map(workItemReference),
+        blocked: series.blocked.map(selectionBlockerSummary),
+        truncated: series.truncated,
+    };
+}
+function selectionBlockerSummary(blocked) {
+    return {
+        candidate: workItemReference(blocked.candidate),
+        blockers: blocked.blockers.map(dependencyReference),
+    };
+}
+function selectionCandidateSummary(candidate, candidateKeys, completedKeys) {
     return {
         key: candidate.key,
         number: candidate.number,
         title: candidate.title,
         labels: candidate.labels,
         parent: candidate.parent,
+        blocked_by: candidate.blocked_by,
+        dependency_status: dependencyStatusSummary({
+            dependencies: candidate.blocked_by ?? [],
+            candidateKeys,
+            completedKeys,
+        }),
         excerpt: candidate.excerpt,
     };
 }
+function dependencyStatusSummary(input) {
+    const selectablePrerequisites = [];
+    const satisfiedBlockers = [];
+    const openBlockers = [];
+    for (const dependency of input.dependencies) {
+        if (input.candidateKeys.has(dependency.key)) {
+            selectablePrerequisites.push(dependency);
+            continue;
+        }
+        if (isDependencySatisfied(dependency, input.completedKeys)) {
+            satisfiedBlockers.push(dependency);
+            continue;
+        }
+        openBlockers.push(dependency);
+    }
+    return {
+        selectable_prerequisites: selectablePrerequisites.map(dependencyReference),
+        satisfied_blockers: satisfiedBlockers.map(dependencyReference),
+        open_blockers: openBlockers.map(dependencyReference),
+    };
+}
+function workItemReference(item) {
+    return {
+        key: item.key,
+        number: item.number,
+        title: item.title,
+    };
+}
+function dependencyReference(dependency) {
+    return {
+        key: dependency.key,
+        number: dependency.number,
+        title: dependency.title,
+        state: dependency.state,
+    };
+}
 function buildCommitMessage(item) {
     return `${item.title}\n\nWork item: ${item.source.locator}`;
 }
@@ -973,6 +1094,17 @@ function completedParentClosures(input) {
 function uniqueNumbers(numbers) {
     return [...new Set(numbers)];
 }
+function formatDependencyCycles(input) {
+    const itemByKey = new Map(input.items.map((item) => [item.key, item]));
+    return input.cycles
+        .map((cycle) => cycle
+        .map((key) => {
+        const item = itemByKey.get(key);
+        return item ? `#${item.number}` : key;
+    })
+        .join(" -> "))
+        .join("; ");
+}
 /** Render unresolved blockers as a bullet list to append to a failure message. */
 function formatBlockers(blockers) {
     if (blockers.length === 0) {

package/dist/runtime/selectionConfirmation.js

@@ -1,4 +1,6 @@
 import { checkbox, Separator } from "@inquirer/prompts";
+import { buildWorkItemSelectionPlan, formatSelectionBlockers, normalizeWorkItemSelection, } from "./selectionPlanner.js";
+export { buildSelectionSections } from "./selectionPlanner.js";
 export async function confirmWorkItemSelection(input) {
     if (input.autoAccept) {
         return input.proposed;
@@ -8,70 +10,84 @@ export async function confirmWorkItemSelection(input) {
         throw new Error('Interactive work item selection requires a TTY. Re-run with "nyxagent run --yes" to accept the agent selection.');
     }
     const choiceItems = buildSelectionChoiceItems(input);
+    const choiceOrder = choiceItems
+        .filter((item) => item.type === "choice")
+        .map((item) => item.value);
     const selectedKeys = await checkbox({
         message: `Select work items to run (max ${input.maxItems})`,
         choices: choiceItems.map(toInquirerChoice),
         pageSize: Math.min(Math.max(choiceItems.length, 7), 20),
         required: false,
-        validate: (selected) => selected.length <= input.maxItems ||
-            `Select at most ${input.maxItems} work item(s).`,
+        validate: (selected) => {
+            const normalized = normalizeSelectedKeys({
+                selectedKeys: selected.map((choice) => choice.value),
+                choiceOrder,
+                candidates: input.candidates,
+                maxItems: input.maxItems,
+            });
+            if (!normalized.ok) {
+                return normalized.error;
+            }
+            if (normalized.blockedCandidates.length > 0) {
+                return `Selection contains blocked work item(s): ${formatSelectionBlockers(normalized.blockedCandidates)}`;
+            }
+            return true;
+        },
         shortcuts: {
             all: null,
             invert: null,
         },
     });
-    const selected = new Set(selectedKeys);
-    const candidatesByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
-    return choiceItems.flatMap((item) => {
-        if (item.type !== "choice" || !selected.has(item.value)) {
-            return [];
-        }
-        const candidate = candidatesByKey.get(item.value);
-        return candidate ? [candidate] : [];
+    const normalized = normalizeSelectedKeys({
+        selectedKeys,
+        choiceOrder,
+        candidates: input.candidates,
+        maxItems: input.maxItems,
     });
+    if (!normalized.ok) {
+        throw new Error(normalized.error);
+    }
+    return normalized.queue;
 }
 export function buildSelectionChoiceItems(input) {
-    const proposedKeys = new Set(input.proposed.map((item) => item.key));
+    const plan = buildWorkItemSelectionPlan({
+        candidates: input.candidates,
+        proposed: input.proposed,
+        maxItems: input.maxItems ?? input.candidates.length,
+    });
+    const proposedKeys = new Set(plan.recommendedQueue.map((item) => item.key));
+    const blockedByKey = new Map(plan.blockedCandidates.map((blocked) => [blocked.candidate.key, blocked]));
     const items = [];
-    for (const section of buildSelectionSections(input.candidates)) {
+    appendSelectionChoices({
+        items,
+        sections: plan.sections,
+        proposedKeys,
+        blockedByKey,
+    });
+    return items;
+}
+function appendSelectionChoices(input) {
+    for (const section of input.sections) {
         if (section.label) {
-            items.push({ type: "separator", label: section.label });
+            input.items.push({ type: "separator", label: section.label });
         }
         for (const candidate of section.candidates) {
-            const proposed = proposedKeys.has(candidate.key);
-            items.push({
+            const proposed = input.proposedKeys.has(candidate.key);
+            const blocked = input.blockedByKey.get(candidate.key);
+            const item = {
                 type: "choice",
                 value: candidate.key,
                 name: `#${candidate.number} ${candidate.title}${proposed ? " (agent)" : ""}`,
                 checked: proposed,
-            });
-        }
-    }
-    return items;
-}
-export function buildSelectionSections(candidates) {
-    const sections = [];
-    const groupedSections = new Map();
-    let ungroupedSection;
-    for (const candidate of candidates) {
-        const group = detectSelectionGroup(candidate);
-        if (!group) {
-            if (!ungroupedSection) {
-                ungroupedSection = { candidates: [] };
-                sections.push(ungroupedSection);
+            };
+            if (blocked) {
+                item.disabled = `blocked by ${blocked.blockers
+                    .map((blocker) => `#${blocker.number}`)
+                    .join(", ")}`;
             }
-            ungroupedSection.candidates.push(candidate);
-            continue;
-        }
-        let section = groupedSections.get(group.key);
-        if (!section) {
-            section = { label: group.label, candidates: [] };
-            groupedSections.set(group.key, section);
-            sections.push(section);
+            input.items.push(item);
         }
-        section.candidates.push(candidate);
     }
-    return sections;
 }
 function toInquirerChoice(item) {
     if (item.type === "separator") {
@@ -81,72 +97,21 @@ function toInquirerChoice(item) {
         value: item.value,
         name: item.name,
         checked: item.checked,
+        disabled: item.disabled,
     };
 }
-function detectSelectionGroup(candidate) {
-    if (candidate.parent) {
-        return {
-            key: `parent:${candidate.parent.key}`,
-            label: formatParentGroup(candidate.parent),
-        };
-    }
-    for (const label of candidate.labels ?? []) {
-        const group = parseGroupLabel(label);
-        if (group) {
-            return { key: `display:${group.toLowerCase()}`, label: group };
-        }
-    }
-    const titleGroup = parseBracketedTitleGroup(candidate.title);
-    return titleGroup
-        ? { key: `display:${titleGroup.toLowerCase()}`, label: titleGroup }
-        : undefined;
-}
-function formatParentGroup(parent) {
-    if (!parent) {
-        return "Parent";
-    }
-    if (!parent.title) {
-        return `Parent #${parent.number}`;
-    }
-    const titledGroup = parseLeadingTitleGroup(parent.title);
-    if (titledGroup) {
-        return `${titledGroup.kind} #${parent.number}: ${titledGroup.name}`;
-    }
-    return `Parent #${parent.number}: ${parent.title}`;
-}
-function parseGroupLabel(label) {
-    const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(label.trim());
-    if (!match) {
-        return undefined;
-    }
-    return formatGroupLabel(match[1], match[2]);
-}
-function parseBracketedTitleGroup(title) {
-    const match = /^\[(plan|prd)\s*[:/=-]\s*([^\]]+)\]/i.exec(title.trim());
-    if (!match) {
-        return undefined;
-    }
-    return formatGroupLabel(match[1], match[2]);
-}
-function parseLeadingTitleGroup(title) {
-    const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(title.trim());
-    if (!match) {
-        return undefined;
-    }
-    const name = match[2].trim();
-    if (!name) {
-        return undefined;
-    }
-    return {
-        kind: match[1].toLowerCase() === "prd" ? "PRD" : "Plan",
-        name,
-    };
-}
-function formatGroupLabel(kind, rawName) {
-    const name = rawName.trim();
-    if (!name) {
-        return undefined;
-    }
-    const prefix = kind.toLowerCase() === "prd" ? "PRD" : "Plan";
-    return `${prefix}: ${name}`;
+function normalizeSelectedKeys(input) {
+    const selected = new Set(input.selectedKeys);
+    const candidatesByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
+    const orderedSelected = input.choiceOrder.flatMap((key) => {
+        const candidate = candidatesByKey.get(key);
+        return candidate && selected.has(key) ? [candidate] : [];
+    });
+    return normalizeWorkItemSelection({
+        candidates: input.candidates,
+        selected: orderedSelected,
+        maxItems: input.maxItems,
+        expandGroups: false,
+        strictMax: true,
+    });
 }

package/dist/runtime/selectionPlanner.js

@@ -0,0 +1,406 @@
+import { orderWorkItemsByDependencies, } from "./workItems.js";
+export function buildWorkItemSelectionPlan(input) {
+    const context = createPlanningContext(input);
+    const recommended = input.proposed
+        ? normalizeWithContext(context, {
+            selected: input.proposed,
+            maxItems: input.maxItems,
+            expandGroups: true,
+        })
+        : emptyNormalizedSelection();
+    const plannedSections = context.sections.map((section) => {
+        const sectionSeries = buildSectionSeries({
+            context,
+            section,
+            maxItems: input.maxItems,
+        });
+        return {
+            label: section.label,
+            candidates: section.candidates,
+            recommended: sectionSeries.queue,
+            blocked: section.candidates.flatMap((candidate) => blockerForCandidate(context, candidate)),
+        };
+    });
+    return {
+        sections: plannedSections,
+        recommendedSeries: plannedSections
+            .map((section) => ({
+            section: section.label,
+            candidates: section.recommended,
+            blocked: section.blocked,
+            truncated: section.recommended.length > 0 &&
+                section.recommended.length === input.maxItems &&
+                section.candidates.some((candidate) => !section.recommended.some((item) => item.key === candidate.key)),
+        }))
+            .filter((series) => series.candidates.length > 0 || series.blocked.length > 0),
+        recommendedQueue: recommended.ok ? recommended.queue : recommended.queue,
+        candidateOrder: context.sections.flatMap((section) => section.candidates),
+        blockedCandidates: [...context.blockedByKey.values()],
+        cycleKeys: recommended.cycleKeys,
+        truncated: recommended.truncated,
+    };
+}
+export function normalizeWorkItemSelection(input) {
+    return normalizeWithContext(createPlanningContext(input), input);
+}
+export function buildSelectionSections(candidates) {
+    const sections = [];
+    const groupedSections = new Map();
+    let ungroupedSection;
+    for (const candidate of candidates) {
+        const group = detectSelectionGroup(candidate);
+        if (!group) {
+            if (!ungroupedSection) {
+                ungroupedSection = { candidates: [] };
+                sections.push(ungroupedSection);
+            }
+            ungroupedSection.candidates.push(candidate);
+            continue;
+        }
+        let section = groupedSections.get(group.key);
+        if (!section) {
+            section = { label: group.label, candidates: [] };
+            groupedSections.set(group.key, section);
+            sections.push(section);
+        }
+        section.candidates.push(candidate);
+    }
+    return sections.map((section) => ({
+        label: section.label,
+        candidates: orderCandidatesForPlanning(section.candidates),
+    }));
+}
+export function isDependencySatisfied(dependency, completedKeys = new Set()) {
+    return (completedKeys.has(dependency.key) ||
+        dependency.state?.toLowerCase() === "closed");
+}
+export function formatSelectionBlockers(blocked) {
+    return blocked
+        .map((item) => `#${item.candidate.number} blocked by ${item.blockers
+        .map(formatDependencyReference)
+        .join(", ")}`)
+        .join("; ");
+}
+function buildSectionSeries(input) {
+    const first = input.section.candidates[0];
+    if (!first) {
+        return emptyNormalizedSelection();
+    }
+    return normalizeWithContext(input.context, {
+        selected: [first],
+        maxItems: input.maxItems,
+        expandGroups: Boolean(input.section.label),
+    });
+}
+function normalizeWithContext(context, input) {
+    if (input.selected.length === 0) {
+        return emptyNormalizedSelection();
+    }
+    const selected = dedupeCandidates(input.selected.flatMap((candidate) => {
+        const resolved = context.candidateByKey.get(candidate.key);
+        return resolved ? [resolved] : [];
+    }));
+    const selectedOrder = new Map(selected.map((candidate, index) => [candidate.key, index]));
+    const targetKeys = selectionTargetKeys({
+        context,
+        selected,
+        expandGroups: input.expandGroups,
+    });
+    const targetIndex = new Map(targetKeys.map((key, index) => [key, index]));
+    const closureKeys = new Set();
+    const blockedByKey = new Map();
+    const visiting = new Set();
+    const resolved = new Map();
+    const includeCandidate = (key) => {
+        const cached = resolved.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const candidate = context.candidateByKey.get(key);
+        if (!candidate) {
+            return false;
+        }
+        if (visiting.has(key)) {
+            return true;
+        }
+        visiting.add(key);
+        const blockers = [];
+        for (const dependency of candidate.blocked_by ?? []) {
+            const dependencyCandidate = context.candidateByKey.get(dependency.key);
+            if (dependencyCandidate) {
+                if (!includeCandidate(dependencyCandidate.key)) {
+                    blockers.push(enrichDependencyFromCandidate(dependency, dependencyCandidate));
+                }
+                continue;
+            }
+            if (!isDependencySatisfied(dependency, context.completedKeys)) {
+                blockers.push(dependency);
+            }
+        }
+        visiting.delete(key);
+        const ok = blockers.length === 0;
+        if (ok) {
+            closureKeys.add(key);
+        }
+        else {
+            blockedByKey.set(candidate.key, {
+                candidate,
+                blockers: dedupeDependencies(blockers),
+            });
+        }
+        resolved.set(key, ok);
+        return ok;
+    };
+    for (const key of targetKeys) {
+        includeCandidate(key);
+    }
+    const preOrdered = [...closureKeys]
+        .flatMap((key) => {
+        const candidate = context.candidateByKey.get(key);
+        return candidate ? [candidate] : [];
+    })
+        .sort((a, b) => compareSelectionCandidates({
+        a,
+        b,
+        targetIndex,
+        selectedOrder,
+        canonicalIndex: context.canonicalIndex,
+    }));
+    const ordered = orderWorkItemsByDependencies(preOrdered);
+    const requiredCount = ordered.queue.length;
+    if (input.strictMax && requiredCount > input.maxItems) {
+        return {
+            ok: false,
+            error: `Selection expands to ${requiredCount} work item(s) after prerequisites; max is ${input.maxItems}.`,
+            queue: ordered.queue.slice(0, input.maxItems),
+            cycleKeys: ordered.cycleKeys,
+            blockedCandidates: [...blockedByKey.values()],
+            requiredCount,
+            truncated: true,
+        };
+    }
+    return {
+        ok: true,
+        queue: ordered.queue.slice(0, input.maxItems),
+        cycleKeys: ordered.cycleKeys,
+        blockedCandidates: [...blockedByKey.values()],
+        requiredCount,
+        truncated: requiredCount > input.maxItems,
+    };
+}
+function createPlanningContext(input) {
+    const sections = buildSelectionSections(input.candidates);
+    const candidateOrder = sections.flatMap((section) => section.candidates);
+    const candidateByKey = new Map(input.candidates.map((candidate) => [candidate.key, candidate]));
+    const sectionByCandidateKey = new Map();
+    const canonicalIndex = new Map();
+    const completedKeys = new Set(input.completedKeys ?? []);
+    for (const [index, candidate] of candidateOrder.entries()) {
+        canonicalIndex.set(candidate.key, index);
+    }
+    for (const section of sections) {
+        for (const candidate of section.candidates) {
+            sectionByCandidateKey.set(candidate.key, section);
+        }
+    }
+    const context = {
+        candidates: input.candidates,
+        candidateByKey,
+        completedKeys,
+        sections,
+        sectionByCandidateKey,
+        canonicalIndex,
+        blockedByKey: new Map(),
+    };
+    context.blockedByKey = collectBlockedCandidates(context);
+    return context;
+}
+function collectBlockedCandidates(context) {
+    const blockedByKey = new Map();
+    const visiting = new Set();
+    const blockersFor = (candidate) => {
+        const cached = blockedByKey.get(candidate.key);
+        if (cached) {
+            return cached.blockers;
+        }
+        if (visiting.has(candidate.key)) {
+            return [];
+        }
+        visiting.add(candidate.key);
+        const blockers = [];
+        for (const dependency of candidate.blocked_by ?? []) {
+            const dependencyCandidate = context.candidateByKey.get(dependency.key);
+            if (dependencyCandidate) {
+                if (blockersFor(dependencyCandidate).length > 0) {
+                    blockers.push(enrichDependencyFromCandidate(dependency, dependencyCandidate));
+                }
+                continue;
+            }
+            if (!isDependencySatisfied(dependency, context.completedKeys)) {
+                blockers.push(dependency);
+            }
+        }
+        visiting.delete(candidate.key);
+        if (blockers.length > 0) {
+            blockedByKey.set(candidate.key, {
+                candidate,
+                blockers: dedupeDependencies(blockers),
+            });
+        }
+        return blockers;
+    };
+    for (const candidate of context.candidates) {
+        blockersFor(candidate);
+    }
+    return blockedByKey;
+}
+function selectionTargetKeys(input) {
+    const keys = [];
+    const seen = new Set();
+    for (const candidate of input.selected) {
+        const section = input.context.sectionByCandidateKey.get(candidate.key);
+        const sectionCandidates = input.expandGroups && section?.label ? section.candidates : [candidate];
+        for (const item of sectionCandidates) {
+            if (!seen.has(item.key)) {
+                seen.add(item.key);
+                keys.push(item.key);
+            }
+        }
+    }
+    return keys;
+}
+function orderCandidatesForPlanning(candidates) {
+    const byNumber = [...candidates].sort(compareByIssueNumber);
+    return orderWorkItemsByDependencies(byNumber).queue;
+}
+function compareSelectionCandidates(input) {
+    const aRank = selectionCandidateRank(input.a, input);
+    const bRank = selectionCandidateRank(input.b, input);
+    if (aRank !== bRank) {
+        return aRank - bRank;
+    }
+    return compareByIssueNumber(input.a, input.b);
+}
+function selectionCandidateRank(candidate, input) {
+    return (input.targetIndex.get(candidate.key) ??
+        input.selectedOrder.get(candidate.key) ??
+        input.canonicalIndex.get(candidate.key) ??
+        Number.MAX_SAFE_INTEGER);
+}
+function compareByIssueNumber(a, b) {
+    if (a.number !== b.number) {
+        return a.number - b.number;
+    }
+    return a.title.localeCompare(b.title);
+}
+function blockerForCandidate(context, candidate) {
+    const blocker = context.blockedByKey.get(candidate.key);
+    return blocker ? [blocker] : [];
+}
+function enrichDependencyFromCandidate(dependency, candidate) {
+    return {
+        ...dependency,
+        title: dependency.title ?? candidate.title,
+        state: dependency.state ?? "open",
+    };
+}
+function dedupeCandidates(candidates) {
+    const seen = new Set();
+    const deduped = [];
+    for (const candidate of candidates) {
+        if (seen.has(candidate.key)) {
+            continue;
+        }
+        seen.add(candidate.key);
+        deduped.push(candidate);
+    }
+    return deduped;
+}
+function dedupeDependencies(dependencies) {
+    const byKey = new Map();
+    for (const dependency of dependencies) {
+        byKey.set(dependency.key, dependency);
+    }
+    return [...byKey.values()];
+}
+function formatDependencyReference(dependency) {
+    const state = dependency.state ? ` (${dependency.state})` : "";
+    return `#${dependency.number}${state}`;
+}
+function emptyNormalizedSelection() {
+    return {
+        ok: true,
+        queue: [],
+        cycleKeys: [],
+        blockedCandidates: [],
+        requiredCount: 0,
+        truncated: false,
+    };
+}
+function detectSelectionGroup(candidate) {
+    if (candidate.parent) {
+        return {
+            key: `parent:${candidate.parent.key}`,
+            label: formatParentGroup(candidate.parent),
+        };
+    }
+    for (const label of candidate.labels ?? []) {
+        const group = parseGroupLabel(label);
+        if (group) {
+            return { key: `display:${group.toLowerCase()}`, label: group };
+        }
+    }
+    const titleGroup = parseBracketedTitleGroup(candidate.title);
+    return titleGroup
+        ? { key: `display:${titleGroup.toLowerCase()}`, label: titleGroup }
+        : undefined;
+}
+function formatParentGroup(parent) {
+    if (!parent) {
+        return "Parent";
+    }
+    if (!parent.title) {
+        return `Parent #${parent.number}`;
+    }
+    const titledGroup = parseLeadingTitleGroup(parent.title);
+    if (titledGroup) {
+        return `${titledGroup.kind} #${parent.number}: ${titledGroup.name}`;
+    }
+    return `Parent #${parent.number}: ${parent.title}`;
+}
+function parseGroupLabel(label) {
+    const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(label.trim());
+    if (!match) {
+        return undefined;
+    }
+    return formatGroupLabel(match[1], match[2]);
+}
+function parseBracketedTitleGroup(title) {
+    const match = /^\[(plan|prd)\s*[:/=-]\s*([^\]]+)\]/i.exec(title.trim());
+    if (!match) {
+        return undefined;
+    }
+    return formatGroupLabel(match[1], match[2]);
+}
+function parseLeadingTitleGroup(title) {
+    const match = /^(plan|prd)\s*[:/=-]\s*(.+)$/i.exec(title.trim());
+    if (!match) {
+        return undefined;
+    }
+    const name = match[2].trim();
+    if (!name) {
+        return undefined;
+    }
+    return {
+        kind: match[1].toLowerCase() === "prd" ? "PRD" : "Plan",
+        name,
+    };
+}
+function formatGroupLabel(kind, rawName) {
+    const name = rawName.trim();
+    if (!name) {
+        return undefined;
+    }
+    const prefix = kind.toLowerCase() === "prd" ? "PRD" : "Plan";
+    return `${prefix}: ${name}`;
+}

package/dist/runtime/workItems.js

@@ -118,11 +118,13 @@ async function listOpenGitHubIssueRecords(input) {
     if (!Array.isArray(issues)) {
         throw new Error("gh issue list returned JSON that is not an array");
     }
-    return issues.slice(0, input.maxCandidates).map((issue) => normalizeIssueRecord({
+    const records = issues.slice(0, input.maxCandidates).map((issue) => normalizeIssueRecord({
         issue,
         repo: input.repo,
         excerptChars: input.excerptChars,
     }));
+    await attachBlockedByDependencies({ records, repo: input.repo });
+    return records;
 }
 export function filterAvailable(input) {
     const completed = new Set(input.completedKeys);
@@ -155,6 +157,79 @@ export function resolveSelectedQueue(input) {
     }
     return { ok: true, queue };
 }
+export function orderWorkItemsByDependencies(queue) {
+    const selectedKeys = new Set(queue.map((item) => item.key));
+    const itemByKey = new Map(queue.map((item) => [item.key, item]));
+    const originalIndex = new Map(queue.map((item, index) => [item.key, index]));
+    const dependenciesByKey = new Map();
+    for (const item of queue) {
+        const seen = new Set();
+        const dependencies = (item.blocked_by ?? [])
+            .map((dependency) => dependency.key)
+            .filter((key) => {
+            if (!selectedKeys.has(key) || seen.has(key)) {
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+        dependenciesByKey.set(item.key, dependencies);
+    }
+    const components = findDependencyComponents({
+        keys: queue.map((item) => item.key),
+        dependenciesByKey,
+    });
+    const componentByKey = new Map();
+    for (const [index, component] of components.entries()) {
+        for (const key of component) {
+            componentByKey.set(key, index);
+        }
+    }
+    const componentDependsOn = new Map();
+    const dependentsByComponent = new Map();
+    for (const [key, dependencies] of dependenciesByKey) {
+        const component = componentByKey.get(key);
+        if (component === undefined) {
+            continue;
+        }
+        for (const dependencyKey of dependencies) {
+            const dependencyComponent = componentByKey.get(dependencyKey);
+            if (dependencyComponent === undefined ||
+                dependencyComponent === component) {
+                continue;
+            }
+            let dependsOn = componentDependsOn.get(component);
+            if (!dependsOn) {
+                dependsOn = new Set();
+                componentDependsOn.set(component, dependsOn);
+            }
+            dependsOn.add(dependencyComponent);
+            let dependents = dependentsByComponent.get(dependencyComponent);
+            if (!dependents) {
+                dependents = new Set();
+                dependentsByComponent.set(dependencyComponent, dependents);
+            }
+            dependents.add(component);
+        }
+    }
+    const orderedComponentIndexes = orderDependencyComponents({
+        components,
+        componentDependsOn,
+        dependentsByComponent,
+        itemByKey,
+        originalIndex,
+    });
+    const ordered = orderedComponentIndexes.flatMap((componentIndex) => sortKeysByOriginalOrder(components[componentIndex], originalIndex).flatMap((key) => {
+        const item = itemByKey.get(key);
+        return item ? [item] : [];
+    }));
+    return {
+        queue: ordered,
+        cycleKeys: components
+            .filter((component) => isCyclicDependencyComponent(component, dependenciesByKey))
+            .map((component) => sortKeysByOriginalOrder(component, originalIndex)),
+    };
+}
 function normalizeIssueRecord(input) {
     if (!isRecord(input.issue)) {
         throw new Error("gh issue list returned a non-object issue");
@@ -216,6 +291,60 @@ function normalizeIssueRecord(input) {
         details,
     };
 }
+async function attachBlockedByDependencies(input) {
+    const detailsByKey = new Map(input.records.map((record) => [record.candidate.key, record.details]));
+    const dependenciesByRecord = new Map();
+    const externalDependencies = new Map();
+    for (const record of input.records) {
+        const dependencies = parseBlockedByDependencies({
+            body: record.body,
+            repo: input.repo,
+        });
+        dependenciesByRecord.set(record, dependencies);
+        for (const dependency of dependencies) {
+            if (!detailsByKey.has(dependency.key)) {
+                externalDependencies.set(dependency.key, dependency);
+            }
+        }
+    }
+    const externalDetailsByKey = await fetchExternalDependencyDetails([
+        ...externalDependencies.values(),
+    ]);
+    for (const record of input.records) {
+        const dependencies = (dependenciesByRecord.get(record) ?? []).map((dependency) => {
+            const details = detailsByKey.get(dependency.key) ??
+                externalDetailsByKey.get(dependency.key);
+            if (!details) {
+                return dependency;
+            }
+            const enriched = { ...dependency };
+            if (details.title) {
+                enriched.title = details.title;
+            }
+            if (details.state) {
+                enriched.state = details.state;
+            }
+            return enriched;
+        });
+        if (dependencies.length > 0) {
+            record.candidate.blocked_by = dependencies;
+        }
+    }
+}
+async function fetchExternalDependencyDetails(dependencies) {
+    const detailsByKey = new Map();
+    for (const dependency of dependencies) {
+        const locator = parseGitHubIssueLocator(dependency.source.locator);
+        if (!locator) {
+            continue;
+        }
+        const details = await getGitHubIssue(locator);
+        if (details) {
+            detailsByKey.set(dependency.key, details);
+        }
+    }
+    return detailsByKey;
+}
 function buildExcerpt(content, maxChars) {
     if (maxChars <= 0) {
         return undefined;
@@ -383,6 +512,209 @@ function parseExplicitParentReferenceLine(line) {
     const number = Number.parseInt(match[1], 10);
     return Number.isInteger(number) && number > 0 ? number : undefined;
 }
+function parseBlockedByDependencies(input) {
+    if (!input.body) {
+        return [];
+    }
+    const dependencies = [];
+    let blockedBySectionLevel;
+    for (const line of input.body.split(/\r?\n/)) {
+        const heading = parseMarkdownHeading(line);
+        if (heading) {
+            if (blockedBySectionLevel !== undefined &&
+                heading.level <= blockedBySectionLevel) {
+                blockedBySectionLevel = undefined;
+            }
+            if (isBlockedByHeading(heading.title)) {
+                blockedBySectionLevel = heading.level;
+            }
+            continue;
+        }
+        dependencies.push(...parseDirectBlockedByLine({
+            line,
+            repo: input.repo,
+        }));
+        if (blockedBySectionLevel !== undefined) {
+            dependencies.push(...parseBlockedBySectionBullet({
+                line,
+                repo: input.repo,
+            }));
+        }
+    }
+    return dedupeDependencies(dependencies);
+}
+function parseDirectBlockedByLine(input) {
+    const line = normalizeMarkdownLinePrefix(input.line);
+    const match = /^blocked\s+by\s*:\s*(.+)$/i.exec(line);
+    return match
+        ? parseIssueReferences({ text: match[1], repo: input.repo })
+        : [];
+}
+function parseBlockedBySectionBullet(input) {
+    const line = normalizeMarkdownLinePrefix(input.line);
+    const match = /^[-*+]\s+(?:\[[ xX]\]\s+)?(.+)$/.exec(line);
+    return match
+        ? parseIssueReferences({ text: match[1], repo: input.repo })
+        : [];
+}
+function parseIssueReferences(input) {
+    const dependencies = [];
+    const issueRefPattern = /#(\d+)|([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#(\d+)|https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/(\d+)/gi;
+    for (const match of input.text.matchAll(issueRefPattern)) {
+        const repo = match[2] ??
+            (match[4] && match[5] ? `${match[4]}/${match[5]}` : input.repo);
+        const rawNumber = match[1] ?? match[3] ?? match[6];
+        const number = Number.parseInt(rawNumber, 10);
+        if (!repo || !Number.isInteger(number) || number <= 0) {
+            continue;
+        }
+        const locator = `${repo}#${number}`;
+        dependencies.push({
+            key: `github:${locator}`,
+            number,
+            source: { type: "github", locator },
+        });
+    }
+    return dedupeDependencies(dependencies);
+}
+function parseMarkdownHeading(line) {
+    const match = /^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        level: match[1].length,
+        title: match[2].trim().replace(/[:：]\s*$/, ""),
+    };
+}
+function isBlockedByHeading(title) {
+    return /^blocked\s+by$/i.test(title.trim());
+}
+function normalizeMarkdownLinePrefix(line) {
+    return line.trim().replace(/^>\s+/, "").trim();
+}
+function dedupeDependencies(dependencies) {
+    const byKey = new Map();
+    for (const dependency of dependencies) {
+        byKey.set(dependency.key, dependency);
+    }
+    return [...byKey.values()];
+}
+function findDependencyComponents(input) {
+    const components = [];
+    const indexByKey = new Map();
+    const lowLinkByKey = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let nextIndex = 0;
+    const visit = (key) => {
+        indexByKey.set(key, nextIndex);
+        lowLinkByKey.set(key, nextIndex);
+        nextIndex += 1;
+        stack.push(key);
+        onStack.add(key);
+        for (const dependencyKey of input.dependenciesByKey.get(key) ?? []) {
+            if (!indexByKey.has(dependencyKey)) {
+                visit(dependencyKey);
+                lowLinkByKey.set(key, Math.min(lowLinkByKey.get(key) ?? 0, lowLinkByKey.get(dependencyKey) ?? 0));
+                continue;
+            }
+            if (onStack.has(dependencyKey)) {
+                lowLinkByKey.set(key, Math.min(lowLinkByKey.get(key) ?? 0, indexByKey.get(dependencyKey) ?? 0));
+            }
+        }
+        if (lowLinkByKey.get(key) !== indexByKey.get(key)) {
+            return;
+        }
+        const component = [];
+        let member;
+        do {
+            member = stack.pop();
+            if (!member) {
+                break;
+            }
+            onStack.delete(member);
+            component.push(member);
+        } while (member !== key);
+        components.push(component);
+    };
+    for (const key of input.keys) {
+        if (!indexByKey.has(key)) {
+            visit(key);
+        }
+    }
+    return components;
+}
+function orderDependencyComponents(input) {
+    const indegree = input.components.map((_, index) => input.componentDependsOn.get(index)?.size ?? 0);
+    const available = input.components
+        .map((_, index) => index)
+        .filter((index) => indegree[index] === 0);
+    const ordered = [];
+    while (available.length > 0) {
+        available.sort((a, b) => compareDependencyComponents({
+            a,
+            b,
+            components: input.components,
+            itemByKey: input.itemByKey,
+            originalIndex: input.originalIndex,
+        }));
+        const component = available.shift();
+        if (component === undefined) {
+            break;
+        }
+        ordered.push(component);
+        for (const dependent of input.dependentsByComponent.get(component) ?? []) {
+            indegree[dependent] -= 1;
+            if (indegree[dependent] === 0) {
+                available.push(dependent);
+            }
+        }
+    }
+    if (ordered.length === input.components.length) {
+        return ordered;
+    }
+    const orderedSet = new Set(ordered);
+    return [
+        ...ordered,
+        ...input.components
+            .map((_, index) => index)
+            .filter((index) => !orderedSet.has(index))
+            .sort((a, b) => compareDependencyComponents({
+            a,
+            b,
+            components: input.components,
+            itemByKey: input.itemByKey,
+            originalIndex: input.originalIndex,
+        })),
+    ];
+}
+function compareDependencyComponents(input) {
+    const aIndex = minOriginalIndex(input.components[input.a], input.originalIndex);
+    const bIndex = minOriginalIndex(input.components[input.b], input.originalIndex);
+    if (aIndex !== bIndex) {
+        return aIndex - bIndex;
+    }
+    return (minIssueNumber(input.components[input.a], input.itemByKey) -
+        minIssueNumber(input.components[input.b], input.itemByKey));
+}
+function minOriginalIndex(keys, originalIndex) {
+    return Math.min(...keys.map((key) => originalIndex.get(key) ?? Number.MAX_SAFE_INTEGER));
+}
+function minIssueNumber(keys, itemByKey) {
+    return Math.min(...keys.map((key) => itemByKey.get(key)?.number ?? Number.MAX_SAFE_INTEGER));
+}
+function sortKeysByOriginalOrder(keys, originalIndex) {
+    return [...keys].sort((a, b) => (originalIndex.get(a) ?? Number.MAX_SAFE_INTEGER) -
+        (originalIndex.get(b) ?? Number.MAX_SAFE_INTEGER));
+}
+function isCyclicDependencyComponent(component, dependenciesByKey) {
+    if (component.length > 1) {
+        return true;
+    }
+    const key = component[0];
+    return (dependenciesByKey.get(key) ?? []).includes(key);
+}
 function parseGitHubRepo(repo) {
     const [owner, repoName, ...rest] = repo.split("/");
     if (!owner || !repoName || rest.length > 0) {
@@ -390,6 +722,26 @@ function parseGitHubRepo(repo) {
     }
     return { owner, repoName };
 }
+function parseGitHubIssueLocator(locator) {
+    const separator = locator.lastIndexOf("#");
+    if (separator <= 0 || separator === locator.length - 1) {
+        return undefined;
+    }
+    const repo = locator.slice(0, separator);
+    const issueNumber = Number.parseInt(locator.slice(separator + 1), 10);
+    if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+        return undefined;
+    }
+    try {
+        return {
+            ...parseGitHubRepo(repo),
+            issueNumber,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function getGitHubParentIssue(input) {
     const result = await ghApi([
         `repos/${input.owner}/${input.repoName}/issues/${input.issueNumber}/parent`,
@@ -419,6 +771,15 @@ async function listGitHubSubIssues(input) {
             .filter((issue) => Boolean(issue)),
     };
 }
+async function getGitHubIssue(input) {
+    const result = await ghApi([
+        `repos/${input.owner}/${input.repoName}/issues/${input.issueNumber}`,
+    ]);
+    if (!result.ok || result.value === undefined) {
+        return undefined;
+    }
+    return normalizeGitHubIssueDetails(result.value);
+}
 async function ghApi(args) {
     const result = await execa("gh", [
         "api",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyxa/nyx-agent",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {