@danielblomma/cortex-mcp 2.0.7 → 2.0.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

package/scaffold/mcp/src/cli/stage.ts

@@ -9,6 +9,7 @@ import {
   type WorkflowDefinition,
 } from "../core/workflow/index.js";
 import { DEFAULT_WORKFLOWS } from "../core/workflow/default-workflows.js";
+import { isEnterpriseProject } from "../hooks/shared.js";
 
 /**
  * `cortex stage` CLI surface. Each subcommand is a thin shell wrapper
@@ -31,10 +32,23 @@ import { DEFAULT_WORKFLOWS } from "../core/workflow/default-workflows.js";
  * standalone shell calls.
  */
 
+const ENTERPRISE_REQUIRED_MESSAGE =
+  "cortex stage is part of the Cortex Harness — an enterprise-only feature. " +
+  "This project does not have an enterprise license configured (no enterprise.api_key " +
+  "in .context/enterprise.yml). Run 'cortex enterprise <api-key>' to enable it, or " +
+  "contact your org admin.";
+
 export async function runStageCommand(args: string[]): Promise<void> {
   const sub = args[0] ?? "help";
   const rest = args.slice(1);
 
+  // help is allowed in community mode so users can discover the feature exists.
+  if (sub !== "help" && sub !== "--help" && sub !== "-h") {
+    if (!isEnterpriseProject(projectRoot())) {
+      throw new Error(ENTERPRISE_REQUIRED_MESSAGE);
+    }
+  }
+
   switch (sub) {
     case "start":
       return runStart(rest);
@@ -65,6 +79,8 @@ function printHelp(): void {
     "  cortex stage envelope --task-id <id> [--stage <name>]",
     "  cortex stage advance  --task-id <id> --stage <name> --body-file <path>",
     "                        [--frontmatter-file <path>] [--status <s>] [--outcome-file <path>]",
+    "                        [--validators-passed <id1,id2,...>]",
+    "                        [--override-reason \"...\"] [--override-skipped-validators <id1,id2>]",
     "  cortex stage run      --task-id <id> -- <command> [args...]",
     "",
     "Status values: complete (default) | blocked | failed",
@@ -193,12 +209,36 @@ async function runAdvance(args: string[]): Promise<void> {
     typeof flags["outcome-file"] === "string" ? flags["outcome-file"] : null;
   const statusFlag =
     typeof flags.status === "string" ? (flags.status as StageStatus) : undefined;
+  const validatorsRaw =
+    typeof flags["validators-passed"] === "string"
+      ? flags["validators-passed"]
+      : null;
+  const overrideReason =
+    typeof flags["override-reason"] === "string"
+      ? flags["override-reason"]
+      : null;
+  const overrideSkippedRaw =
+    typeof flags["override-skipped-validators"] === "string"
+      ? flags["override-skipped-validators"]
+      : null;
 
   const body = readFileSync(bodyPath, "utf8");
   const frontmatter: Record<string, unknown> = frontmatterPath
     ? parseJsonObject(frontmatterPath)
     : {};
   const outcome = outcomePath ? parseJsonObject(outcomePath) : undefined;
+  const validatorsPassed = validatorsRaw
+    ? validatorsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+  const override = overrideReason
+    ? {
+        reason: overrideReason,
+        skipped_validators: overrideSkippedRaw
+          ? overrideSkippedRaw.split(",").map((s) => s.trim()).filter(Boolean)
+          : [],
+        skipped_requirements: [],
+      }
+    : undefined;
 
   const state = getRunState(projectRoot(), taskId);
   if (!state) {
@@ -234,6 +274,8 @@ async function runAdvance(args: string[]): Promise<void> {
     body,
     status: finalStatus,
     outcome,
+    validatorsPassed,
+    override,
   });
 
   let nextEnvelope = null;

package/scaffold/mcp/src/core/workflow/default-workflows.ts

@@ -17,6 +17,7 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "plan.md",
       reads: [],
       required_fields: ["files_targeted", "constraints"],
+      validators: [],
       capability: "planner",
       description:
         "Produce a step-by-step implementation plan grounded in the repo's rules and memory.",
@@ -26,6 +27,7 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "plan-review.md",
       reads: ["plan"],
       required_fields: ["approved", "blocking_comments"],
+      validators: [],
       capability: "reviewer",
       description:
         "Review the plan for architectural fit and rule compliance before any code is written.",
@@ -35,6 +37,18 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "changes.md",
       reads: ["plan", "plan-review"],
       required_fields: ["files_changed"],
+      validators: [
+        {
+          id: "build-passes",
+          description:
+            "The project's build / typecheck command must succeed on the produced diff.",
+        },
+        {
+          id: "tests-pass",
+          description:
+            "The project's existing test suite must pass on the produced diff.",
+        },
+      ],
       capability: "builder",
       description:
         "Implement the approved plan. Produces the diff manifest used by the downstream reviewers.",
@@ -44,6 +58,7 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "build-review.md",
       reads: ["plan", "changes"],
       required_fields: ["approved", "blocking_comments"],
+      validators: [],
       capability: "reviewer",
       description:
         "Review the implementation against the plan and the project's rules.",
@@ -53,6 +68,13 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "mutation-report.md",
       reads: ["changes"],
       required_fields: ["score", "survived"],
+      validators: [
+        {
+          id: "mutation-score",
+          description:
+            "Mutation testing tool of the agent's choice (e.g. stryker, mutmut) must run and report a score against the changed files.",
+        },
+      ],
       capability: "tester",
       description:
         "Run mutation tests on the changed files. Report score + surviving mutants.",
@@ -62,6 +84,18 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "security-report.md",
       reads: ["changes"],
       required_fields: ["findings", "severity_summary"],
+      validators: [
+        {
+          id: "secret-scan",
+          description:
+            "Scan the diff for newly committed secrets (API keys, tokens, credentials).",
+        },
+        {
+          id: "dependency-audit",
+          description:
+            "Audit any added or upgraded dependencies for known vulnerabilities.",
+        },
+      ],
       capability: "security-reviewer",
       description:
         "Security review focused on the diff: injection, authn/authz, secrets, dependency risk.",
@@ -71,6 +105,7 @@ export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
       artifact: "approval.md",
       reads: ["plan", "changes", "build-review", "mutation", "security"],
       required_fields: ["approved", "approver"],
+      validators: [],
       capability: "human",
       description:
         "Human sign-off. Pulls every prior artifact for the approver to read; the approver writes the artifact.",

package/scaffold/mcp/src/core/workflow/envelope.ts

@@ -35,6 +35,8 @@ export type ComposedEnvelope = {
   requiredFields: string[];
   /** Capability key the stage runs under (informational). */
   capability: string | null;
+  /** Validators the stage requires the agent to have run. */
+  validators: { id: string; description: string }[];
 };
 
 export type ComposeStageEnvelopeOptions = {
@@ -107,6 +109,7 @@ export function composeStageEnvelope(
 
   const requiredFields = stage.required_fields;
   const capability = stage.capability ?? null;
+  const validators = stage.validators;
 
   const prompt = renderPrompt({
     taskDescription: state.task_description,
@@ -118,6 +121,7 @@ export function composeStageEnvelope(
     requiredFields,
     capability,
     handoffs,
+    validators,
   });
 
   return {
@@ -125,6 +129,7 @@ export function composeStageEnvelope(
     expectedArtifact: stage.artifact,
     requiredFields,
     capability,
+    validators,
   };
 }
 
@@ -150,6 +155,7 @@ type RenderPromptOptions = {
   requiredFields: string[];
   capability: string | null;
   handoffs: string[];
+  validators: { id: string; description: string }[];
 };
 
 function renderPrompt(o: RenderPromptOptions): string {
@@ -200,13 +206,32 @@ function renderPrompt(o: RenderPromptOptions): string {
       ? `_No additional required fields beyond the harness defaults._`
       : o.requiredFields.map((f) => `- \`${f}\``).join("\n");
 
+  const validatorLines =
+    o.validators.length === 0
+      ? `_No validators required for this stage._`
+      : o.validators
+          .map((v) => `- \`${v.id}\` — ${v.description}`)
+          .join("\n");
+
+  sections.push(
+    [
+      `# VALIDATORS`,
+      ``,
+      `Cortex defines what must be validated; you (the agent) pick the concrete tooling and run it in this environment, then report back.`,
+      ``,
+      validatorLines,
+      ``,
+      `When you call \`cortex.workflow.advance\`, set \`validators_passed: [<id1>, <id2>, ...]\` listing every validator you successfully ran. The harness blocks the advance if a required validator is missing — unless you explicitly pass \`override\` with a reason and the list of skipped validator ids.`,
+    ].join("\n"),
+  );
+
   sections.push(
     [
       `# OUTPUT`,
       ``,
       `Produce a single markdown file named \`${o.expectedArtifact}\` with YAML frontmatter on top.`,
       ``,
-      `Required frontmatter fields (in addition to \`stage\`, \`status\`, \`references\`, \`written_at\` which the harness manages):`,
+      `Required frontmatter fields (in addition to \`stage\`, \`status\`, \`references\`, \`validators_passed\`, \`written_at\` which the harness manages):`,
       ``,
       requiredLines,
       ``,

package/scaffold/mcp/src/core/workflow/mcp-tools.ts

@@ -4,6 +4,7 @@ import { composeStageEnvelope } from "./envelope.js";
 import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
 import { loadSyncedWorkflows } from "./synced-registry.js";
 import {
+  stageOverrideSchema,
   stageStatusSchema,
   type StageStatus,
   type WorkflowDefinition,
@@ -45,6 +46,19 @@ export const WorkflowAdvanceInput = z.object({
   status: stageStatusSchema.optional(),
   /** Optional structured outcome surfaced into state.json for fast lookup by later stages. */
   outcome: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * Validators the agent reports having run for this stage. Compared
+   * against the stage definition's required validators on advance —
+   * missing entries block the call unless an override is supplied.
+   */
+  validators_passed: z.array(z.string().min(1)).default([]),
+  /**
+   * Process override. Required when validators_passed does not cover
+   * every validator the stage declares. Logged as a high-evidence
+   * audit event and stamped into the artifact's frontmatter so the
+   * deviation is visible in the evidence trail.
+   */
+  override: stageOverrideSchema.optional(),
 });
 export type WorkflowAdvanceInputT = z.infer<typeof WorkflowAdvanceInput>;
 
@@ -155,6 +169,8 @@ export function runWorkflowAdvance(
     body: input.body,
     outcome: input.outcome,
     status: finalStatus,
+    validatorsPassed: input.validators_passed,
+    override: input.override,
   });
 
   // If the run is still going, also return the next envelope so the caller

package/scaffold/mcp/src/core/workflow/run-lifecycle.ts

@@ -6,8 +6,10 @@ import {
 import {
   runStateSchema,
   stageArtifactFrontmatterSchema,
+  stageOverrideSchema,
   workflowDefinitionSchema,
   type RunState,
+  type StageOverride,
   type StageRecord,
   type StageStatus,
   type WorkflowDefinition,
@@ -36,6 +38,7 @@ export function createRun(options: CreateRunOptions): RunState {
   const stages: StageRecord[] = workflow.stages.map((stage) => ({
     name: stage.name,
     status: "pending" as StageStatus,
+    validators_passed: [],
   }));
 
   const state: RunState = {
@@ -80,6 +83,10 @@ export type AdvanceStageOptions = {
   outcome?: Record<string, unknown>;
   /** Final status to record for this stage. Defaults to "complete". */
   status?: StageStatus;
+  /** Validators the agent reports having run. Compared against stage.validators. */
+  validatorsPassed?: string[];
+  /** Process override; required when validators_passed doesn't cover stage.validators. */
+  override?: StageOverride;
   now?: () => Date;
 };
 
@@ -111,12 +118,52 @@ export function advanceStage(options: AdvanceStageOptions): RunState {
     );
   }
 
+  const stageIndex = workflow.stages.findIndex((s) => s.name === options.stageName);
+  const stageDef = workflow.stages[stageIndex];
+
+  // Validator coverage check: every validator the stage declares must
+  // appear in validators_passed unless the override explicitly skips it.
+  // Process is enforced here even though the validators themselves run
+  // in the agent's environment.
+  const validatorsPassed = options.validatorsPassed ?? [];
+  const override = options.override
+    ? stageOverrideSchema.parse(options.override)
+    : undefined;
+  const requiredValidators = stageDef.validators.map((v) => v.id);
+  const declaredSkipped = new Set(override?.skipped_validators ?? []);
+  const missingValidators = requiredValidators.filter(
+    (id) => !validatorsPassed.includes(id) && !declaredSkipped.has(id),
+  );
+  // blocked / failed stages are exempt from validator coverage — the
+  // stage is explicitly halting before completion, so the validators
+  // logically cannot have run.
+  const finalStatus = options.status ?? "complete";
+  const exemptStatus = finalStatus === "blocked" || finalStatus === "failed";
+  if (missingValidators.length > 0 && !exemptStatus) {
+    throw new Error(
+      `Stage ${options.stageName} requires validators ${requiredValidators.join(", ")} ` +
+        `but artifact reported only ${validatorsPassed.join(", ") || "<none>"}. ` +
+        `Missing: ${missingValidators.join(", ")}. ` +
+        `Pass override.skipped_validators with a reason to advance anyway.`,
+    );
+  }
+
   const now = (options.now ?? (() => new Date()))();
   const completedAt = now.toISOString();
 
   const frontmatter = stageArtifactFrontmatterSchema.parse({
     ...options.frontmatter,
     stage: options.stageName,
+    validators_passed: validatorsPassed,
+    ...(override
+      ? {
+          override: {
+            reason: override.reason,
+            skipped_validators: override.skipped_validators,
+            skipped_requirements: override.skipped_requirements,
+          },
+        }
+      : {}),
     written_at: options.frontmatter.written_at ?? completedAt,
   });
   writeStageArtifact(
@@ -127,9 +174,7 @@ export function advanceStage(options: AdvanceStageOptions): RunState {
     options.body,
   );
 
-  const stageIndex = workflow.stages.findIndex((s) => s.name === options.stageName);
   const nextStage = workflow.stages[stageIndex + 1] ?? null;
-  const finalStatus = options.status ?? "complete";
 
   const updatedStages: StageRecord[] = state.stages.map((record) => {
     if (record.name !== options.stageName) return record;
@@ -140,6 +185,8 @@ export function advanceStage(options: AdvanceStageOptions): RunState {
       started_at: record.started_at ?? state.started_at,
       completed_at: completedAt,
       outcome: options.outcome,
+      validators_passed: validatorsPassed,
+      override,
     };
   });
 

package/scaffold/mcp/src/core/workflow/schemas.ts

@@ -26,6 +26,23 @@ const slugSchema = z
     "Must be lowercase alphanumeric with hyphens (no leading/trailing hyphen)",
   );
 
+/**
+ * Validator requirement declared by a workflow stage. Cortex enforces
+ * that the agent reports having run each declared validator (via the
+ * artifact's `validators_passed` frontmatter), but never executes the
+ * validator itself — the agent picks the concrete tooling.
+ *
+ * id is a stable identifier (e.g. "mutation-score") that the agent
+ * echoes back; description is human-readable context for the agent
+ * rendered into the stage envelope.
+ */
+export const validatorRequirementSchema = z.object({
+  id: slugSchema,
+  description: z.string().min(1).max(500),
+});
+
+export type ValidatorRequirement = z.infer<typeof validatorRequirementSchema>;
+
 /**
  * Static definition of a single stage in a workflow. Authored at the
  * organization level (in cortex-web later) and synced down to projects.
@@ -37,6 +54,15 @@ export const stageDefinitionSchema = z.object({
   reads: z.array(slugSchema).default([]),
   /** Required frontmatter fields the produced artifact must populate. */
   required_fields: z.array(z.string().min(1)).default([]),
+  /**
+   * Validators the stage requires the agent to have run. The agent
+   * picks the actual tooling (e.g. stryker for mutation testing) and
+   * reports the result by listing each validator's id under
+   * `validators_passed` in the artifact frontmatter. Cortex enforces
+   * the list-coverage contract on advance unless the call carries an
+   * explicit override.
+   */
+  validators: z.array(validatorRequirementSchema).default([]),
   /** Capability key the stage runs under. References a separate capability registry. */
   capability: z.string().min(1).optional(),
   /** Human-readable summary surfaced in dashboards and audit. */
@@ -70,6 +96,21 @@ export const stageStatusSchema = z.enum([
 
 export type StageStatus = z.infer<typeof stageStatusSchema>;
 
+/**
+ * Process-override record. When a stage advances despite missing or
+ * failed validators, the caller must pass an override with a free-text
+ * reason. The override is recorded on the StageRecord, stamped into
+ * the artifact's frontmatter, and emitted as a high-evidence audit
+ * event so reviewers can see the deviation in the evidence trail.
+ */
+export const stageOverrideSchema = z.object({
+  reason: z.string().min(1).max(2000),
+  skipped_validators: z.array(z.string().min(1)).default([]),
+  skipped_requirements: z.array(z.string().min(1)).default([]),
+});
+
+export type StageOverride = z.infer<typeof stageOverrideSchema>;
+
 /**
  * Per-stage record inside state.json. Holds outcome metadata that the next
  * stage's envelope composer needs without re-parsing every artifact.
@@ -82,6 +123,10 @@ export const stageRecordSchema = z.object({
   completed_at: z.string().datetime().optional(),
   /** Frontmatter outcome surfaced for fast lookup (e.g. approved=true on review). */
   outcome: z.record(z.string(), z.unknown()).optional(),
+  /** Validators the agent reported having run for this stage. */
+  validators_passed: z.array(z.string().min(1)).default([]),
+  /** Override record if the stage advanced despite missing/failed requirements. */
+  override: stageOverrideSchema.optional(),
 });
 
 export type StageRecord = z.infer<typeof stageRecordSchema>;

package/scaffold/mcp/src/enterprise/index.ts

@@ -14,6 +14,7 @@ import { pushAuditEvents, queueAuditEvent, setAuditPushContext } from "./audit/p
 import { PolicyStore } from "../core/policy/store.js";
 import { syncFromCloud, syncFromLocal } from "./policy/sync.js";
 import { registerEnterpriseTools } from "./tools/enterprise.js";
+import { registerHarnessTools } from "./tools/harness.js";
 import { pushViolations, setViolationPushContext } from "./violations/push.js";
 import { pushReviewResults, setReviewPushContext } from "./reviews/push.js";
 import { setWorkflowPushContext } from "./workflow/push.js";
@@ -319,6 +320,10 @@ export async function register(server: McpServer): Promise<void> {
   }
 
   registerEnterpriseTools(server, collector, auditWriter, config, contextDir, policyStore, version);
+  // Cortex Harness MCP tools (cortex.workflow.*) — only registered for
+  // enterprise projects, since they depend on org-authored workflows
+  // synced from cortex-web (also enterprise-only).
+  registerHarnessTools(server);
 
   // v2.0.0: globalThis.__cortexContextToolHook bridge removed.
   // Enterprise is now in-process with cortex-mcp; tool events flow via

package/scaffold/mcp/src/enterprise/tools/harness.ts

@@ -0,0 +1,98 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  WorkflowAdvanceInput,
+  WorkflowEnvelopeInput,
+  WorkflowStartInput,
+  WorkflowStatusInput,
+  resolveProjectRoot,
+  runWorkflowAdvance,
+  runWorkflowEnvelope,
+  runWorkflowStart,
+  runWorkflowStatus,
+} from "../../core/workflow/mcp-tools.js";
+
+/**
+ * Registers the cortex.workflow.* tools that drive the Cortex Harness.
+ * These are an enterprise-only feature: they're only registered when
+ * the enterprise plugin successfully loads (license + config valid).
+ *
+ * Community-mode MCP servers do not see these tools at all — the
+ * harness depends on org-authored workflows from cortex-web, which
+ * itself requires an enterprise plan.
+ *
+ * Pure runner functions live in core/workflow/mcp-tools.ts so they can
+ * be unit-tested without spinning up an MCP server. This module only
+ * wires them onto the server with the right tool names + input schemas.
+ */
+
+type ToolPayload = Record<string, unknown>;
+
+export function registerHarnessTools(server: McpServer): void {
+  server.registerTool(
+    "cortex.workflow.start",
+    {
+      description:
+        "Start a Cortex Harness workflow run for a task. Creates .agents/<task_id>/state.json and returns the first stage's envelope (the prompt the agent should answer). Enterprise-only.",
+      inputSchema: WorkflowStartInput,
+    },
+    async (input) => buildResult(
+      runWorkflowStart(WorkflowStartInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+
+  server.registerTool(
+    "cortex.workflow.advance",
+    {
+      description:
+        "Complete the current stage of a workflow run by writing its artifact and advancing the run pointer. Returns the new run state plus the next stage's envelope (or null when the run is finished, blocked, or failed). Enterprise-only.",
+      inputSchema: WorkflowAdvanceInput,
+    },
+    async (input) => buildResult(
+      runWorkflowAdvance(WorkflowAdvanceInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+
+  server.registerTool(
+    "cortex.workflow.status",
+    {
+      description:
+        "Read the current run state for a task (current stage, completed stages, outcome). Returns null state when no run exists for the given task_id. Enterprise-only.",
+      inputSchema: WorkflowStatusInput,
+    },
+    async (input) => buildResult(
+      runWorkflowStatus(WorkflowStatusInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+
+  server.registerTool(
+    "cortex.workflow.envelope",
+    {
+      description:
+        "Compose the prompt envelope for a workflow stage without advancing the run. Defaults to the run's current_stage; pass `stage` to dry-run a different stage. Enterprise-only.",
+      inputSchema: WorkflowEnvelopeInput,
+    },
+    async (input) => buildResult(
+      runWorkflowEnvelope(WorkflowEnvelopeInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+      }) as ToolPayload,
+    ),
+  );
+}
+
+function buildResult(data: ToolPayload) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+    structuredContent: data,
+  };
+}

package/scaffold/mcp/src/server.ts

@@ -11,17 +11,6 @@ import {
   getSessionEventHook,
   loadPlugins,
 } from "./plugin.js";
-import {
-  WorkflowStartInput,
-  WorkflowAdvanceInput,
-  WorkflowStatusInput,
-  WorkflowEnvelopeInput,
-  resolveProjectRoot,
-  runWorkflowAdvance,
-  runWorkflowEnvelope,
-  runWorkflowStart,
-  runWorkflowStatus,
-} from "./core/workflow/mcp-tools.js";
 
 type ToolPayload = Record<string, unknown>;
 
@@ -334,69 +323,10 @@ function registerTools(server: McpServer): void {
     })
   );
 
-  server.registerTool(
-    "cortex.workflow.start",
-    {
-      description:
-        "Start a Cortex Harness workflow run for a task. Creates .agents/<task_id>/state.json and returns the first stage's envelope (the prompt the agent should answer).",
-      inputSchema: WorkflowStartInput,
-    },
-    async (input) => executeInstrumentedTool(
-      "cortex.workflow.start",
-      input,
-      async () => runWorkflowStart(WorkflowStartInput.parse(input ?? {}), {
-        cwd: resolveProjectRoot(),
-      }) as ToolPayload,
-    ),
-  );
-
-  server.registerTool(
-    "cortex.workflow.advance",
-    {
-      description:
-        "Complete the current stage of a workflow run by writing its artifact and advancing the run pointer. Returns the new run state plus the next stage's envelope (or null when the run is finished, blocked, or failed).",
-      inputSchema: WorkflowAdvanceInput,
-    },
-    async (input) => executeInstrumentedTool(
-      "cortex.workflow.advance",
-      input,
-      async () => runWorkflowAdvance(WorkflowAdvanceInput.parse(input ?? {}), {
-        cwd: resolveProjectRoot(),
-      }) as ToolPayload,
-    ),
-  );
-
-  server.registerTool(
-    "cortex.workflow.status",
-    {
-      description:
-        "Read the current run state for a task (current stage, completed stages, outcome). Returns null state when no run exists for the given task_id.",
-      inputSchema: WorkflowStatusInput,
-    },
-    async (input) => executeInstrumentedTool(
-      "cortex.workflow.status",
-      input,
-      async () => runWorkflowStatus(WorkflowStatusInput.parse(input ?? {}), {
-        cwd: resolveProjectRoot(),
-      }) as ToolPayload,
-    ),
-  );
-
-  server.registerTool(
-    "cortex.workflow.envelope",
-    {
-      description:
-        "Compose the prompt envelope for a workflow stage without advancing the run. Defaults to the run's current_stage; pass `stage` to dry-run a different stage.",
-      inputSchema: WorkflowEnvelopeInput,
-    },
-    async (input) => executeInstrumentedTool(
-      "cortex.workflow.envelope",
-      input,
-      async () => runWorkflowEnvelope(WorkflowEnvelopeInput.parse(input ?? {}), {
-        cwd: resolveProjectRoot(),
-      }) as ToolPayload,
-    ),
-  );
+  // Note: cortex.workflow.* tools (the Cortex Harness) are enterprise-only
+  // and registered by enterprise/index.ts::register() once the license has
+  // verified. They intentionally do not appear here so community-mode MCP
+  // servers do not surface them at all.
 }
 
 let shutdownCalled = false;

package/scaffold/mcp/tests/workflow-cli.test.mjs

@@ -9,6 +9,15 @@ import { runStageCommand } from "../dist/cli/stage.js";
 function makeWorkspace() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-stage-cli-"));
   process.env.CORTEX_PROJECT_ROOT = dir;
+  // cortex stage is enterprise-only; satisfy the gate by writing a
+  // minimal enterprise.yml. isEnterpriseProject only requires a
+  // non-empty enterprise.api_key field.
+  fs.mkdirSync(path.join(dir, ".context"), { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, ".context", "enterprise.yml"),
+    "enterprise:\n  api_key: test-key-for-cli-tests\n",
+    "utf8",
+  );
   return dir;
 }
 
@@ -289,5 +298,37 @@ test("stage help: prints help text and returns without throwing", async () => {
 });
 
 test("stage <unknown>: throws with help text", async () => {
+  makeWorkspace();
   await assert.rejects(runStageCommand(["frobnicate"]), /Unknown stage subcommand/);
 });
+
+test("stage start: blocked in community mode (no enterprise.yml)", async () => {
+  // Bypass the helper that auto-writes enterprise.yml.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-stage-cli-community-"));
+  process.env.CORTEX_PROJECT_ROOT = dir;
+  try {
+    await assert.rejects(
+      runStageCommand([
+        "start",
+        "--task-id",
+        "task-1",
+        "--description",
+        "x",
+      ]),
+      /Cortex Harness — an enterprise-only feature/,
+    );
+  } finally {
+    delete process.env.CORTEX_PROJECT_ROOT;
+  }
+});
+
+test("stage help: still prints in community mode (so users discover the feature)", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-stage-cli-community-help-"));
+  process.env.CORTEX_PROJECT_ROOT = dir;
+  try {
+    const { captured } = await captureStdout(() => runStageCommand(["help"]));
+    assert.match(captured, /Usage:/);
+  } finally {
+    delete process.env.CORTEX_PROJECT_ROOT;
+  }
+});

package/scaffold/mcp/tests/workflow-validators-override.test.mjs

@@ -0,0 +1,272 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  createRun,
+  advanceStage,
+} from "../dist/core/workflow/run-lifecycle.js";
+import { composeStageEnvelope } from "../dist/core/workflow/envelope.js";
+import {
+  runWorkflowAdvance,
+  runWorkflowStart,
+} from "../dist/core/workflow/mcp-tools.js";
+
+function makeWorkspace() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-validators-"));
+}
+
+const WORKFLOW = {
+  id: "validated",
+  description: "One stage that requires two validators",
+  version: 1,
+  stages: [
+    {
+      name: "build",
+      artifact: "changes.md",
+      reads: [],
+      required_fields: [],
+      validators: [
+        { id: "tests-pass", description: "Test suite must pass" },
+        { id: "build-passes", description: "Build must succeed" },
+      ],
+      capability: "builder",
+      description: "Implement the change.",
+    },
+  ],
+};
+
+const REGISTRY = { validated: WORKFLOW };
+
+test("advanceStage: blocks when validators_passed misses required ids", () => {
+  const cwd = makeWorkspace();
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    taskDescription: "Test",
+  });
+
+  assert.throws(
+    () =>
+      advanceStage({
+        cwd,
+        taskId: "task-1",
+        workflow: WORKFLOW,
+        stageName: "build",
+        artifactName: "changes.md",
+        frontmatter: { stage: "build", status: "complete", references: [] },
+        body: "# Changes",
+        validatorsPassed: ["tests-pass"], // missing build-passes
+      }),
+    /Missing: build-passes/,
+  );
+});
+
+test("advanceStage: allows when validators_passed covers required ids", () => {
+  const cwd = makeWorkspace();
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    taskDescription: "Test",
+  });
+
+  const next = advanceStage({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    stageName: "build",
+    artifactName: "changes.md",
+    frontmatter: { stage: "build", status: "complete", references: [] },
+    body: "# Changes",
+    validatorsPassed: ["tests-pass", "build-passes"],
+  });
+  assert.equal(next.outcome, "complete");
+  assert.deepEqual(next.stages[0].validators_passed, ["tests-pass", "build-passes"]);
+});
+
+test("advanceStage: override.skipped_validators bypasses missing-validator block", () => {
+  const cwd = makeWorkspace();
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    taskDescription: "Test",
+  });
+
+  const next = advanceStage({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    stageName: "build",
+    artifactName: "changes.md",
+    frontmatter: { stage: "build", status: "complete", references: [] },
+    body: "# Changes",
+    validatorsPassed: ["tests-pass"],
+    override: {
+      reason: "Build infra is down on CI; skipping per ops-incident-2026-05-06",
+      skipped_validators: ["build-passes"],
+    },
+  });
+
+  assert.equal(next.outcome, "complete");
+  assert.equal(next.stages[0].override?.reason.includes("Build infra is down"), true);
+  assert.deepEqual(next.stages[0].override?.skipped_validators, ["build-passes"]);
+});
+
+test("advanceStage: blocked status is exempt from validator coverage check", () => {
+  const cwd = makeWorkspace();
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    taskDescription: "Test",
+  });
+
+  const next = advanceStage({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    stageName: "build",
+    artifactName: "changes.md",
+    frontmatter: { stage: "build", status: "blocked", references: [] },
+    body: "# Plan blocked\n\nMissing context.",
+    status: "blocked",
+    validatorsPassed: [], // exempt
+  });
+  assert.equal(next.outcome, "blocked");
+});
+
+test("advanceStage: override is stamped into the artifact frontmatter", () => {
+  const cwd = makeWorkspace();
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    taskDescription: "Test",
+  });
+
+  advanceStage({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    stageName: "build",
+    artifactName: "changes.md",
+    frontmatter: { stage: "build", status: "complete", references: [] },
+    body: "# Changes",
+    validatorsPassed: ["tests-pass"],
+    override: {
+      reason: "Hot fix, will follow up",
+      skipped_validators: ["build-passes"],
+    },
+  });
+
+  const text = fs.readFileSync(
+    path.join(cwd, ".agents", "task-1", "changes.md"),
+    "utf8",
+  );
+  assert.match(text, /override:/);
+  assert.match(text, /reason: Hot fix/);
+  assert.match(text, /- build-passes/);
+});
+
+test("composeStageEnvelope: renders VALIDATORS section when stage declares them", () => {
+  const cwd = makeWorkspace();
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+    taskDescription: "Test",
+  });
+
+  const env = composeStageEnvelope({
+    cwd,
+    taskId: "task-1",
+    workflow: WORKFLOW,
+  });
+
+  assert.match(env.prompt, /# VALIDATORS/);
+  assert.match(env.prompt, /`tests-pass` — Test suite must pass/);
+  assert.match(env.prompt, /`build-passes` — Build must succeed/);
+  assert.match(env.prompt, /`validators_passed: \[<id1>, <id2>, \.\.\.\]`/);
+  assert.deepEqual(env.validators.map((v) => v.id), ["tests-pass", "build-passes"]);
+});
+
+test("composeStageEnvelope: VALIDATORS section is empty when stage has none", () => {
+  const cwd = makeWorkspace();
+  const noValidators = {
+    ...WORKFLOW,
+    stages: [{ ...WORKFLOW.stages[0], validators: [] }],
+  };
+  createRun({
+    cwd,
+    taskId: "task-1",
+    workflow: noValidators,
+    taskDescription: "Test",
+  });
+
+  const env = composeStageEnvelope({
+    cwd,
+    taskId: "task-1",
+    workflow: noValidators,
+  });
+
+  assert.match(env.prompt, /No validators required for this stage/);
+  assert.equal(env.validators.length, 0);
+});
+
+test("runWorkflowAdvance MCP runner: forwards validators_passed + override", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-1", task_description: "x", workflow_id: "validated" },
+    { cwd, workflows: REGISTRY },
+  );
+
+  const result = runWorkflowAdvance(
+    {
+      task_id: "task-1",
+      stage: "build",
+      frontmatter: {},
+      body: "# Changes",
+      validators_passed: ["tests-pass"],
+      override: {
+        reason: "CI builder offline; manual verification done",
+        skipped_validators: ["build-passes"],
+        skipped_requirements: [],
+      },
+    },
+    { cwd, workflows: REGISTRY },
+  );
+
+  assert.equal(result.state.outcome, "complete");
+  assert.equal(
+    result.state.stages[0].override?.reason.includes("CI builder offline"),
+    true,
+  );
+});
+
+test("runWorkflowAdvance MCP runner: rejects missing validators without override", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-1", task_description: "x", workflow_id: "validated" },
+    { cwd, workflows: REGISTRY },
+  );
+
+  assert.throws(
+    () =>
+      runWorkflowAdvance(
+        {
+          task_id: "task-1",
+          stage: "build",
+          frontmatter: {},
+          body: "# Changes",
+          validators_passed: [],
+        },
+        { cwd, workflows: REGISTRY },
+      ),
+    /Missing: tests-pass, build-passes/,
+  );
+});