@nyxa/nyx-agent 0.2.0 → 0.3.0

package/dist/cli.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { createRequire } from "node:module";
 import pc from "picocolors";
 import { initCommand } from "./commands/init.js";
 import { runCommand } from "./commands/run.js";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
 const program = new Command();
 program
     .name("nyxagent")
     .description("Run coding-agent workflows with fresh context per phase.")
-    .version("0.1.0");
+    .version(packageJson.version);
 program
     .command("init")
     .description("Create a .nyxagent project configuration")
@@ -16,8 +19,9 @@ program
     .option("--model <name>", "model name")
     .option("--reasoning-level <level>", "harness-neutral reasoning level")
     .option("--max-iterations <count>", "maximum work items per run")
-    .option("--work-items-source <source>", "work item source template: local-markdown, github, or custom")
+    .option("--work-items-source <source>", "work item source template: local or github")
     .option("--work-items-path <path>", "local markdown work item directory")
+    .option("--work-items-repository <owner/repo>", "GitHub work item repository")
     .action(async (options) => {
     await initCommand(options);
 });

package/dist/commands/init.js

@@ -24,8 +24,8 @@ export async function initCommand(options, projectRoot = process.cwd()) {
     if (resolved) {
         await writeText(configPath, buildConfigToml(resolved));
     }
-    if (resolved?.workItemsSource === "local-markdown" && resolved.workItemsPath) {
-        await maybeCreateSampleTask(root, resolved.workItemsPath, Boolean(options.missing));
+    if (resolved?.workItemsSource === "local" && resolved.workItemsPath) {
+        await ensureWorkItemsDirectory(root, resolved.workItemsPath);
     }
     console.log(pc.green("NyxAgent initialized."));
     console.log(`Config: ${relativeToProject(root, configPath)}`);
@@ -59,23 +59,36 @@ async function resolveInitOptions(options, root) {
             default: 5,
             required: true
         }));
-    const workItemsSource = options.workItemsSource ??
-        (await select({
+    const workItemsSource = options.workItemsSource
+        ? normalizeWorkItemsSource(options.workItemsSource)
+        : await select({
             message: "Work item source template",
             choices: [
-                { name: "local-markdown", value: "local-markdown" },
-                { name: "github", value: "github" },
-                { name: "custom", value: "custom" }
+                { name: "local", value: "local" },
+                { name: "github", value: "github" }
             ]
-        }));
+        });
     let workItemsPath = options.workItemsPath;
-    if (workItemsSource === "local-markdown" && !workItemsPath) {
+    if (workItemsSource === "local" && !workItemsPath) {
         const issuesPath = path.join(root, "issues");
         workItemsPath = await input({
-            message: "Local task path",
+            message: "Local work item path",
             default: (await pathExists(issuesPath)) ? "issues" : ".nyxagent/tasks"
         });
     }
+    if (workItemsSource !== "local" && workItemsPath) {
+        throw new Error("--work-items-path can only be used with local work items");
+    }
+    let workItemsRepository = options.workItemsRepository;
+    if (workItemsSource === "github" && !workItemsRepository) {
+        workItemsRepository = await input({
+            message: "GitHub repository",
+            default: ""
+        });
+    }
+    if (workItemsSource === "github") {
+        validateGitHubRepository(workItemsRepository);
+    }
     if (!Number.isInteger(maxIterations) || maxIterations <= 0) {
         throw new Error("max iterations must be a positive integer");
     }
@@ -85,9 +98,24 @@ async function resolveInitOptions(options, root) {
         reasoningLevel,
         maxIterations,
         workItemsSource,
-        workItemsPath
+        workItemsPath,
+        workItemsRepository
     };
 }
+function normalizeWorkItemsSource(source) {
+    if (source === "local" || source === "local-markdown") {
+        return "local";
+    }
+    if (source === "github") {
+        return source;
+    }
+    throw new Error('work item source must be "local" or "github"');
+}
+function validateGitHubRepository(repository) {
+    if (!repository || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+        throw new Error('GitHub repository must use "owner/repo"');
+    }
+}
 function getTemplatesDir() {
     const currentFile = fileURLToPath(import.meta.url);
     return path.resolve(path.dirname(currentFile), "../../templates/default");
@@ -108,31 +136,15 @@ async function copyTemplateTree(sourceDir, destinationDir, missingOnly) {
         await writeText(destination, await readText(source));
     }
 }
