mcoda 0.1.19 → 0.1.21

package/dist/commands/review/CodeReviewCommand.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
 import { CodeReviewService, WorkspaceResolver } from "@mcoda/core";
 import { REVIEW_ALLOWED_STATUSES, filterTaskStatuses, normalizeReviewStatuses } from "@mcoda/shared";
 const usage = `mcoda code-review \\
@@ -13,6 +14,8 @@ const usage = `mcoda code-review \\
   [--agent <NAME>] \\
   [--agent-stream <true|false>] \\
   [--create-followup-tasks <true|false>] \\
+  [--execution-context-policy <best_effort|require_any|require_sds_or_openapi>] \\
+  [--empty-diff-approval-policy <ready_to_qa|complete>] \\
   [--rate-agents] \\
   [--json]
 
@@ -35,6 +38,24 @@ const parseCsv = (value) => {
         .map((v) => v.trim())
         .filter(Boolean);
 };
+const normalizeExecutionContextPolicy = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "best_effort" || normalized === "require_any" || normalized === "require_sds_or_openapi") {
+        return normalized;
+    }
+    return undefined;
+};
+const normalizeEmptyDiffApprovalPolicy = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "ready_to_qa" || normalized === "complete") {
+        return normalized;
+    }
+    return undefined;
+};
 export const parseCodeReviewArgs = (argv) => {
     let workspaceRoot;
     let projectKey;
@@ -50,6 +71,8 @@ export const parseCodeReviewArgs = (argv) => {
     let agentStream;
     let rateAgents = false;
     let createFollowupTasks = false;
+    let executionContextPolicy;
+    let emptyDiffApprovalPolicy;
     let json = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -79,6 +102,20 @@ export const parseCodeReviewArgs = (argv) => {
             createFollowupTasks = parseBooleanFlag(raw, true);
             continue;
         }
+        if (arg.startsWith("--execution-context-policy=")) {
+            const [, raw] = arg.split("=", 2);
+            const parsedPolicy = normalizeExecutionContextPolicy(raw);
+            if (parsedPolicy)
+                executionContextPolicy = parsedPolicy;
+            continue;
+        }
+        if (arg.startsWith("--empty-diff-approval-policy=")) {
+            const [, raw] = arg.split("=", 2);
+            const parsedPolicy = normalizeEmptyDiffApprovalPolicy(raw);
+            if (parsedPolicy)
+                emptyDiffApprovalPolicy = parsedPolicy;
+            continue;
+        }
         switch (arg) {
             case "--workspace":
             case "--workspace-root":
@@ -160,6 +197,28 @@ export const parseCodeReviewArgs = (argv) => {
                 }
                 break;
             }
+            case "--execution-context-policy": {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("--")) {
+                    const parsedPolicy = normalizeExecutionContextPolicy(next);
+                    if (parsedPolicy) {
+                        executionContextPolicy = parsedPolicy;
+                        i += 1;
+                    }
+                }
+                break;
+            }
+            case "--empty-diff-approval-policy": {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("--")) {
+                    const parsedPolicy = normalizeEmptyDiffApprovalPolicy(next);
+                    if (parsedPolicy) {
+                        emptyDiffApprovalPolicy = parsedPolicy;
+                        i += 1;
+                    }
+                }
+                break;
+            }
             case "--json":
                 json = true;
                 break;
