mcoda 0.1.23 → 0.1.26

package/README.md

@@ -27,7 +27,7 @@ mcoda docs pdr generate --workspace-root . --project WEB --rfp-path docs/rfp/web
 ## Common commands
 - Docs: `mcoda docs pdr generate`, `mcoda docs sds generate`
 - Specs: `mcoda openapi-from-docs`
-- Planning: `mcoda create-tasks`, `mcoda refine-tasks`, `mcoda order-tasks`
+- Planning: `mcoda create-tasks`, `mcoda task-sufficiency-audit`, `mcoda refine-tasks`, `mcoda order-tasks`
 - Execution: `mcoda add-tests`, `mcoda work-on-tasks`, `mcoda code-review`, `mcoda qa-tasks`
 - Backlog: `mcoda backlog`, `mcoda task`
 - Jobs/telemetry: `mcoda jobs`, `mcoda tokens`, `mcoda telemetry`
@@ -35,6 +35,8 @@ mcoda docs pdr generate --workspace-root . --project WEB --rfp-path docs/rfp/web
 - Updates: `mcoda update --check`
 
 `mcoda work-on-tasks` auto-runs the same test-harness bootstrap logic as `mcoda add-tests` when selected tasks require tests but no runnable harness exists.
+`mcoda create-tasks` auto-runs a sufficiency pass (same engine as `mcoda task-sufficiency-audit`) to compare SDS coverage against generated backlog items and fill obvious planning gaps.
+If that sufficiency pass errors, create-tasks continues (fail-open) and records audit failure details in job checkpoints/logs.
 
 ## Configuration
 Environment variables are optional overrides for workspace settings:

package/dist/bin/McodaEntrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"McodaEntrypoint.d.ts","sourceRoot":"","sources":["../../src/bin/McodaEntrypoint.ts"],"names":[],"mappings":";AA6BA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;CA0LxE"}
+{"version":3,"file":"McodaEntrypoint.d.ts","sourceRoot":"","sources":["../../src/bin/McodaEntrypoint.ts"],"names":[],"mappings":";AA8BA,qBAAa,eAAe;WACb,GAAG,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;CA8LxE"}

package/dist/bin/McodaEntrypoint.js

@@ -9,6 +9,7 @@ import { JobsCommands } from "../commands/jobs/JobsCommands.js";
 import { OpenapiCommands } from "../commands/openapi/OpenapiCommands.js";
 import { CreateTasksCommand } from "../commands/planning/CreateTasksCommand.js";
 import { RefineTasksCommand } from "../commands/planning/RefineTasksCommand.js";
+import { TaskSufficiencyAuditCommand } from "../commands/planning/TaskSufficiencyAuditCommand.js";
 import { BacklogCommands } from "../commands/backlog/BacklogCommands.js";
 import { TaskShowCommands } from "../commands/backlog/TaskShowCommands.js";
 import { OrderTasksCommand } from "../commands/backlog/OrderTasksCommand.js";
