@danielblomma/cortex-mcp 2.0.6 → 2.0.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.6",
+  "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/index.ts

@@ -6,3 +6,4 @@ export * from "./default-workflows.js";
 export * from "./mcp-tools.js";
 export * from "./capabilities.js";
 export * from "./enforcement.js";
+export * from "./synced-registry.js";

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

@@ -2,7 +2,9 @@ import { z } from "zod";
 import { advanceStage, createRun, getRunState } from "./run-lifecycle.js";
 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,
@@ -44,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>;
 
@@ -79,7 +94,13 @@ function resolveWorkflow(
   workflowId: string,
   registry: Record<string, WorkflowDefinition> | undefined,
 ): WorkflowDefinition {
-  const workflows = registry ?? DEFAULT_WORKFLOWS;
+  // When the caller passes an explicit registry, it wins outright (used
+  // by tests). Otherwise we merge bundled defaults with the org-authored
+  // workflows the daemon has synced into ~/.cortex/workflows.local.json,
+  // with the synced ones taking precedence on workflow_id collisions so
+  // org overrides actually override.
+  const workflows =
+    registry ?? { ...DEFAULT_WORKFLOWS, ...loadSyncedWorkflows() };
   const workflow = workflows[workflowId];
   if (!workflow) {
     throw new Error(
@@ -148,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/core/workflow/synced-registry.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { workflowDefinitionSchema, type WorkflowDefinition } from "./schemas.js";
+
+/**
+ * Read side of the org-workflow sync cache. The daemon's
+ * workflow-sync-checker writes ~/.cortex/workflows.local.json; this
+ * module reads it. Kept in core/workflow/ rather than daemon/ so
+ * mcp-tools.ts can consult the cache without depending on daemon code.
+ *
+ * Each entry is validated against workflowDefinitionSchema before being
+ * surfaced — if the cache file is corrupt or contains stale shapes from
+ * an older daemon, those entries are silently dropped rather than
+ * crashing the read.
+ */
+
+export const SYNCED_WORKFLOWS_FILENAME = "workflows.local.json";
+
+type LocalWorkflowRecord = {
+  workflow_id: string;
+  version: number;
+  updated_at: string;
+  definition: unknown;
+};
+
+type LocalWorkflowsState = {
+  workflows?: Record<string, LocalWorkflowRecord>;
+};
+
+export function syncedWorkflowsCachePath(dir?: string): string {
+  return join(dir ?? join(homedir(), ".cortex"), SYNCED_WORKFLOWS_FILENAME);
+}
+
+/**
+ * Returns the synced org-authored workflows keyed by `workflow_id`.
+ * Empty object when the cache is missing, unreadable, malformed, or
+ * contains no valid entries. The optional `dir` argument is for tests;
+ * production callers leave it unset.
+ */
+export function loadSyncedWorkflows(
+  dir?: string,
+): Record<string, WorkflowDefinition> {
+  const path = syncedWorkflowsCachePath(dir);
+  if (!existsSync(path)) return {};
+
+  let parsed: LocalWorkflowsState;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8")) as LocalWorkflowsState;
+  } catch {
+    return {};
+  }
+  const records = parsed.workflows;
+  if (!records || typeof records !== "object") return {};
+
+  const out: Record<string, WorkflowDefinition> = {};
+  for (const [id, record] of Object.entries(records)) {
+    if (!record || typeof record !== "object") continue;
+    const result = workflowDefinitionSchema.safeParse(record.definition);
+    if (!result.success) continue;
+    out[id] = result.data;
+  }
+  return out;
+}

package/scaffold/mcp/src/daemon/main.ts

@@ -28,6 +28,7 @@ import {
 } from "./heartbeat-tracker.js";
 import { startSyncTimer } from "./sync-checker.js";
 import { startSkillSyncTimer } from "./skill-sync-checker.js";
+import { startWorkflowSyncTimer } from "./workflow-sync-checker.js";
 import { startHostEventsPusher } from "./host-events-pusher.js";
 import { startEgressProxy } from "./egress-proxy.js";
 import { startHeartbeatPusher } from "./heartbeat-pusher.js";
@@ -357,6 +358,20 @@ async function main(): Promise<void> {
     startSkillSyncTimer(process.cwd(), skillSyncMs);
   }
 
+  // Harness Phase 2: poll cortex-web for org-authored workflows, cache
+  // their definitions locally so cortex.workflow.start can resolve
+  // org-specific workflow_ids ahead of bundled defaults. Same cadence
+  // as the skill sync by default; independently configurable via
+  // CORTEX_WORKFLOW_SYNC_MS / CORTEX_DISABLE_WORKFLOW_SYNC.
+  const workflowSyncRaw = parseInt(process.env.CORTEX_WORKFLOW_SYNC_MS ?? "", 10);
+  const workflowSyncMs =
+    Number.isFinite(workflowSyncRaw) && workflowSyncRaw > 0
+      ? workflowSyncRaw
+      : skillSyncMs;
+  if (process.env.CORTEX_DISABLE_WORKFLOW_SYNC !== "1") {
+    startWorkflowSyncTimer(process.cwd(), workflowSyncMs);
+  }
+
   // Govern host heartbeat — fills host_enrollment on cortex-web so the
   // dashboard at /dashboard/govern actually shows this host.
   const heartbeatRaw = parseInt(process.env.CORTEX_HEARTBEAT_PUSH_MS ?? "", 10);