-async function maybeCreateSampleTask(root, taskPath, missingOnly) {
+async function ensureWorkItemsDirectory(root, taskPath) {
     const absoluteTaskPath = path.resolve(root, taskPath);
-    await ensureDir(absoluteTaskPath);
-    const sampleTaskPath = path.join(absoluteTaskPath, "TASK-0001.md");
-    if (missingOnly && (await pathExists(sampleTaskPath))) {
-        return;
+    if (!(await pathExists(absoluteTaskPath))) {
+        await ensureDir(absoluteTaskPath);
     }
     const taskPathStat = await stat(absoluteTaskPath);
     if (!taskPathStat.isDirectory()) {
         throw new Error(`Work item path is not a directory: ${taskPath}`);
     }
-    if (!(await pathExists(sampleTaskPath))) {
-        await writeText(sampleTaskPath, [
-            "---",
-            "nyx_id: TASK-0001",
-            "status: open",
-            "title: Replace this sample task",
-            "---",
-            "",
-            "# Replace this sample task",
-            "",
-            "Describe the task here.",
-            ""
-        ].join("\n"));
-    }
 }
 function buildConfigToml(options) {
     const harness = buildHarnessToml(options.harness);
@@ -245,18 +257,18 @@ function buildCodexArgs(readOnly) {
     return args;
 }
 function buildWorkItemsToml(options) {
-    if (options.workItemsSource === "local-markdown") {
+    if (options.workItemsSource === "local") {
         return `[work_items]
-source = "local-markdown"
-path = "${escapeTomlString(options.workItemsPath ?? ".nyxagent/tasks")}"`;
-    }
-    if (options.workItemsSource === "github") {
-        return `[work_items]
-source = "github"
-repository = ""`;
+source = "local"
+path = "${escapeTomlString(options.workItemsPath ?? ".nyxagent/tasks")}"
+max_candidates = 50
+excerpt_chars = 800`;
     }
     return `[work_items]
-source = "custom"`;
+source = "github"
+repository = "${escapeTomlString(options.workItemsRepository ?? "")}"
+max_candidates = 50
+excerpt_chars = 800`;
 }
 function formatTomlArray(values) {
     return `[${values.map((value) => `"${escapeTomlString(value)}"`).join(", ")}]`;

package/dist/config/schema.js

@@ -28,6 +28,42 @@ const phaseSchema = z
     harness: harnessOverrideSchema.optional()
 })
     .passthrough();
+const workItemsSourceSchema = z.preprocess((value) => (value === "local-markdown" ? "local" : value), z.enum(["local", "github"]));
+const githubRepositoryPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const workItemsSchema = z
+    .object({
+    source: workItemsSourceSchema,
+    path: z.string().min(1).optional(),
+    repository: z.string().min(1).optional(),
+    max_candidates: z.number().int().positive().default(50),
+    excerpt_chars: z.number().int().nonnegative().default(800)
+})
+    .passthrough()
+    .superRefine((workItems, ctx) => {
+    if (workItems.source === "local" && !workItems.path) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["path"],
+            message: 'Local work items require "path"'
+        });
+    }
+    if (workItems.source === "github") {
+        if (!workItems.repository) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["repository"],
+                message: 'GitHub work items require "repository"'
+            });
+        }
+        else if (!githubRepositoryPattern.test(workItems.repository)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["repository"],
+                message: 'GitHub repository must use "owner/repo"'
+            });
+        }
+    }
+});
 export const nyxConfigSchema = z
     .object({
     workflow: z.object({
@@ -45,7 +81,7 @@ export const nyxConfigSchema = z
         max_attempts: 1,
         prompt: "prompts/repair-result.md"
     }),
-    work_items: z.record(z.string(), z.unknown()).optional(),
+    work_items: workItemsSchema.optional(),
     phases: z.array(phaseSchema).min(1)
 })
     .superRefine((config, ctx) => {

package/dist/runtime/buildPrompt.js

@@ -34,6 +34,26 @@ async function buildRuntimeContract(input) {
         "Work item configuration:",
         "```json",
         JSON.stringify(input.config.work_items ?? {}, null, 2),
+        "```",
+        "",
+        "Available work items:",
+        "```json",
+        JSON.stringify(input.context.available_work_items ?? [], null, 2),
+        "```",
+        "",
+        "Seen work item keys:",
+        "```json",
+        JSON.stringify(input.context.seen_work_item_keys ?? [], null, 2),
+        "```",
+        "",
+        "Completed work item keys:",
+        "```json",
+        JSON.stringify(input.context.completed_work_item_keys ?? [], null, 2),
+        "```",
+        "",
+        "Last completed work item:",
+        "```json",
+        JSON.stringify(input.context.last_completed_work_item ?? null, null, 2),
         "```"
     ];
     if (input.phase.transitions) {

package/dist/runtime/ledger.js

@@ -0,0 +1,118 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { writeJson } from "./files.js";
+export async function readWorkItemLedger(nyxDir) {
+    const statePath = getLedgerPath(nyxDir);
+    let raw;
+    try {
+        raw = await readFile(statePath, "utf8");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return createEmptyLedger();
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse .nyxagent/state.json: ${message}`);
+    }
+    return normalizeLedger(parsed);
+}
+export async function writeWorkItemLedger(nyxDir, ledger) {
+    await writeJson(getLedgerPath(nyxDir), ledger);
+}
+export function markWorkItemCompleted(input) {
+    const record = normalizeCompletedRecord(input.workItem, input.completedAt ?? new Date().toISOString());
+    if (!record) {
+        return input.ledger;
+    }
+    const completedWorkItemKeys = uniqueStrings([
+        ...input.ledger.completed_work_item_keys,
+        record.key
+    ]);
+    const previousHistory = input.ledger.completed_work_items.filter((item) => item.key !== record.key);
+    return {
+        completed_work_item_keys: completedWorkItemKeys,
+        last_completed_work_item: record,
+        completed_work_items: [...previousHistory, record]
+    };
+}
+function getLedgerPath(nyxDir) {
+    return path.join(nyxDir, "state.json");
+}
+function createEmptyLedger() {
+    return {
+        completed_work_item_keys: [],
+        last_completed_work_item: null,
+        completed_work_items: []
+    };
+}
+function normalizeLedger(value) {
+    if (!isRecord(value)) {
+        return createEmptyLedger();
+    }
+    const completedWorkItems = Array.isArray(value.completed_work_items)
+        ? value.completed_work_items
+            .map((item) => normalizeCompletedRecord(item))
+            .filter((item) => Boolean(item))
+        : [];
+    const completedKeys = uniqueStrings([
+        ...readStringArray(value.completed_work_item_keys),
+        ...completedWorkItems.map((item) => item.key)
+    ]);
+    const lastCompleted = normalizeCompletedRecord(value.last_completed_work_item) ??
+        completedWorkItems.at(-1);
+    return {
+        completed_work_item_keys: completedKeys,
+        last_completed_work_item: lastCompleted ?? null,
+        completed_work_items: completedWorkItems
+    };
+}
+function normalizeCompletedRecord(value, completedAt) {
+    if (!isRecord(value) || typeof value.key !== "string" || value.key.length === 0) {
+        return undefined;
+    }
+    const record = {
+        key: value.key,
+        completed_at: completedAt ??
+            (typeof value.completed_at === "string"
+                ? value.completed_at
+                : new Date().toISOString())
+    };
+    if (typeof value.title === "string" && value.title.length > 0) {
+        record.title = value.title;
+    }
+    if (typeof value.url === "string" && value.url.length > 0) {
+        record.url = value.url;
+    }
+    if (isRecord(value.source)) {
+        record.source = {};
+        if (typeof value.source.type === "string") {
+            record.source.type = value.source.type;
+        }
+        if (typeof value.source.locator === "string") {
+            record.source.locator = value.source.locator;
+        }
+    }
+    return record;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/runtime/runPhase.js

@@ -8,6 +8,7 @@ import { parseNyxAgentResult, getOutcome } from "./parseResult.js";
 import { resolveNyxPath } from "./paths.js";
 import { renderTemplate } from "./renderTemplate.js";
 import { validateAgainstSchema } from "./validateResult.js";
+import { validateWorkItemIdentity } from "./validateWorkItem.js";
 export async function runPhase(input) {
     const phaseDir = path.join(input.iterationDir, "phases", input.phase.id);
     await ensureDir(phaseDir);
@@ -81,8 +82,11 @@ function buildContext(input) {
         phase: input.phase,
         workflow: input.config.workflow,
         work_items: input.config.work_items ?? {},
+        available_work_items: input.state.available_work_items ?? [],
         work_item: input.state.work_item ?? {},
         seen_work_item_keys: input.state.seen_work_item_keys ?? [],
+        completed_work_item_keys: input.state.completed_work_item_keys ?? [],
+        last_completed_work_item: input.state.last_completed_work_item ?? null,
         phase_results: input.state.phase_results ?? {},
         state: input.state,
         model,
@@ -171,6 +175,21 @@ async function parseAndValidatePhaseResult(input) {
             error: `Phase "${input.input.phase.id}" has transitions but result has no string outcome`
         };
     }
+    const workItem = readObjectProperty(parsed.value, "work_item");
+    if (workItem !== undefined) {
+        const currentWorkItemKey = readObjectProperty(readObjectProperty(input.input.state, "work_item"), "key");
+        const workItemValidation = validateWorkItemIdentity({
+            config: input.input.config,
+            workItem,
+            availableWorkItems: readWorkItemCandidates(input.input.state.available_work_items),
+            seenWorkItemKeys: readStringArray(input.input.state.seen_work_item_keys),
+            completedWorkItemKeys: readStringArray(input.input.state.completed_work_item_keys),
+            allowKnownKey: typeof currentWorkItemKey === "string" ? currentWorkItemKey : undefined
+        });
+        if (!workItemValidation.ok) {
+            return workItemValidation;
+        }
+    }
     await writeJson(path.join(input.phaseDir, "result.json"), parsed.value);
     return {
         ok: true,
@@ -242,3 +261,34 @@ async function repairStructuredResult(input) {
         error: lastError
     };
 }
+function readObjectProperty(value, key) {
+    if (value &&
+        typeof value === "object" &&
+        Object.prototype.hasOwnProperty.call(value, key)) {
+        return value[key];
+    }
+    return undefined;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function readWorkItemCandidates(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter(isWorkItemCandidate);
+}
+function isWorkItemCandidate(value) {
+    const key = readObjectProperty(value, "key");
+    const title = readObjectProperty(value, "title");
+    const source = readObjectProperty(value, "source");
+    const type = readObjectProperty(source, "type");
+    const locator = readObjectProperty(source, "locator");
+    return (typeof key === "string" &&
+        typeof title === "string" &&
+        (type === "local" || type === "github") &&
+        typeof locator === "string");
+}

package/dist/runtime/runWorkflow.js

@@ -3,9 +3,11 @@ import pc from "picocolors";
 import { loadConfig } from "../config/loadConfig.js";
 import { ensureDir, writeJson } from "./files.js";
 import { getGitSnapshot } from "./git.js";
+import { markWorkItemCompleted, readWorkItemLedger, writeWorkItemLedger } from "./ledger.js";
 import { getNyxDir, relativeToProject } from "./paths.js";
 import { runPhase } from "./runPhase.js";
 import { createRunId } from "./time.js";
+import { filterAvailableWorkItems, listWorkItemCandidates } from "./workItems.js";
 export async function runWorkflow(options) {
     const projectRoot = path.resolve(options.projectRoot);
     const nyxDir = getNyxDir(projectRoot);
@@ -14,13 +16,17 @@ export async function runWorkflow(options) {
     const runId = createRunId();
     const runDir = path.join(nyxDir, "runs", runId);
     await ensureDir(runDir);
+    let ledger = await readWorkItemLedger(nyxDir);
+    await writeWorkItemLedger(nyxDir, ledger);
     const git = await getGitSnapshot(projectRoot);
     const runState = {
         run_id: runId,
         status: "running",
         current_iteration: 0,
         completed_iterations: 0,
-        seen_work_item_keys: []
+        seen_work_item_keys: [],
+        completed_work_item_keys: [...ledger.completed_work_item_keys],
+        last_completed_work_item: ledger.last_completed_work_item
     };
     await writeJson(path.join(runDir, "run.json"), {
         run_id: runId,
@@ -45,10 +51,19 @@ export async function runWorkflow(options) {
         await writeJson(path.join(runDir, "state.json"), runState);
         const iterationDir = path.join(runDir, "iterations", String(iterationNumber).padStart(3, "0"));
         await ensureDir(iterationDir);
+        const availableWorkItems = await loadAvailableWorkItems({
+            projectRoot,
+            config,
+            runState,
+            ledger
+        });
         const iterationState = {
             iteration: iterationNumber,
             status: "running",
+            available_work_items: availableWorkItems,
             seen_work_item_keys: [...runState.seen_work_item_keys],
+            completed_work_item_keys: [...ledger.completed_work_item_keys],
+            last_completed_work_item: ledger.last_completed_work_item,
             phase_results: {},
             phase_visit_counts: {}
         };
@@ -122,6 +137,16 @@ export async function runWorkflow(options) {
             if (nextTarget === "stop_iteration" || nextTarget === "next_iteration") {
                 iterationState.status = "completed";
                 runState.completed_iterations += 1;
+                ledger = await completeIterationWorkItem({
+                    nyxDir,
+                    ledger,
+                    runState,
+                    iterationState
+                });
+                iterationState.completed_work_item_keys = [
+                    ...ledger.completed_work_item_keys
+                ];
+                iterationState.last_completed_work_item = ledger.last_completed_work_item;
                 await writeJson(iterationStateFile, iterationState);
                 await writeJson(path.join(runDir, "state.json"), runState);
                 break;
@@ -148,6 +173,29 @@ function resolveNextTarget(phase, outcome) {
     }
     return phase.next;
 }
+async function loadAvailableWorkItems(input) {
+    const candidates = await listWorkItemCandidates({
+        projectRoot: input.projectRoot,
+        config: input.config
+    });
+    return filterAvailableWorkItems({
+        candidates,
+        seenWorkItemKeys: input.runState.seen_work_item_keys,
+        completedWorkItemKeys: input.ledger.completed_work_item_keys
+    });
+}
+async function completeIterationWorkItem(input) {
+    const ledger = markWorkItemCompleted({
+        ledger: input.ledger,
+        workItem: input.iterationState.work_item
+    });
+    input.runState.completed_work_item_keys = [
+        ...ledger.completed_work_item_keys
+    ];
+    input.runState.last_completed_work_item = ledger.last_completed_work_item;
+    await writeWorkItemLedger(input.nyxDir, ledger);
+    return ledger;
+}
 function readObjectProperty(value, key) {
     if (value &&
         typeof value === "object" &&

package/dist/runtime/validateWorkItem.js

@@ -0,0 +1,156 @@
+import path from "node:path";
+export function validateWorkItemIdentity(input) {
+    const workItems = input.config.work_items;
+    if (!workItems) {
+        return {
+            ok: false,
+            error: "Selected work item requires configured [work_items]"
+        };
+    }
+    if (!isRecord(input.workItem)) {
+        return { ok: false, error: "Selected work item must be an object" };
+    }
+    const source = input.workItem.source;
+    if (!isRecord(source)) {
+        return { ok: false, error: "Selected work item source must be an object" };
+    }
+    const key = input.workItem.key;
+    const sourceType = source.type;
+    const locator = source.locator;
+    if (typeof key !== "string" || key.length === 0) {
+        return { ok: false, error: "Selected work item key must be a non-empty string" };
+    }
+    if (input.seenWorkItemKeys?.includes(key) && key !== input.allowKnownKey) {
+        return {
+            ok: false,
+            error: `Selected work item key "${key}" was already seen in this run`
+        };
+    }
+    if (input.completedWorkItemKeys?.includes(key) &&
+        key !== input.allowKnownKey) {
+        return {
+            ok: false,
+            error: `Selected work item key "${key}" is already completed`
+        };
+    }
+    if (sourceType !== workItems.source) {
+        return {
+            ok: false,
+            error: `Selected work item source.type must be "${workItems.source}"`
+        };
+    }
+    if (typeof locator !== "string" || locator.length === 0) {
+        return {
+            ok: false,
+            error: "Selected work item source.locator must be a non-empty string"
+        };
+    }
+    if (key !== `${workItems.source}:${locator}`) {
+        return {
+            ok: false,
+            error: `Selected work item key must be "${workItems.source}:${locator}"`
+        };
+    }
+    if (workItems.source === "local") {
+        const localValidation = validateLocalLocator(locator, workItems.path);
+        if (!localValidation.ok) {
+            return localValidation;
+        }
+    }
+    else {
+        const githubValidation = validateGitHubLocator(locator, workItems.repository);
+        if (!githubValidation.ok) {
+            return githubValidation;
+        }
+    }
+    if (input.availableWorkItems) {
+        return validateCandidateMembership({
+            key,
+            sourceType,
+            locator,
+            availableWorkItems: input.availableWorkItems
+        });
+    }
+    return { ok: true };
+}
+function validateCandidateMembership(input) {
+    const candidate = input.availableWorkItems.find((item) => item.key === input.key);
+    if (!candidate) {
+        return {
+            ok: false,
+            error: `Selected work item key "${input.key}" is not in available_work_items`
+        };
+    }
+    if (candidate.source.type !== input.sourceType ||
+        candidate.source.locator !== input.locator) {
+        return {
+            ok: false,
+            error: `Selected work item source does not match available_work_items entry "${input.key}"`
+        };
+    }
+    return { ok: true };
+}
+function validateLocalLocator(locator, configuredPath) {
+    const normalizedLocator = normalizeRelativePath(locator);
+    const normalizedPath = configuredPath
+        ? normalizeRelativePath(configuredPath)
+        : undefined;
+    if (!normalizedLocator || normalizedLocator !== locator) {
+        return {
+            ok: false,
+            error: "Local work item locator must be a canonical relative path"
+        };
+    }
+    if (!normalizedPath) {
+        return {
+            ok: false,
+            error: "Local work item validation requires [work_items].path"
+        };
+    }
+    if (normalizedLocator !== normalizedPath &&
+        !normalizedLocator.startsWith(`${normalizedPath}/`)) {
+        return {
+            ok: false,
+            error: `Local work item locator must stay under "${normalizedPath}"`
+        };
+    }
+    return { ok: true };
+}
+function validateGitHubLocator(locator, repository) {
+    if (!repository) {
+        return {
+            ok: false,
+            error: "GitHub work item validation requires [work_items].repository"
+        };
+    }
+    const match = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)$/.exec(locator);
+    if (!match) {
+        return {
+            ok: false,
+            error: 'GitHub work item locator must use "owner/repo#number"'
+        };
+    }
+    if (match[1] !== repository) {
+        return {
+            ok: false,
+            error: `GitHub work item locator must use repository "${repository}"`
+        };
+    }
+    return { ok: true };
+}
+function normalizeRelativePath(value) {
+    if (value.length === 0 ||
+        value.includes("\\") ||
+        path.posix.isAbsolute(value) ||
+        /^[A-Za-z]:[\\/]/.test(value)) {
+        return undefined;
+    }
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        return undefined;
+    }
+    return normalized;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/runtime/workItems.js

@@ -0,0 +1,212 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { execa } from "execa";
+export async function listWorkItemCandidates(input) {
+    const workItems = input.config.work_items;
+    if (!workItems) {
+        return [];
+    }
+    if (workItems.source === "local") {
+        if (!workItems.path) {
+            throw new Error('Local work items require [work_items].path');
+        }
+        return listLocalWorkItemCandidates({
+            projectRoot: input.projectRoot,
+            workItemsPath: workItems.path,
+            maxCandidates: workItems.max_candidates,
+            excerptChars: workItems.excerpt_chars
+        });
+    }
+    if (!workItems.repository) {
+        throw new Error('GitHub work items require [work_items].repository');
+    }
+    return listGitHubWorkItemCandidates({
+        repository: workItems.repository,
+        maxCandidates: workItems.max_candidates,
+        excerptChars: workItems.excerpt_chars
+    });
+}
+export function filterAvailableWorkItems(input) {
+    const seen = new Set(input.seenWorkItemKeys);
+    const completed = new Set(input.completedWorkItemKeys);
+    return input.candidates.filter((candidate) => !seen.has(candidate.key) && !completed.has(candidate.key));
+}
+export async function listLocalWorkItemCandidates(input) {
+    const normalizedPath = normalizeProjectRelativePath(input.workItemsPath);
+    if (!normalizedPath) {
+        throw new Error("[work_items].path must be a canonical relative path");
+    }
+    const root = path.resolve(input.projectRoot);
+    const workItemsDir = path.resolve(root, normalizedPath);
+    const relative = path.relative(root, workItemsDir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("[work_items].path must stay inside the project root");
+    }
+    const dirStat = await stat(workItemsDir).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Local work item path does not exist: ${normalizedPath} (${message})`);
+    });
+    if (!dirStat.isDirectory()) {
+        throw new Error(`Local work item path is not a directory: ${normalizedPath}`);
+    }
+    const files = (await collectMarkdownFiles(workItemsDir))
+        .map((filePath) => toPosixPath(path.relative(root, filePath)))
+        .sort((left, right) => left.localeCompare(right));
+    const candidates = [];
+    for (const locator of files.slice(0, input.maxCandidates)) {
+        const absolutePath = path.join(root, locator);
+        const content = await readFile(absolutePath, "utf8");
+        candidates.push({
+            key: `local:${locator}`,
+            title: inferMarkdownTitle(content, locator),
+            source: {
+                type: "local",
+                locator
+            },
+            excerpt: buildExcerpt(content, input.excerptChars)
+        });
+    }
+    return candidates;
+}
+export async function listGitHubWorkItemCandidates(input) {
+    const result = await execa("gh", [
+        "issue",
+        "list",
+        "--repo",
+        input.repository,
+        "--state",
+        "open",
+        "--limit",
+        String(input.maxCandidates),
+        "--json",
+        "number,title,url,labels,updatedAt,body"
+    ], { reject: false });
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout || "unknown error").trim();
+        throw new Error(`Failed to list GitHub work items with gh: ${detail}`);
+    }
+    let issues;
+    try {
+        issues = JSON.parse(result.stdout);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse gh issue list JSON: ${message}`);
+    }
+    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) => normalizeGitHubIssue({
+        issue,
+        repository: input.repository,
+        excerptChars: input.excerptChars
+    }));
+}
+function normalizeGitHubIssue(input) {
+    if (!isRecord(input.issue)) {
+        throw new Error("gh issue list returned a non-object issue");
+    }
+    const number = input.issue.number;
+    const title = input.issue.title;
+    if (typeof number !== "number" || !Number.isInteger(number) || number <= 0) {
+        throw new Error("GitHub issue is missing a positive integer number");
+    }
+    if (typeof title !== "string" || title.length === 0) {
+        throw new Error(`GitHub issue #${number} is missing a title`);
+    }
+    const locator = `${input.repository}#${number}`;
+    const candidate = {
+        key: `github:${locator}`,
+        title,
+        source: {
+            type: "github",
+            locator
+        },
+        labels: normalizeLabels(input.issue.labels)
+    };
+    if (typeof input.issue.url === "string" && input.issue.url.length > 0) {
+        candidate.url = input.issue.url;
+    }
+    if (typeof input.issue.updatedAt === "string" &&
+        input.issue.updatedAt.length > 0) {
+        candidate.updated_at = input.issue.updatedAt;
+    }
+    if (typeof input.issue.body === "string") {
+        candidate.excerpt = buildExcerpt(input.issue.body, input.excerptChars);
+    }
+    return candidate;
+}
+async function collectMarkdownFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const filePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectMarkdownFiles(filePath)));
+            continue;
+        }
+        if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            files.push(filePath);
+        }
+    }
+    return files;
+}
+function inferMarkdownTitle(content, locator) {
+    const heading = /^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/m.exec(content);
+    if (heading?.[1]) {
+        return heading[1].trim();
+    }
+    return path.posix.basename(locator, ".md");
+}
+function buildExcerpt(content, maxChars) {
+    if (maxChars <= 0) {
+        return undefined;
+    }
+    const compact = content.replace(/\s+/g, " ").trim();
+    if (!compact) {
+        return undefined;
+    }
+    if (compact.length <= maxChars) {
+        return compact;
+    }
+    if (maxChars <= 3) {
+        return compact.slice(0, maxChars);
+    }
+    return `${compact.slice(0, maxChars - 3).trimEnd()}...`;
+}
+function normalizeLabels(labels) {
+    if (!Array.isArray(labels)) {
+        return undefined;
+    }
+    const normalized = labels
+        .map((label) => {
+        if (typeof label === "string") {
+            return label;
+        }
+        if (isRecord(label) && typeof label.name === "string") {
+            return label.name;
+        }
+        return undefined;
+    })
+        .filter((label) => Boolean(label));
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeProjectRelativePath(value) {
+    if (value.length === 0 ||
+        value.includes("\\") ||
+        path.posix.isAbsolute(value) ||
+        /^[A-Za-z]:[\\/]/.test(value)) {
+        return undefined;
+    }
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        return undefined;
+    }
+    return normalized;
+}
+function toPosixPath(value) {
+    return value.split(path.sep).join(path.posix.sep);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/docs/nyxagent-v0-spec.md

@@ -26,7 +26,7 @@ configuration.
 
 ## Non-Goals For v0
 
-- No built-in GitHub, Jira, Linear, or local task tracker adapter.
+- No native classification of work items as plans, PRDs, or tasks.
 - No native Git commit or issue close logic in the engine.
 - No resume command.
 - No fully general DAG/workflow engine.
@@ -62,6 +62,7 @@ If `.nyxagent/` already exists:
 ```text
 .nyxagent/
   config.toml
+  state.json
   prompts/
     selection.md
     execution.md
@@ -113,8 +114,10 @@ max_attempts = 1
 prompt = "prompts/repair-result.md"
 
 [work_items]
-source = "local-markdown"
+source = "local"
 path = "issues"
+max_candidates = 50
+excerpt_chars = 800
 
 [[phases]]
 id = "selection"
@@ -175,8 +178,23 @@ max_visits_per_iteration = 1
 - `model.reasoning_level` is a harness-neutral string.
 - Harness args are declarative and may interpolate config/runtime variables.
 - Per-phase `model` and `harness` blocks override global values.
-- `work_items` is informative in v0. It is injected into runtime context and
-  used by prompts, not scanned by the engine.
+- `work_items` supports only `local` and `github` in v0.
+- `work_items.max_candidates` defaults to `50` and caps the inventory sent to
+  the selection prompt.
+- `work_items.excerpt_chars` defaults to `800` and bounds candidate excerpts.
+- The engine scans the configured provider, normalizes candidates into
+  `available_work_items`, and injects that inventory into runtime context.
+- The engine validates the selected `work_item` identity against `[work_items]`
+  and requires the selected key to exist in `available_work_items` before
+  recording phase results.
+- Local markdown work items do not have a required frontmatter schema. The
+  provider infers titles from the first heading or filename and includes a
+  bounded content excerpt.
+- Local keys use `local:<relative-path-under-work-items-path>`.
+- GitHub keys use `github:<owner>/<repo>#<issue-number>` and must match the
+  configured repository.
+- NyxAgent does not decide whether an item is a plan, PRD, or task. The
+  selection agent makes that semantic choice from the deterministic inventory.
 
 ## Workflow Model
 
@@ -273,6 +291,10 @@ The runtime contract includes:
 - required structured output contract
 - work item context, when selected
 - work item config from `[work_items]`
+- `available_work_items`
+- `seen_work_item_keys`
+- `completed_work_item_keys`
+- `last_completed_work_item`
 
 The user prompt remains focused on domain behavior.
 
@@ -347,11 +369,23 @@ Each run creates a timestamped directory:
 - current iteration
 - completed iterations
 - seen work item keys
+- completed work item keys
+- last completed work item
+
+`.nyxagent/state.json` records persistent work item completion state:
+
+- completed work item keys
+- last completed work item
+- minimal completion history
 
 `iterations/NNN/state.json` records per-work-item state:
 
 - iteration number
 - work item
+- available work items for the iteration
+- seen work item keys
+- completed work item keys
+- last completed work item
 - phase results
 - phase visit counts
 - current phase status
@@ -392,9 +426,13 @@ Default prompts should be concise but operational.
 
 Selection:
 
-- inspect configured work item source
-- choose one work item
-- avoid keys already present in `seen_work_item_keys`
+- choose one item from `available_work_items`
+- treat candidates agnostically: they may be plans, PRDs, or tasks
+- prefer the most actionable item based on the candidate title and excerpt
+- if a plan references concrete candidate tasks, choose the concrete task when
+  that is the best next work
+- avoid keys already present in `seen_work_item_keys` or
+  `completed_work_item_keys`
 - return `selected` or `no_work`
 
 Execution:
@@ -429,17 +467,18 @@ Closure:
 - model name
 - reasoning level
 - max iterations
-- work item source template: `local-markdown`, `github`, or `custom`
+- work item source template: `local` or `github`
 
-For `local-markdown`, init asks for a task path.
+For `local`, init asks for a work item path.
+For `github`, init asks for a repository in `owner/repo` format.
 
 Default path selection:
 
 - use `issues/` if it exists
 - otherwise suggest `.nyxagent/tasks/`
 
-If the chosen local task path does not exist, init may create it and add a
-sample task.
+If the chosen local work item path does not exist, init creates the directory but
+does not create sample work items.
 
 ## Implementation Stack
 
@@ -479,7 +518,7 @@ src/
 
 - `nyxagent resume`
 - `nyxagent import-tasks`
-- tracker adapters for GitHub, Jira, Linear, or local frontmatter tasks
+- additional tracker adapters
 - explicit Git commit adapter
 - stricter artifact redaction
 - richer phase retry policy

package/package.json

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

package/templates/default/prompts/selection.md

@@ -1,19 +1,29 @@
 Select exactly one work item for this iteration.
 
-Use the work item configuration from the runtime contract. Prefer open,
-well-scoped work that has not already been selected in this run. Avoid any item
-whose key appears in `seen_work_item_keys`.
+Use `available_work_items` from the runtime contract as the complete inventory
+for this selection. Some candidates may be plans, PRDs, or concrete tasks. Pick
+the most actionable next item from the provided context.
 
-If no suitable work item exists, return `no_work`.
+If a candidate is a plan that references more concrete candidates also present
+in `available_work_items`, you may choose the concrete task. If the plan itself
+is the best next work, choose the plan. If no candidate is exploitable, return
+`no_work`.
+
+Do not choose any key listed in `seen_work_item_keys` or
+`completed_work_item_keys`. The selected work item must be copied from
+`available_work_items`; do not invent a key.
+
+The selected work item identity must match the inventory entry:
+
+- local: `source.type` is `local`, `source.locator` is the project-relative
+  markdown path, and `key` is `local:<source.locator>`.
+- github: `source.type` is `github`, `source.locator` is
+  `owner/repo#number` for the configured repository, and `key` is
+  `github:<source.locator>`.
 
 Return one of these outcomes:
 
 - `selected`: include a stable `work_item`
 - `no_work`: include a short `reason`
 
-The selected work item must have a stable key. Examples:
-
-- `github:owner/repo#42`
-- `local:issues/TASK-0007.md`
-
 Do not modify project files or task files during selection.

package/templates/default/schemas/selection.schema.json

@@ -25,7 +25,7 @@
           "properties": {
             "type": {
               "type": "string",
-              "minLength": 1
+              "enum": ["local", "github"]
             },
             "locator": {
               "type": "string",