@@ -191,9 +250,55 @@ export const parseCodeReviewArgs = (argv) => {
         agentStream: agentStream ?? false,
         rateAgents,
         createFollowupTasks,
+        executionContextPolicy: executionContextPolicy ?? "require_sds_or_openapi",
+        emptyDiffApprovalPolicy: emptyDiffApprovalPolicy ?? "ready_to_qa",
         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 pickCodeReviewProjectKey = (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 class CodeReviewCommand {
     static async run(argv) {
         const parsed = parseCodeReviewArgs(argv);
@@ -202,11 +307,31 @@ export class CodeReviewCommand {
             explicitWorkspace: parsed.workspaceRoot,
             noRepoWrites: true,
         });
+        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 = pickCodeReviewProjectKey({
+            requestedKey: parsed.projectKey,
+            configuredKey,
+            existing: existingProjects,
+        });
+        const commandWarnings = [...projectResolution.warnings];
+        if (!projectResolution.projectKey) {
+            // eslint-disable-next-line no-console
+            console.error("code-review could not resolve a project key. Provide --project <PROJECT_KEY> or create tasks for this workspace first.");
+            process.exitCode = 1;
+            return;
+        }
+        if (commandWarnings.length && !parsed.json) {
+            // eslint-disable-next-line no-console
+            console.warn(commandWarnings.map((warning) => `! ${warning}`).join("\n"));
+        }
         const service = await CodeReviewService.create(workspace);
         try {
             const result = await service.reviewTasks({
                 workspace,
-                projectKey: parsed.projectKey,
+                projectKey: projectResolution.projectKey,
                 epicKey: parsed.epicKey,
                 storyKey: parsed.storyKey,
                 taskKeys: parsed.taskKeys.length ? parsed.taskKeys : undefined,
@@ -220,8 +345,11 @@ export class CodeReviewCommand {
                 agentStream: parsed.agentStream,
                 rateAgents: parsed.rateAgents,
                 createFollowupTasks: parsed.createFollowupTasks,
+                executionContextPolicy: parsed.executionContextPolicy,
+                emptyDiffApprovalPolicy: parsed.emptyDiffApprovalPolicy,
             });
             if (parsed.json) {
+                const warnings = [...commandWarnings, ...result.warnings];
                 // eslint-disable-next-line no-console
                 console.log(JSON.stringify({
                     job: { id: result.jobId, commandRunId: result.commandRunId },
@@ -236,7 +364,7 @@ export class CodeReviewCommand {
                         followupTasks: t.followupTasks,
                     })),
                     errors: result.tasks.filter((t) => t.error).map((t) => ({ taskId: t.taskId, taskKey: t.taskKey, error: t.error })),
-                    warnings: result.warnings,
+                    warnings,
                 }, null, 2));
                 return;
             }
@@ -260,8 +388,9 @@ export class CodeReviewCommand {
                 `Artifacts: ${path.join(workspace.mcodaDir, "jobs", result.jobId, "review")}`,
                 ...lines,
             ];
-            if (result.warnings.length) {
-                summary.push(`Warnings: ${result.warnings.join("; ")}`);
+            const warnings = [...commandWarnings, ...result.warnings];
+            if (warnings.length) {
+                summary.push(`Warnings: ${warnings.join("; ")}`);
             }
             // eslint-disable-next-line no-console
             console.log(summary.join("\n"));

package/dist/commands/work/WorkOnTasksCommand.d.ts

@@ -17,11 +17,25 @@ interface ParsedArgs {
     workRunner?: string;
     useCodali?: boolean;
     agentAdapterOverride?: string;
-    missingTestsPolicy?: "block_job" | "skip_task" | "fail_task";
+    missingTestsPolicy?: "block_job" | "skip_task" | "fail_task" | "continue_task";
     allowMissingTests?: boolean;
+    missingContextPolicy?: "allow" | "warn" | "block";
+    executionContextPolicy?: "best_effort" | "require_any" | "require_sds_or_openapi";
     json: boolean;
 }
+type ProjectKeyCandidate = {
+    key: string;
+    createdAt?: string | null;
+};
 export declare const parseWorkOnTasksArgs: (argv: string[]) => ParsedArgs;
+export declare const pickWorkOnTasksProjectKey: (options: {
+    requestedKey?: string;
+    configuredKey?: string;
+    existing: ProjectKeyCandidate[];
+}) => {
+    projectKey?: string;
+    warnings: string[];
+};
 export declare class WorkOnTasksCommand {
     static run(argv: string[]): Promise<void>;
 }

package/dist/commands/work/WorkOnTasksCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkOnTasksCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/work/WorkOnTasksCommand.ts"],"names":[],"mappings":"AAIA,UAAU,UAAU;IAClB,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,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf;AA6ED,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,KAAG,UAwQrD,CAAC;AAEF,qBAAa,kBAAkB;WAChB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAmHhD"}
+{"version":3,"file":"WorkOnTasksCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/work/WorkOnTasksCommand.ts"],"names":[],"mappings":"AAKA,UAAU,UAAU;IAClB,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,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAClD,sBAAsB,CAAC,EAAE,aAAa,GAAG,aAAa,GAAG,wBAAwB,CAAC;IAClF,IAAI,EAAE,OAAO,CAAC;CACf;AAED,KAAK,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAgHtE,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,EAAE,KAAG,UA8SrD,CAAC;AAoBF,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;AAEF,qBAAa,kBAAkB;WAChB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAwIhD"}

package/dist/commands/work/WorkOnTasksCommand.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
 import { JobService, WorkOnTasksService, WorkspaceResolver } from "@mcoda/core";
 import { WORK_ALLOWED_STATUSES, filterTaskStatuses } from "@mcoda/shared";
 const usage = `mcoda work-on-tasks \\
@@ -14,8 +15,10 @@ const usage = `mcoda work-on-tasks \\
   [--agent-stream <true|false>] \\
   [--work-runner <codali|default>] \\
   [--use-codali <true|false>] \\
-  [--missing-tests-policy <block_job|skip_task|fail_task>] \\
+  [--missing-tests-policy <continue_task|block_job|skip_task|fail_task>] \\
   [--allow-missing-tests <true|false>] \\
+  [--missing-context-policy <allow|warn|block>] \\
+  [--execution-context-policy <best_effort|require_any|require_sds_or_openapi>] \\
   [--rate-agents] \\
   [--auto-merge <true|false>] \\
   [--auto-push <true|false>] \\
@@ -52,7 +55,34 @@ const normalizeMissingTestsPolicy = (value) => {
     if (!value)
         return undefined;
     const normalized = value.trim().toLowerCase().replace(/-/g, "_");
-    if (normalized === "block_job" || normalized === "skip_task" || normalized === "fail_task") {
+    if (normalized === "block_job" ||
+        normalized === "skip_task" ||
+        normalized === "fail_task" ||
+        normalized === "continue_task" ||
+        normalized === "continue" ||
+        normalized === "allow" ||
+        normalized === "warn_task") {
+        if (normalized === "continue" || normalized === "allow" || normalized === "warn_task") {
+            return "continue_task";
+        }
+        return normalized;
+    }
+    return undefined;
+};
+const normalizeMissingContextPolicy = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "allow" || normalized === "warn" || normalized === "block") {
+        return normalized;
+    }
+    return undefined;
+};
+const normalizeExecutionContextPolicy = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "best_effort" || normalized === "require_any" || normalized === "require_sds_or_openapi") {
         return normalized;
     }
     return undefined;
@@ -93,6 +123,8 @@ export const parseWorkOnTasksArgs = (argv) => {
     let useCodali;
     let missingTestsPolicy;
     let allowMissingTests;
+    let missingContextPolicy;
+    let executionContextPolicy;
     let json = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -149,6 +181,20 @@ export const parseWorkOnTasksArgs = (argv) => {
             allowMissingTests = parseBooleanFlag(raw, true);
             continue;
         }
+        if (arg.startsWith("--missing-context-policy=")) {
+            const [, raw] = arg.split("=", 2);
+            const parsedPolicy = normalizeMissingContextPolicy(raw);
+            if (parsedPolicy)
+                missingContextPolicy = parsedPolicy;
+            continue;
+        }
+        if (arg.startsWith("--execution-context-policy=")) {
+            const [, raw] = arg.split("=", 2);
+            const parsedPolicy = normalizeExecutionContextPolicy(raw);
+            if (parsedPolicy)
+                executionContextPolicy = parsedPolicy;
+            continue;
+        }
         switch (arg) {
             case "--workspace":
             case "--workspace-root":
@@ -248,6 +294,28 @@ export const parseWorkOnTasksArgs = (argv) => {
                 }
                 break;
             }
+            case "--missing-context-policy": {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("--")) {
+                    const parsedPolicy = normalizeMissingContextPolicy(next);
+                    if (parsedPolicy) {
+                        missingContextPolicy = parsedPolicy;
+                    }
+                    i += 1;
+                }
+                break;
+            }
+            case "--execution-context-policy": {
+                const next = argv[i + 1];
+                if (next && !next.startsWith("--")) {
+                    const parsedPolicy = normalizeExecutionContextPolicy(next);
+                    if (parsedPolicy) {
+                        executionContextPolicy = parsedPolicy;
+                    }
+                    i += 1;
+                }
+                break;
+            }
             case "--auto-merge": {
                 const next = argv[i + 1];
                 if (next && !next.startsWith("--")) {
@@ -335,9 +403,55 @@ export const parseWorkOnTasksArgs = (argv) => {
         agentAdapterOverride: runnerOverride.agentAdapterOverride,
         missingTestsPolicy,
         allowMissingTests,
+        missingContextPolicy,
+        executionContextPolicy: executionContextPolicy ?? "require_sds_or_openapi",
         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 pickWorkOnTasksProjectKey = (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 class WorkOnTasksCommand {
     static async run(argv) {
         const parsed = parseWorkOnTasksArgs(argv);
@@ -349,12 +463,26 @@ export class WorkOnTasksCommand {
             cwd: process.cwd(),
             explicitWorkspace: parsed.workspaceRoot,
         });
-        if (!parsed.projectKey) {
+        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 = pickWorkOnTasksProjectKey({
+            requestedKey: parsed.projectKey,
+            configuredKey,
+            existing: existingProjects,
+        });
+        const commandWarnings = [...projectResolution.warnings];
+        if (!projectResolution.projectKey) {
             // eslint-disable-next-line no-console
-            console.error("work-on-tasks requires --project <PROJECT_KEY>");
+            console.error("work-on-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 && !parsed.json) {
+            // eslint-disable-next-line no-console
+            console.warn(commandWarnings.map((warning) => `! ${warning}`).join("\n"));
+        }
         const service = await WorkOnTasksService.create(workspace);
         try {
             const abortController = new AbortController();
@@ -382,7 +510,7 @@ export class WorkOnTasksCommand {
             const onAgentChunk = parsed.agentStream !== false ? streamSink : undefined;
             const result = await service.workOnTasks({
                 workspace,
-                projectKey: parsed.projectKey,
+                projectKey: projectResolution.projectKey,
                 epicKey: parsed.epicKey,
                 storyKey: parsed.storyKey,
                 taskKeys: parsed.taskKeys.length ? parsed.taskKeys : undefined,
@@ -402,9 +530,12 @@ export class WorkOnTasksCommand {
                 agentAdapterOverride: parsed.agentAdapterOverride,
                 missingTestsPolicy: parsed.missingTestsPolicy,
                 allowMissingTests: parsed.allowMissingTests,
+                missingContextPolicy: parsed.missingContextPolicy,
+                executionContextPolicy: parsed.executionContextPolicy,
                 onAgentChunk,
                 abortSignal: abortController.signal,
             });
+            const warnings = [...commandWarnings, ...result.warnings];
             const success = result.results.filter((r) => r.status === "succeeded").length;
             const failed = result.results.filter((r) => r.status === "failed").length;
             const skipped = result.results.filter((r) => r.status === "skipped").length;
@@ -420,7 +551,8 @@ export class WorkOnTasksCommand {
                     succeeded: success,
                     failed,
                     skipped,
-                    warnings: result.warnings,
+                    projectKey: projectResolution.projectKey,
+                    warnings,
                 }, null, 2));
                 return;
             }
@@ -432,9 +564,9 @@ export class WorkOnTasksCommand {
                 .join("\n");
             // eslint-disable-next-line no-console
             console.log(summary);
-            if (result.warnings.length) {
+            if (warnings.length) {
                 // eslint-disable-next-line no-console
-                console.warn(result.warnings.map((w) => `! ${w}`).join("\n"));
+                console.warn(warnings.map((w) => `! ${w}`).join("\n"));
             }
         }
         catch (error) {

package/dist/commands/workspace/ProjectGuidanceCommand.d.ts

@@ -1,5 +1,6 @@
 export interface ParsedProjectGuidanceArgs {
     workspaceRoot?: string;
+    projectKey?: string;
     force: boolean;
     json: boolean;
     help: boolean;

package/dist/commands/workspace/ProjectGuidanceCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectGuidanceCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/workspace/ProjectGuidanceCommand.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAUD,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,EAAE,KAAG,yBAqDzD,CAAC;AAEF,qBAAa,sBAAsB;WACpB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA0ChD"}
+{"version":3,"file":"ProjectGuidanceCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/workspace/ProjectGuidanceCommand.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAUD,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,EAAE,KAAG,yBAgEzD,CAAC;AA2DF,qBAAa,sBAAsB;WACpB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAiEhD"}

package/dist/commands/workspace/ProjectGuidanceCommand.js

@@ -1,6 +1,7 @@
 import path from "node:path";
+import { WorkspaceRepository } from "@mcoda/db";
 import { WorkspaceResolver, ensureProjectGuidance } from "@mcoda/core";
-const USAGE = "Usage: mcoda project-guidance [--workspace <path>|--workspace-root <path>] [--force] [--json]";
+const USAGE = "Usage: mcoda project-guidance [--workspace <path>|--workspace-root <path>] [--project <key>] [--force] [--json]";
 const parseBooleanFlag = (value, defaultValue) => {
     if (value === undefined)
         return defaultValue;
@@ -25,6 +26,12 @@ export const parseProjectGuidanceArgs = (argv) => {
                 parsed.workspaceRoot = path.resolve(raw);
             continue;
         }
+        if (arg.startsWith("--project=")) {
+            const [, raw] = arg.split("=", 2);
+            if (raw)
+                parsed.projectKey = raw.trim() || undefined;
+            continue;
+        }
         if (arg.startsWith("--force=")) {
             const [, raw] = arg.split("=", 2);
             parsed.force = parseBooleanFlag(raw, true);
@@ -43,6 +50,12 @@ export const parseProjectGuidanceArgs = (argv) => {
                     i += 1;
                 }
                 break;
+            case "--project":
+                if (argv[i + 1] && !argv[i + 1].startsWith("--")) {
+                    parsed.projectKey = argv[i + 1].trim() || undefined;
+                    i += 1;
+                }
+                break;
             case "--force": {
                 const next = argv[i + 1];
                 if (next && !next.startsWith("--")) {
@@ -67,6 +80,51 @@ export const parseProjectGuidanceArgs = (argv) => {
     }
     return parsed;
 };
+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();
+    }
+};
+const pickProjectGuidanceProjectKey = (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 };
+    }
+    warnings.push("No workspace project found; creating workspace-global project guidance.");
+    return { projectKey: undefined, warnings };
+};
 export class ProjectGuidanceCommand {
     static async run(argv) {
         const parsed = parseProjectGuidanceArgs(argv);
@@ -80,20 +138,42 @@ export class ProjectGuidanceCommand {
                 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 = pickProjectGuidanceProjectKey({
+                requestedKey: parsed.projectKey,
+                configuredKey,
+                existing: existingProjects,
+            });
             const result = await ensureProjectGuidance(workspace.workspaceRoot, {
                 mcodaDir: workspace.mcodaDir,
                 force: parsed.force,
+                projectKey: projectResolution.projectKey,
             });
             if (parsed.json) {
                 // eslint-disable-next-line no-console
                 console.log(JSON.stringify({
                     workspaceRoot: workspace.workspaceRoot,
                     mcodaDir: workspace.mcodaDir,
+                    projectKey: projectResolution.projectKey ?? null,
                     path: result.path,
                     status: result.status,
+                    source: result.source ?? null,
+                    sdsSource: result.sdsSource ?? null,
+                    warnings: [...projectResolution.warnings, ...(result.warnings ?? [])],
                 }, null, 2));
                 return;
             }
+            for (const warning of projectResolution.warnings) {
+                // eslint-disable-next-line no-console
+                console.warn(`[project-guidance] ${warning}`);
+            }
+            for (const warning of result.warnings ?? []) {
+                // eslint-disable-next-line no-console
+                console.warn(`[project-guidance] ${warning}`);
+            }
             // eslint-disable-next-line no-console
             console.log(`project-guidance ${result.status}: ${result.path}`);
         }

package/dist/commands/workspace/SetWorkspaceCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SetWorkspaceCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/workspace/SetWorkspaceCommand.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SetWorkspaceCommand.d.ts","sourceRoot":"","sources":["../../../src/commands/workspace/SetWorkspaceCommand.ts"],"names":[],"mappings":"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"}