@@ -81,7 +82,7 @@ export class McodaEntrypoint {
             return;
         }
         if (!command) {
-            throw new Error("Usage: mcoda <agent|gateway-agent|test-agent|agent-run|routing|docs|openapi|job|jobs|tokens|telemetry|create-tasks|migrate-tasks|refine-tasks|order-tasks|tasks|add-tests|work-on-tasks|gateway-trio|code-review|qa-tasks|backlog|task|task-detail|estimate|update|set-workspace|project-guidance|pdr|sds> [...args]\n" +
+            throw new Error("Usage: mcoda <agent|gateway-agent|test-agent|agent-run|routing|docs|openapi|job|jobs|tokens|telemetry|create-tasks|migrate-tasks|refine-tasks|task-sufficiency-audit|order-tasks|tasks|add-tests|work-on-tasks|gateway-trio|code-review|qa-tasks|backlog|task|task-detail|estimate|update|set-workspace|project-guidance|pdr|sds> [...args]\n" +
                 "Routing: use `mcoda routing defaults` to view/update workspace/global defaults, `mcoda routing preview|explain` to inspect agent selection/provenance (override → workspace_default → global_default).\n" +
                 "Aliases: `tasks order-by-deps` forwards to `order-tasks` (dependency-aware ordering), `task`/`task-detail` show a single task.\n" +
                 "Job commands (mcoda job --help for details): list|status|watch|logs|inspect|resume|cancel|tokens\n" +
@@ -147,6 +148,10 @@ export class McodaEntrypoint {
             await RefineTasksCommand.run(rest);
             return;
         }
+        if (command === "task-sufficiency-audit") {
+            await TaskSufficiencyAuditCommand.run(rest);
+            return;
+        }
         if (command === "qa-tasks") {
             if (rest.includes("--help") || rest.includes("-h")) {
                 // eslint-disable-next-line no-console

package/dist/commands/backlog/OrderTasksCommand.d.ts

@@ -13,6 +13,18 @@ interface ParsedArgs {
     stageOrder?: string[];
     json: boolean;
 }
+type ProjectKeyCandidate = {
+    key: string;
+    createdAt?: string | null;
+};
+export declare const pickOrderTasksProjectKey: (options: {
+    requestedKey?: string;
+    configuredKey?: string;
+    existing: ProjectKeyCandidate[];
+}) => {
+    projectKey?: string;
+    warnings: string[];
+};
 export declare const parseOrderTasksArgs: (argv: string[]) => ParsedArgs;
 export declare class OrderTasksCommand {
     static run(argv: string[]): Promise<void>;

package/dist/commands/backlog/OrderTasksCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrderTasksCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/OrderTasksCommand.ts"],"names":[],"mappings":"AAGA,UAAU,UAAU;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,qBAAqB,EAAE,aAAa,GAAG,aAAa,GAAG,wBAAwB,CAAC;IAChF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;CACf;AAuDD,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,EAAE,KAAG,UA4IpD,CAAC;AAkDF,qBAAa,iBAAiB;WACf,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA+DhD"}
+{"version":3,"file":"OrderTasksCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/OrderTasksCommand.ts"],"names":[],"mappings":"AAIA,UAAU,UAAU;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,qBAAqB,EAAE,aAAa,GAAG,aAAa,GAAG,wBAAwB,CAAC;IAChF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAmCtE,eAAO,MAAM,wBAAwB,GAAI,SAAS;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC,KAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAkC5C,CAAC;AAwCF,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,EAAE,KAAG,UA4IpD,CAAC;AAkDF,qBAAa,iBAAiB;WACf,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA6EhD"}

package/dist/commands/backlog/OrderTasksCommand.js

@@ -1,8 +1,9 @@
 import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
 import { TaskOrderingService, WorkspaceResolver } from "@mcoda/core";
 const usage = `mcoda order-tasks \\
   [--workspace-root <PATH>] \\
-  --project <PROJECT_KEY> \\
+  [--project <PROJECT_KEY>] \\
   [--epic <EPIC_KEY>] \\
   [--story <STORY_KEY>] \\
   [--status <STATUS_FILTER>] \\
@@ -14,6 +15,50 @@ const usage = `mcoda order-tasks \\
   [--stage-order <foundation,backend,frontend,other>] \\
   [--rate-agents] \\
   [--json]`;
+const listWorkspaceProjects = async (workspaceRoot) => {
+    const repo = await WorkspaceRepository.create(workspaceRoot);
+    try {
+        const rows = await repo
+            .getDb()
+            .all(`SELECT key, created_at FROM projects ORDER BY created_at ASC, key ASC`);
+        return rows
+            .map((row) => ({ key: String(row.key), createdAt: row.created_at ?? null }))
+            .filter((row) => row.key.trim().length > 0);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await repo.close();
+    }
+};
+export const pickOrderTasksProjectKey = (options) => {
+    const warnings = [];
+    const requestedKey = options.requestedKey?.trim() || undefined;
+    const configuredKey = options.configuredKey?.trim() || undefined;
+    const existing = options.existing ?? [];
+    const firstExisting = existing[0]?.key;
+    if (requestedKey) {
+        if (configuredKey && configuredKey !== requestedKey) {
+            warnings.push(`Using explicitly requested project key "${requestedKey}"; overriding configured project key "${configuredKey}".`);
+        }
+        if (firstExisting && requestedKey !== firstExisting) {
+            warnings.push(`Using explicitly requested project key "${requestedKey}"; first workspace project is "${firstExisting}".`);
+        }
+        return { projectKey: requestedKey, warnings };
+    }
+    if (configuredKey) {
+        if (firstExisting && configuredKey !== firstExisting) {
+            warnings.push(`Using configured project key "${configuredKey}" instead of first workspace project "${firstExisting}".`);
+        }
+        return { projectKey: configuredKey, warnings };
+    }
+    if (firstExisting) {
+        warnings.push(`No --project provided; defaulting to first workspace project "${firstExisting}".`);
+        return { projectKey: firstExisting, warnings };
+    }
+    return { projectKey: undefined, warnings };
+};
 const parseBooleanFlag = (value, defaultValue) => {
     if (value === undefined)
         return defaultValue;
@@ -243,9 +288,19 @@ export class OrderTasksCommand {
             cwd: process.cwd(),
             explicitWorkspace: parsed.workspaceRoot,
         });
-        if (!parsed.project) {
+        const existingProjects = parsed.project ? [] : await listWorkspaceProjects(workspace.workspaceRoot);
+        const configuredKey = typeof workspace.config?.projectKey === "string" && workspace.config.projectKey.trim().length > 0
+            ? workspace.config.projectKey
+            : undefined;
+        const projectResolution = pickOrderTasksProjectKey({
+            requestedKey: parsed.project,
+            configuredKey,
+            existing: existingProjects,
+        });
+        const commandWarnings = [...projectResolution.warnings];
+        if (!projectResolution.projectKey) {
             // eslint-disable-next-line no-console
-            console.error("order-tasks requires --project <PROJECT_KEY>");
+            console.error("order-tasks could not resolve a project key. Provide --project <PROJECT_KEY> or create tasks for this workspace first.");
             process.exitCode = 1;
             return;
         }
@@ -263,7 +318,7 @@ export class OrderTasksCommand {
         const service = await TaskOrderingService.create(workspace);
         try {
             const result = await service.orderTasks({
-                projectKey: parsed.project,
+                projectKey: projectResolution.projectKey,
                 epicKey: parsed.epic,
                 storyKey: parsed.story,
                 statusFilter: parsed.status,
@@ -275,18 +330,19 @@ export class OrderTasksCommand {
                 planningContextPolicy: parsed.planningContextPolicy,
                 stageOrder: resolvedStageOrder,
             });
+            const warnings = [...commandWarnings, ...result.warnings];
             if (parsed.json) {
                 const payload = {
                     order: result.ordered,
                 };
-                if (result.warnings.length > 0) {
-                    payload.warnings = result.warnings;
+                if (warnings.length > 0) {
+                    payload.warnings = warnings;
                 }
                 // eslint-disable-next-line no-console
                 console.log(JSON.stringify(payload, null, 2));
                 return;
             }
-            renderOrder(result.ordered, result.warnings);
+            renderOrder(result.ordered, warnings);
         }
         catch (error) {
             // eslint-disable-next-line no-console

package/dist/commands/planning/RefineTasksCommand.d.ts

@@ -23,6 +23,18 @@ interface ParsedRefineArgs {
     planOut?: string;
     jobId?: string;
 }
+type ProjectKeyCandidate = {
+    key: string;
+    createdAt?: string | null;
+};
+export declare const pickRefineTasksProjectKey: (options: {
+    requestedKey?: string;
+    configuredKey?: string;
+    existing: ProjectKeyCandidate[];
+}) => {
+    projectKey?: string;
+    warnings: string[];
+};
 export declare const parseRefineTasksArgs: (argv: string[]) => ParsedRefineArgs;
 export declare class RefineTasksCommand {
     static run(argv: string[]): Promise<void>;

package/dist/commands/planning/RefineTasksCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefineTasksCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/planning/RefineTasksCommand.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,UAAU,gBAAgB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA8BD,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,KAAG,gBAyNrD,CAAC;AAEF,qBAAa,kBAAkB;WAChB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA0JhD"}
+{"version":3,"file":"RefineTasksCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/planning/RefineTasksCommand.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,UAAU,gBAAgB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAsBtE,eAAO,MAAM,yBAAyB,GAAI,SAAS;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC,KAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAkC5C,CAAC;AA4BF,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,KAAG,gBAyNrD,CAAC;AAEF,qBAAa,kBAAkB;WAChB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAkLhD"}

package/dist/commands/planning/RefineTasksCommand.js

@@ -1,6 +1,51 @@
 import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
 import { RefineTasksService, WorkspaceResolver } from "@mcoda/core";
-const usage = `mcoda refine-tasks --project <PROJECT_KEY> [--workspace-root <PATH>] [--epic <EPIC_KEY>] [--story <STORY_KEY>] [--task <TASK_KEY> ...] [--status <STATUS>] [--max-tasks N] [--strategy split|merge|enrich|estimate|auto] [--agent <NAME>] [--agent-stream [true|false]] [--rate-agents] [--from-db [true|false]] [--dry-run] [--apply] [--resume|--skip-refined] [--run-all] [--batch-size N] [--max-batches N] [--plan-in <PATH>] [--plan-out <PATH>] [--json]`;
+const usage = `mcoda refine-tasks [--project <PROJECT_KEY>] [--workspace-root <PATH>] [--epic <EPIC_KEY>] [--story <STORY_KEY>] [--task <TASK_KEY> ...] [--status <STATUS>] [--max-tasks N] [--strategy split|merge|enrich|estimate|auto] [--agent <NAME>] [--agent-stream [true|false]] [--rate-agents] [--from-db [true|false]] [--dry-run] [--apply] [--resume|--skip-refined] [--run-all] [--batch-size N] [--max-batches N] [--plan-in <PATH>] [--plan-out <PATH>] [--json]`;
+const listWorkspaceProjects = async (workspaceRoot) => {
+    const repo = await WorkspaceRepository.create(workspaceRoot);
+    try {
+        const rows = await repo
+            .getDb()
+            .all(`SELECT key, created_at FROM projects ORDER BY created_at ASC, key ASC`);
+        return rows
+            .map((row) => ({ key: String(row.key), createdAt: row.created_at ?? null }))
+            .filter((row) => row.key.trim().length > 0);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await repo.close();
+    }
+};
+export const pickRefineTasksProjectKey = (options) => {
+    const warnings = [];
+    const requestedKey = options.requestedKey?.trim() || undefined;
+    const configuredKey = options.configuredKey?.trim() || undefined;
+    const existing = options.existing ?? [];
+    const firstExisting = existing[0]?.key;
+    if (requestedKey) {
+        if (configuredKey && configuredKey !== requestedKey) {
+            warnings.push(`Using explicitly requested project key "${requestedKey}"; overriding configured project key "${configuredKey}".`);
+        }
+        if (firstExisting && requestedKey !== firstExisting) {
+            warnings.push(`Using explicitly requested project key "${requestedKey}"; first workspace project is "${firstExisting}".`);
+        }
+        return { projectKey: requestedKey, warnings };
+    }
+    if (configuredKey) {
+        if (firstExisting && configuredKey !== firstExisting) {
+            warnings.push(`Using configured project key "${configuredKey}" instead of first workspace project "${firstExisting}".`);
+        }
+        return { projectKey: configuredKey, warnings };
+    }
+    if (firstExisting) {
+        warnings.push(`No --project provided; defaulting to first workspace project "${firstExisting}".`);
+        return { projectKey: firstExisting, warnings };
+    }
+    return { projectKey: undefined, warnings };
+};
 const parseBooleanFlag = (value, defaultValue) => {
     if (value === undefined)
         return defaultValue;
@@ -251,12 +296,6 @@ export const parseRefineTasksArgs = (argv) => {
 export class RefineTasksCommand {
     static async run(argv) {
         const parsed = parseRefineTasksArgs(argv);
-        if (!parsed.projectKey) {
-            // eslint-disable-next-line no-console
-            console.error("refine-tasks requires --project <PROJECT_KEY>");
-            process.exitCode = 1;
-            return;
-        }
         if (parsed.apply && parsed.dryRun) {
             // eslint-disable-next-line no-console
             console.error("refine-tasks: --apply cannot be used with --dry-run");
@@ -273,11 +312,31 @@ export class RefineTasksCommand {
             cwd: process.cwd(),
             explicitWorkspace: parsed.workspaceRoot,
         });
+        const existingProjects = parsed.projectKey ? [] : await listWorkspaceProjects(workspace.workspaceRoot);
+        const configuredKey = typeof workspace.config?.projectKey === "string" && workspace.config.projectKey.trim().length > 0
+            ? workspace.config.projectKey
+            : undefined;
+        const projectResolution = pickRefineTasksProjectKey({
+            requestedKey: parsed.projectKey,
+            configuredKey,
+            existing: existingProjects,
+        });
+        const commandWarnings = [...projectResolution.warnings];
+        if (!projectResolution.projectKey) {
+            // eslint-disable-next-line no-console
+            console.error("refine-tasks could not resolve a project key. Provide --project <PROJECT_KEY> or create tasks for this workspace first.");
+            process.exitCode = 1;
+            return;
+        }
+        if (commandWarnings.length > 0 && !parsed.json) {
+            // eslint-disable-next-line no-console
+            console.warn(commandWarnings.map((warning) => `! ${warning}`).join("\n"));
+        }
         const service = await RefineTasksService.create(workspace);
         try {
             const baseRequest = {
                 workspace,
-                projectKey: parsed.projectKey,
+                projectKey: projectResolution.projectKey,
                 epicKey: parsed.epicKey,
                 storyKey: parsed.storyKey,
                 taskKeys: parsed.taskKeys.length ? parsed.taskKeys : undefined,
@@ -329,7 +388,7 @@ export class RefineTasksCommand {
                 }
                 if (parsed.json) {
                     // eslint-disable-next-line no-console
-                    console.log(JSON.stringify({ status: "completed", totalProcessed, totalAffected, batches }, null, 2));
+                    console.log(JSON.stringify({ status: "completed", totalProcessed, totalAffected, batches, warnings: commandWarnings }, null, 2));
                 }
                 else {
                     // eslint-disable-next-line no-console
@@ -342,12 +401,13 @@ export class RefineTasksCommand {
                 maxTasks: parsed.maxTasks,
             });
             if (parsed.json) {
+                const warnings = [...commandWarnings, ...(result.plan.warnings ?? [])];
                 // eslint-disable-next-line no-console
                 console.log(JSON.stringify({
                     status: result.applied ? "applied" : "dry_run",
                     summary: result.summary,
                     plan: result.plan,
-                    warnings: result.plan.warnings ?? [],
+                    warnings,
                 }, null, 2));
             }
             else {

package/dist/commands/planning/TaskSufficiencyAuditCommand.d.ts

@@ -0,0 +1,28 @@
+interface ParsedTaskSufficiencyArgs {
+    workspaceRoot?: string;
+    projectKey?: string;
+    maxIterations?: number;
+    maxTasksPerIteration?: number;
+    minCoverageRatio?: number;
+    dryRun: boolean;
+    json: boolean;
+    quiet: boolean;
+}
+type ProjectKeyCandidate = {
+    key: string;
+    createdAt?: string | null;
+};
+export declare const pickTaskSufficiencyProjectKey: (options: {
+    requestedKey?: string;
+    configuredKey?: string;
+    existing: ProjectKeyCandidate[];
+}) => {
+    projectKey?: string;
+    warnings: string[];
+};
+export declare const parseTaskSufficiencyAuditArgs: (argv: string[]) => ParsedTaskSufficiencyArgs;
+export declare class TaskSufficiencyAuditCommand {
+    static run(argv: string[]): Promise<void>;
+}
+export {};
+//# sourceMappingURL=TaskSufficiencyAuditCommand.d.ts.map

package/dist/commands/planning/TaskSufficiencyAuditCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskSufficiencyAuditCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/planning/TaskSufficiencyAuditCommand.ts"],"names":[],"mappings":"AAIA,UAAU,yBAAyB;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAsBtE,eAAO,MAAM,6BAA6B,GAAI,SAAS;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC,KAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAkC5C,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAI,MAAM,MAAM,EAAE,KAAG,yBAmE9D,CAAC;AAEF,qBAAa,2BAA2B;WACzB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA0GhD"}

package/dist/commands/planning/TaskSufficiencyAuditCommand.js

@@ -0,0 +1,209 @@
+import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
+import { TaskSufficiencyService, WorkspaceResolver } from "@mcoda/core";
+const usage = `mcoda task-sufficiency-audit [--workspace-root <path>] [--project <PROJECT_KEY>] [--max-iterations N] [--max-tasks-per-iteration N] [--min-coverage-ratio 0..1] [--dry-run] [--json] [--quiet]`;
+const listWorkspaceProjects = async (workspaceRoot) => {
+    const repo = await WorkspaceRepository.create(workspaceRoot);
+    try {
+        const rows = await repo
+            .getDb()
+            .all(`SELECT key, created_at FROM projects ORDER BY created_at ASC, key ASC`);
+        return rows
+            .map((row) => ({ key: String(row.key), createdAt: row.created_at ?? null }))
+            .filter((row) => row.key.trim().length > 0);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        await repo.close();
+    }
+};
+export const pickTaskSufficiencyProjectKey = (options) => {
+    const warnings = [];
+    const requestedKey = options.requestedKey?.trim() || undefined;
+    const configuredKey = options.configuredKey?.trim() || undefined;
+    const existing = options.existing ?? [];
+    const firstExisting = existing[0]?.key;
+    if (requestedKey) {
+        if (configuredKey && configuredKey !== requestedKey) {
+            warnings.push(`Using explicitly requested project key "${requestedKey}"; overriding configured project key "${configuredKey}".`);
+        }
+        if (firstExisting && requestedKey !== firstExisting) {
+            warnings.push(`Using explicitly requested project key "${requestedKey}"; first workspace project is "${firstExisting}".`);
+        }
+        return { projectKey: requestedKey, warnings };
+    }
+    if (configuredKey) {
+        if (firstExisting && configuredKey !== firstExisting) {
+            warnings.push(`Using configured project key "${configuredKey}" instead of first workspace project "${firstExisting}".`);
+        }
+        return { projectKey: configuredKey, warnings };
+    }
+    if (firstExisting) {
+        warnings.push(`No --project provided; defaulting to first workspace project "${firstExisting}".`);
+        return { projectKey: firstExisting, warnings };
+    }
+    return { projectKey: undefined, warnings };
+};
+export const parseTaskSufficiencyAuditArgs = (argv) => {
+    let workspaceRoot;
+    let projectKey;
+    let maxIterations;
+    let maxTasksPerIteration;
+    let minCoverageRatio;
+    let dryRun = false;
+    let json = false;
+    let quiet = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--workspace-root":
+            case "--workspace":
+                workspaceRoot = argv[i + 1] ? path.resolve(argv[i + 1]) : undefined;
+                i += 1;
+                break;
+            case "--project":
+            case "--project-key":
+                projectKey = argv[i + 1];
+                i += 1;
+                break;
+            case "--max-iterations":
+                maxIterations = Number(argv[i + 1]);
+                i += 1;
+                break;
+            case "--max-tasks-per-iteration":
+            case "--max-new-tasks":
+                maxTasksPerIteration = Number(argv[i + 1]);
+                i += 1;
+                break;
+            case "--min-coverage-ratio":
+            case "--min-coverage":
+                minCoverageRatio = Number(argv[i + 1]);
+                i += 1;
+                break;
+            case "--dry-run":
+                dryRun = true;
+                break;
+            case "--json":
+                json = true;
+                break;
+            case "--quiet":
+                quiet = true;
+                break;
+            case "--help":
+            case "-h":
+                // eslint-disable-next-line no-console
+                console.log(usage);
+                process.exit(0);
+                break;
+            default:
+                break;
+        }
+    }
+    return {
+        workspaceRoot,
+        projectKey,
+        maxIterations: Number.isFinite(maxIterations) ? maxIterations : undefined,
+        maxTasksPerIteration: Number.isFinite(maxTasksPerIteration) ? maxTasksPerIteration : undefined,
+        minCoverageRatio: Number.isFinite(minCoverageRatio) ? minCoverageRatio : undefined,
+        dryRun,
+        json,
+        quiet,
+    };
+};
+export class TaskSufficiencyAuditCommand {
+    static async run(argv) {
+        const parsed = parseTaskSufficiencyAuditArgs(argv);
+        const workspace = await WorkspaceResolver.resolveWorkspace({
+            cwd: process.cwd(),
+            explicitWorkspace: parsed.workspaceRoot,
+        });
+        const existingProjects = parsed.projectKey ? [] : await listWorkspaceProjects(workspace.workspaceRoot);
+        const configuredKey = typeof workspace.config?.projectKey === "string" && workspace.config.projectKey.trim().length > 0
+            ? workspace.config.projectKey
+            : undefined;
+        const projectResolution = pickTaskSufficiencyProjectKey({
+            requestedKey: parsed.projectKey,
+            configuredKey,
+            existing: existingProjects,
+        });
+        if (!projectResolution.projectKey) {
+            // eslint-disable-next-line no-console
+            console.error("task-sufficiency-audit could not resolve a project key. Provide --project <PROJECT_KEY> or run create-tasks first.");
+            process.exitCode = 1;
+            return;
+        }
+        if (projectResolution.warnings.length > 0 && !parsed.json && !parsed.quiet) {
+            // eslint-disable-next-line no-console
+            console.warn(projectResolution.warnings.map((warning) => `! ${warning}`).join("\n"));
+        }
+        const service = await TaskSufficiencyService.create(workspace);
+        try {
+            const result = await service.runAudit({
+                workspace,
+                projectKey: projectResolution.projectKey,
+                dryRun: parsed.dryRun,
+                maxIterations: parsed.maxIterations,
+                maxTasksPerIteration: parsed.maxTasksPerIteration,
+                minCoverageRatio: parsed.minCoverageRatio,
+            });
+            const warnings = [...projectResolution.warnings, ...result.warnings];
+            if (parsed.json) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify({
+                    projectKey: result.projectKey,
+                    jobId: result.jobId,
+                    commandRunId: result.commandRunId,
+                    sourceCommand: result.sourceCommand ?? null,
+                    satisfied: result.satisfied,
+                    dryRun: result.dryRun,
+                    maxIterations: result.maxIterations,
+                    minCoverageRatio: result.minCoverageRatio,
+                    totalTasksAdded: result.totalTasksAdded,
+                    totalTasksUpdated: result.totalTasksUpdated,
+                    finalCoverageRatio: result.finalCoverageRatio,
+                    remainingSectionHeadings: result.remainingSectionHeadings,
+                    remainingFolderEntries: result.remainingFolderEntries,
+                    remainingGaps: result.remainingGaps,
+                    iterations: result.iterations,
+                    reportPath: result.reportPath,
+                    reportHistoryPath: result.reportHistoryPath ?? null,
+                    warnings,
+                }, null, 2));
+                return;
+            }
+            if (!parsed.quiet) {
+                const lines = [
+                    `task-sufficiency-audit project=${result.projectKey}`,
+                    `Job: ${result.jobId}, Command Run: ${result.commandRunId}`,
+                    `Satisfied: ${result.satisfied ? "yes" : "no"}`,
+                    `Dry run: ${result.dryRun ? "yes" : "no"}`,
+                    `Coverage: ${result.finalCoverageRatio} (target ${result.minCoverageRatio})`,
+                    `Tasks added: ${result.totalTasksAdded}`,
+                    `Tasks updated: ${result.totalTasksUpdated}`,
+                    `Remaining section gaps: ${result.remainingSectionHeadings.length}`,
+                    `Remaining folder gaps: ${result.remainingFolderEntries.length}`,
+                    `Remaining total gaps: ${result.remainingGaps.total}`,
+                    `Report: ${result.reportPath}`,
+                    result.reportHistoryPath ? `History snapshot: ${result.reportHistoryPath}` : undefined,
+                ].filter(Boolean);
+                // eslint-disable-next-line no-console
+                console.log(lines.join("\n"));
+            }
+            if (warnings.length > 0) {
+                // eslint-disable-next-line no-console
+                console.warn(warnings.map((warning) => `! ${warning}`).join("\n"));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.error(`task-sufficiency-audit failed: ${message}`);
+            process.exitCode = 1;
+        }
+        finally {
+            await service.close();
+        }
+    }
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from "./commands/backlog/OrderTasksCommand.js";
 export * from "./commands/estimate/EstimateCommands.js";
 export * from "./commands/telemetry/TelemetryCommands.js";
 export * from "./commands/planning/RefineTasksCommand.js";
+export * from "./commands/planning/TaskSufficiencyAuditCommand.js";
 export * from "./commands/work/WorkOnTasksCommand.js";
 export * from "./commands/work/GatewayTrioCommand.js";
 export * from "./commands/review/CodeReviewCommand.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,gDAAgD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,oDAAoD,CAAC;AACnE,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,gDAAgD,CAAC"}

package/dist/index.js

@@ -10,6 +10,7 @@ export * from "./commands/backlog/OrderTasksCommand.js";
 export * from "./commands/estimate/EstimateCommands.js";
 export * from "./commands/telemetry/TelemetryCommands.js";
 export * from "./commands/planning/RefineTasksCommand.js";
+export * from "./commands/planning/TaskSufficiencyAuditCommand.js";
 export * from "./commands/work/WorkOnTasksCommand.js";
 export * from "./commands/work/GatewayTrioCommand.js";
 export * from "./commands/review/CodeReviewCommand.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcoda",
-  "version": "0.1.23",
+  "version": "0.1.26",
   "description": "Local-first CLI for planning, documentation, and execution workflows with agent assistance.",
   "type": "module",
   "main": "dist/index.js",
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "yaml": "^2.4.2",
-    "@mcoda/core": "0.1.23",
-    "@mcoda/shared": "0.1.23"
+    "@mcoda/core": "0.1.26",
+    "@mcoda/shared": "0.1.26"
   },
   "devDependencies": {
-    "@mcoda/db": "0.1.23",
-    "@mcoda/integrations": "0.1.23"
+    "@mcoda/db": "0.1.26",
+    "@mcoda/integrations": "0.1.26"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",