@saiteja1123/mcp-server 1.1.4 → 1.1.6

package/src/deep-scan/ralph-tasks.js

@@ -0,0 +1,598 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { createArtifactRef, validateRunIdSegment } from './contracts.js';
+import { assertSourceSafePayload, cloneSourceSafe, findRawSourceField } from './sourceSafe.js';
+
+export const AGENT_FIX_TASK_SCHEMA_VERSION = 'agent_fix_task.v1';
+export const AGENT_FIX_TASK_STEPPER_ID = 'ralph.tasks';
+export const AGENT_FIX_TASK_STEPPER_VERSION = '1.0.0';
+export const AGENT_FIX_TASK_STATUSES = Object.freeze(['ready', 'manual', 'blocked']);
+
+const TASKS_FILE = 'agent-fix-tasks.json';
+const SHA256 = /^[a-f0-9]{64}$/i;
+const UUIDISH = /^[a-zA-Z0-9_.:-]+$/;
+
+const READY_CATEGORIES = new Set([
+  'api_abuse',
+  'auth_session',
+  'deployment_config',
+  'input_validation_xss',
+  'injection',
+  'path_traversal',
+  'secrets_config',
+  'ssrf',
+]);
+
+const CATEGORY_TEMPLATES = Object.freeze({
+  secrets_config: {
+    label: 'Secret and configuration handling',
+    problem: 'A secret or configuration handling risk is linked to local evidence. Keep secret values outside source, prompts, logs, and Vibesecur artifacts.',
+    requiredBehavior: 'Move sensitive values to the local or deployment secret manager, leave only safe references in source, and preserve Vibesecur metadata-only artifacts.',
+    rollback: 'If the change breaks startup, restore the previous local configuration and retry with a secret-manager-backed reference.',
+  },
+  injection: {
+    label: 'Injection defense',
+    problem: 'A deterministic finding indicates untrusted input may reach an executable, query, or interpreter boundary.',
+    requiredBehavior: 'Constrain the input path with parameterization, allowlists, or safe framework APIs before execution or query construction.',
+    rollback: 'If behavior regresses, restore the previous call path and isolate the unsafe input boundary with a narrower test case.',
+  },
+  input_validation_xss: {
+    label: 'Input validation and XSS defense',
+    problem: 'A finding or test-plan candidate points to user-controlled data reaching a browser-rendered or HTML-sensitive surface.',
+    requiredBehavior: 'Encode or sanitize untrusted data at the correct boundary and keep framework escaping enabled.',
+    rollback: 'If rendering changes break expected UI behavior, restore the rendering path and add a focused escaping regression test first.',
+  },
+  ssrf: {
+    label: 'Outbound request control',
+    problem: 'A finding or test-plan candidate points to user-influenced outbound network requests.',
+    requiredBehavior: 'Restrict outbound targets with a fixed allowlist, reject private or metadata-network destinations, and keep redirects bounded.',
+    rollback: 'If legitimate integrations fail, restore the previous integration path and add explicit allowed destinations one at a time.',
+  },
+  path_traversal: {
+    label: 'Filesystem path containment',
+    problem: 'A finding or test-plan candidate indicates a path may escape the intended project or storage root.',
+    requiredBehavior: 'Resolve paths against the intended root, reject traversal or absolute escape attempts, and keep reads/writes inside the bound directory.',
+    rollback: 'If legitimate file access fails, restore the previous path and add a focused containment test for the intended safe directory.',
+  },
+  api_abuse: {
+    label: 'API abuse and authorization control',
+    problem: 'A route-like surface needs explicit abuse, authorization, validation, or quota coverage.',
+    requiredBehavior: 'Keep authentication, authorization, validation, rate limits, and quota checks fail-closed before privileged behavior runs.',
+    rollback: 'If a legitimate route flow breaks, restore the prior behavior and reintroduce the control behind a narrower route-level test.',
+  },
+  auth_session: {
+    label: 'Auth and session review',
+    problem: 'Auth or session behavior requires local review with credentials, cookies, or tokens that must not be copied into artifacts.',
+    requiredBehavior: 'Verify login, logout, session refresh, token expiry, and unauthorized access locally without exposing credential values.',
+    rollback: 'If auth flow changes lock out legitimate users, revert the local change and capture a redacted failure summary for human review.',
+  },
+  deployment_config: {
+    label: 'Deployment configuration review',
+    problem: 'Deployment metadata needs review for secret handling, security headers, and runtime configuration boundaries.',
+    requiredBehavior: 'Keep deployment secrets referenced through the host secret manager and preserve security controls in runtime config.',
+    rollback: 'If deployment config changes fail, restore the prior deployment file and add one configuration control at a time.',
+  },
+  manual_review: {
+    label: 'Manual security review',
+    problem: 'This category is not yet covered by a deterministic Ralph template and requires manual review by a human in the local project.',
+    requiredBehavior: 'Inspect the linked local files and evidence, define the smallest safe fix or acceptance decision, and keep values out of Vibesecur artifacts.',
+    rollback: 'If the review cannot produce a safe local action, leave the task manual and require human approval before release reliance.',
+  },
+});
+
+const nowIso = () => new Date().toISOString();
+
+function stableSort(value) {
+  if (Array.isArray(value)) return value.map(stableSort);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = stableSort(value[key]);
+      return acc;
+    }, {});
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableSort(value));
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function requireString(value, name, { max = 500, pattern = null } = {}) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  if (value.length > max) throw new Error(`${name} must be ${max} characters or fewer`);
+  if (pattern && !pattern.test(value)) throw new Error(`${name} has an invalid format`);
+  return value;
+}
+
+function optionalString(value, name, options) {
+  if (value === undefined || value === null) return null;
+  return requireString(value, name, options);
+}
+
+function requireIsoDate(value, name) {
+  requireString(value, name, { max: 40 });
+  if (Number.isNaN(Date.parse(value))) throw new Error(`${name} must be an ISO timestamp`);
+  return value;
+}
+
+function asArray(value, name) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value;
+}
+
+function asObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value;
+}
+
+function safeText(value, fallback, max = 300) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+  if (!text) return fallback;
+  if (findRawSourceField(text, 'agentFixTask.text')) return fallback;
+  return text;
+}
+
+function safeIdSegment(value, fallback = 'item') {
+  const token = String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9_.:-]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 80);
+  return token || fallback;
+}
+
+function normalizeSeverity(value) {
+  const severity = safeIdSegment(value || 'medium', 'medium');
+  return ['critical', 'high', 'medium', 'low'].includes(severity) ? severity : 'medium';
+}
+
+function countsBy(items, key) {
+  return items.reduce((acc, item) => {
+    const value = item[key] || 'unknown';
+    acc[value] = (acc[value] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function deterministicFindingMap(deterministicScan = {}) {
+  return new Map((deterministicScan.findings || []).map((finding) => [finding.id, finding]));
+}
+
+function selectTemplate(category) {
+  if (READY_CATEGORIES.has(category)) return CATEGORY_TEMPLATES[category];
+  return CATEGORY_TEMPLATES.manual_review;
+}
+
+function candidateStatus(candidate, category) {
+  if (!READY_CATEGORIES.has(category)) return 'manual';
+  if (candidate.status === 'blocked') return 'blocked';
+  if (candidate.status === 'manual') return 'manual';
+  return 'ready';
+}
+
+function statusReason(candidate, status, category) {
+  if (status === 'blocked') {
+    return safeText(candidate.blockedReason, 'This task is blocked until the missing local harness, dependency, or environment is supplied.', 400);
+  }
+  if (status === 'manual' && !READY_CATEGORIES.has(category)) {
+    return 'No deterministic Ralph template exists for this category yet; human local review is required.';
+  }
+  if (status === 'manual') {
+    return safeText(candidate.manualReason, 'Manual local review is required before release reliance.', 400);
+  }
+  return null;
+}
+
+function taskIdFor(candidate) {
+  return `fix-${sha256(candidate.dedupeKey || candidate.id || candidate.title).slice(0, 16)}`;
+}
+
+function targetFilesFor(candidate) {
+  const files = asArray(candidate.targetSurface?.files, 'testCase.targetSurface.files')
+    .map((file, index) => requireString(file, `testCase.targetSurface.files[${index}]`, { max: 300 }));
+  return files.length > 0 ? files : ['local-target-requires-review'];
+}
+
+function artifactRefsFor(candidate, sourceRefs) {
+  return [...new Set([
+    sourceRefs.securityTestPlan,
+    ...asArray(candidate.sourceArtifactRefs, 'testCase.sourceArtifactRefs'),
+  ].filter(Boolean))];
+}
+
+function sourceFindingsFor(candidate, findingById) {
+  return asArray(candidate.sourceFindingIds, 'testCase.sourceFindingIds')
+    .map((findingId) => {
+      const finding = findingById.get(findingId);
+      if (!finding) {
+        throw new Error(`agentFixTask.sourceFindingIds references unknown deterministic finding ${findingId}`);
+      }
+      return finding;
+    });
+}
+
+function verificationCommand({ candidate, status }) {
+  if (status === 'blocked') return null;
+  if (candidate.suggestedCommand) return safeText(candidate.suggestedCommand, 'Run the linked local test command.', 300);
+  if (status === 'manual') {
+    return 'Manual local review with redacted notes; then rerun Vibesecur MCP for the bound root.';
+  }
+  return 'Create or identify a focused local regression test, run it, then rerun Vibesecur MCP for the bound root.';
+}
+
+function buildInstructions({ candidate, template, status, targetFiles }) {
+  const title = safeText(candidate.title, 'security task', 180);
+  const fileScope = targetFiles.join(', ');
+  const verification = verificationCommand({ candidate, status });
+  const rerun = 'Rerun Vibesecur MCP with `deepScanStart` or `scanSummary` on the bound root and compare this task against the linked artifact refs.';
+  const acceptedRiskPath = 'If the risk cannot be fixed now, require human approval and record an accepted-risk reference before release reliance.';
+  return {
+    problem: `${template.problem} Candidate: ${title}.`,
+    likelyFileScope: `Inspect only the linked local target files: ${fileScope}.`,
+    requiredBehavior: template.requiredBehavior,
+    verification: verification || 'Supply the missing local harness or environment, then run the focused verification command.',
+    rerun,
+    rollback: template.rollback,
+    acceptedRiskPath,
+    localFirst: 'Do not paste source bodies, credentials, cookies, provider keys, install tokens, JWTs, or env values into Vibesecur artifacts or prompts.',
+  };
+}
+
+function makeTask({ candidate, findingById, sourceRefs }) {
+  const category = safeIdSegment(candidate.category, 'manual_review');
+  const template = selectTemplate(category);
+  const status = candidateStatus(candidate, category);
+  const findingIds = asArray(candidate.sourceFindingIds, 'testCase.sourceFindingIds')
+    .map((id, index) => requireString(id, `testCase.sourceFindingIds[${index}]`, { max: 160, pattern: UUIDISH }));
+  const testPlanCandidateIds = [requireString(candidate.id, 'testCase.id', { max: 120, pattern: UUIDISH })];
+  const targetFiles = targetFilesFor(candidate);
+  const artifactRefs = artifactRefsFor(candidate, sourceRefs);
+  const relatedFindings = sourceFindingsFor(candidate, findingById);
+  const risk = normalizeSeverity(candidate.priority || candidate.risk || relatedFindings[0]?.severity);
+  const instructions = buildInstructions({ candidate, template, status, targetFiles });
+  const command = verificationCommand({ candidate, status });
+  const reason = statusReason(candidate, status, category);
+  const task = {
+    taskId: taskIdFor(candidate),
+    version: AGENT_FIX_TASK_SCHEMA_VERSION,
+    title: safeText(candidate.title, `${template.label} task`, 220),
+    category: READY_CATEGORIES.has(category) ? category : 'manual_review',
+    status,
+    safeSummary: safeText(
+      candidate.purpose,
+      `${template.label} task generated from source-safe Test Plan evidence.`,
+      500,
+    ),
+    findingIds,
+    testPlanCandidateIds,
+    artifactRefs,
+    targetFiles,
+    instructions,
+    verification: {
+      command,
+      expectedOutcome: 'Local verification runs or manual review is recorded, then Vibesecur rerun evidence no longer shows the linked unresolved risk unless human acceptance is recorded.',
+      rerunVibesecur: 'Use the bound-root MCP Deep Scan or scan summary path after local changes; do not rely on edit claims alone.',
+    },
+    risk: {
+      severity: risk,
+      priority: normalizeSeverity(candidate.priority || risk),
+      category: READY_CATEGORIES.has(category) ? category : 'manual_review',
+    },
+    acceptedRiskRef: null,
+    blockedReason: status === 'blocked' ? reason : null,
+    manualReason: status === 'manual' ? reason : null,
+    metadata: {
+      generatedFrom: AGENT_FIX_TASK_STEPPER_ID,
+      template: READY_CATEGORIES.has(category) ? category : 'manual_review',
+      sourceStatus: candidate.status || null,
+      sourceRank: Number.isInteger(candidate.rank) ? candidate.rank : null,
+      sourceDedupeKey: safeText(candidate.dedupeKey, candidate.id, 240),
+      sourceFindingCount: findingIds.length,
+    },
+  };
+  if (task.artifactRefs.length === 0) throw new Error('agentFixTask.artifactRefs must include source artifact refs');
+  if (task.findingIds.length === 0 && task.testPlanCandidateIds.length === 0) {
+    throw new Error('agentFixTask must reference findings or test-plan items');
+  }
+  assertSourceSafePayload(task, 'agentFixTask');
+  return task;
+}
+
+function buildSources({ securityTestPlan = {}, deterministicScan = {}, sourceRefs }) {
+  return {
+    securityTestPlan: {
+      artifactRef: sourceRefs.securityTestPlan,
+      schemaVersion: securityTestPlan.schemaVersion || null,
+      totalTests: securityTestPlan.summary?.totalTests || 0,
+      downstreamContract: cloneSourceSafe(securityTestPlan.downstreamContract || {}, 'agentFixTask.sources.testPlanContract'),
+    },
+    deterministicScan: {
+      artifactRef: sourceRefs.deterministicScan,
+      schemaVersion: deterministicScan.schemaVersion || null,
+      findingCount: (deterministicScan.findings || []).length,
+    },
+  };
+}
+
+export function buildAgentFixTaskArtifact({
+  securityTestPlan,
+  deterministicScan = {},
+  generatedAt = nowIso(),
+  sourceRefs = {},
+} = {}) {
+  const safeTestPlan = cloneSourceSafe(securityTestPlan || {}, 'agentFixTask.securityTestPlanInput');
+  const safeDeterministicScan = cloneSourceSafe(deterministicScan || {}, 'agentFixTask.deterministicScanInput');
+  const refs = {
+    securityTestPlan: sourceRefs.securityTestPlan || 'security_test_plan',
+    deterministicScan: sourceRefs.deterministicScan || 'deterministic_scan',
+  };
+  const findingById = deterministicFindingMap(safeDeterministicScan);
+  const tasks = asArray(safeTestPlan.testCases, 'securityTestPlan.testCases')
+    .map((candidate) => makeTask({ candidate, findingById, sourceRefs: refs }));
+  const artifact = {
+    schemaVersion: AGENT_FIX_TASK_SCHEMA_VERSION,
+    generatedAt: requireIsoDate(generatedAt, 'agentFixTask.generatedAt'),
+    root: {
+      name: safeTestPlan.root?.name || safeDeterministicScan.root?.name || 'project',
+      pathHash: safeTestPlan.root?.pathHash || safeDeterministicScan.root?.pathHash || null,
+    },
+    sources: buildSources({
+      securityTestPlan: safeTestPlan,
+      deterministicScan: safeDeterministicScan,
+      sourceRefs: refs,
+    }),
+    summary: {
+      totalTasks: tasks.length,
+      byStatus: countsBy(tasks, 'status'),
+      byCategory: countsBy(tasks, 'category'),
+      readyCount: tasks.filter((task) => task.status === 'ready').length,
+      manualCount: tasks.filter((task) => task.status === 'manual').length,
+      blockedCount: tasks.filter((task) => task.status === 'blocked').length,
+      highOrCriticalCount: tasks.filter((task) => ['critical', 'high'].includes(task.risk.severity)).length,
+    },
+    templates: {
+      version: AGENT_FIX_TASK_SCHEMA_VERSION,
+      categories: Object.keys(CATEGORY_TEMPLATES).sort(),
+      unknownCategoryFallback: 'manual_review',
+    },
+    tasks,
+    privacy: {
+      rawSourceStored: false,
+      secretValuesCaptured: false,
+      instructionsAreTemplates: true,
+      artifactStorage: 'local_metadata_and_hash_refs',
+    },
+  };
+  return validateAgentFixTaskArtifact(artifact);
+}
+
+function validateInstructions(input = {}) {
+  const instructions = {
+    problem: requireString(input.problem, 'agentFixTask.instructions.problem', { max: 700 }),
+    likelyFileScope: requireString(input.likelyFileScope, 'agentFixTask.instructions.likelyFileScope', { max: 500 }),
+    requiredBehavior: requireString(input.requiredBehavior, 'agentFixTask.instructions.requiredBehavior', { max: 700 }),
+    verification: requireString(input.verification, 'agentFixTask.instructions.verification', { max: 700 }),
+    rerun: requireString(input.rerun, 'agentFixTask.instructions.rerun', { max: 700 }),
+    rollback: requireString(input.rollback, 'agentFixTask.instructions.rollback', { max: 700 }),
+    acceptedRiskPath: requireString(input.acceptedRiskPath, 'agentFixTask.instructions.acceptedRiskPath', { max: 700 }),
+    localFirst: requireString(input.localFirst, 'agentFixTask.instructions.localFirst', { max: 700 }),
+  };
+  assertSourceSafePayload(instructions, 'agentFixTask.instructions');
+  return instructions;
+}
+
+function validateTask(input = {}) {
+  assertSourceSafePayload(input, 'agentFixTask');
+  const status = requireString(input.status, 'agentFixTask.status', { max: 40, pattern: UUIDISH });
+  if (!AGENT_FIX_TASK_STATUSES.includes(status)) {
+    throw new Error(`agentFixTask.status must be one of ${AGENT_FIX_TASK_STATUSES.join(', ')}`);
+  }
+  const task = {
+    taskId: requireString(input.taskId, 'agentFixTask.taskId', { max: 120, pattern: UUIDISH }),
+    version: requireString(input.version, 'agentFixTask.version', { max: 80, pattern: UUIDISH }),
+    title: requireString(input.title, 'agentFixTask.title', { max: 220 }),
+    category: requireString(input.category, 'agentFixTask.category', { max: 80, pattern: UUIDISH }),
+    status,
+    safeSummary: requireString(input.safeSummary, 'agentFixTask.safeSummary', { max: 500 }),
+    findingIds: asArray(input.findingIds, 'agentFixTask.findingIds')
+      .map((id, index) => requireString(id, `agentFixTask.findingIds[${index}]`, { max: 160, pattern: UUIDISH })),
+    testPlanCandidateIds: asArray(input.testPlanCandidateIds, 'agentFixTask.testPlanCandidateIds')
+      .map((id, index) => requireString(id, `agentFixTask.testPlanCandidateIds[${index}]`, { max: 160, pattern: UUIDISH })),
+    artifactRefs: asArray(input.artifactRefs, 'agentFixTask.artifactRefs')
+      .map((id, index) => requireString(id, `agentFixTask.artifactRefs[${index}]`, { max: 160, pattern: UUIDISH })),
+    targetFiles: asArray(input.targetFiles, 'agentFixTask.targetFiles')
+      .map((file, index) => requireString(file, `agentFixTask.targetFiles[${index}]`, { max: 300 })),
+    instructions: validateInstructions(input.instructions || {}),
+    verification: {
+      command: optionalString(input.verification?.command, 'agentFixTask.verification.command', { max: 500 }),
+      expectedOutcome: requireString(input.verification?.expectedOutcome, 'agentFixTask.verification.expectedOutcome', { max: 700 }),
+      rerunVibesecur: requireString(input.verification?.rerunVibesecur, 'agentFixTask.verification.rerunVibesecur', { max: 700 }),
+    },
+    risk: {
+      severity: normalizeSeverity(input.risk?.severity),
+      priority: normalizeSeverity(input.risk?.priority),
+      category: requireString(input.risk?.category || input.category, 'agentFixTask.risk.category', { max: 80, pattern: UUIDISH }),
+    },
+    acceptedRiskRef: optionalString(input.acceptedRiskRef, 'agentFixTask.acceptedRiskRef', { max: 160, pattern: UUIDISH }),
+    blockedReason: optionalString(input.blockedReason, 'agentFixTask.blockedReason', { max: 500 }),
+    manualReason: optionalString(input.manualReason, 'agentFixTask.manualReason', { max: 500 }),
+    metadata: cloneSourceSafe(input.metadata || {}, 'agentFixTask.metadata'),
+  };
+  if (task.version !== AGENT_FIX_TASK_SCHEMA_VERSION) {
+    throw new Error(`agentFixTask.version must be ${AGENT_FIX_TASK_SCHEMA_VERSION}`);
+  }
+  if (task.findingIds.length === 0 && task.testPlanCandidateIds.length === 0) {
+    throw new Error('agentFixTask must reference findings or test-plan items');
+  }
+  if (task.artifactRefs.length === 0) throw new Error('agentFixTask.artifactRefs must include source artifact refs');
+  if (task.targetFiles.length === 0) throw new Error('agentFixTask.targetFiles must include at least one file or local target');
+  if (status === 'blocked' && !task.blockedReason) throw new Error('blocked Agent Fix Tasks require blockedReason');
+  if (status === 'manual' && !task.manualReason) throw new Error('manual Agent Fix Tasks require manualReason');
+  assertSourceSafePayload(task, 'agentFixTask');
+  return task;
+}
+
+export function validateAgentFixTaskArtifact(input = {}) {
+  assertSourceSafePayload(input, 'agentFixTaskArtifact');
+  const artifact = {
+    schemaVersion: requireString(input.schemaVersion, 'agentFixTask.schemaVersion', { max: 80, pattern: UUIDISH }),
+    generatedAt: requireIsoDate(input.generatedAt, 'agentFixTask.generatedAt'),
+    root: {
+      name: requireString(input.root?.name || 'project', 'agentFixTask.root.name', { max: 180 }),
+      pathHash: optionalString(input.root?.pathHash, 'agentFixTask.root.pathHash', { max: 64, pattern: SHA256 }),
+    },
+    sources: cloneSourceSafe(asObject(input.sources || {}, 'agentFixTask.sources'), 'agentFixTask.sources'),
+    summary: cloneSourceSafe(asObject(input.summary || {}, 'agentFixTask.summary'), 'agentFixTask.summary'),
+    templates: cloneSourceSafe(asObject(input.templates || {}, 'agentFixTask.templates'), 'agentFixTask.templates'),
+    tasks: asArray(input.tasks, 'agentFixTask.tasks').map(validateTask),
+    privacy: cloneSourceSafe(asObject(input.privacy || {}, 'agentFixTask.privacy'), 'agentFixTask.privacy'),
+  };
+  if (artifact.schemaVersion !== AGENT_FIX_TASK_SCHEMA_VERSION) {
+    throw new Error(`agentFixTask.schemaVersion must be ${AGENT_FIX_TASK_SCHEMA_VERSION}`);
+  }
+  assertSourceSafePayload(artifact, 'agentFixTaskArtifact');
+  return artifact;
+}
+
+export function hashAgentFixTaskArtifact(artifact) {
+  assertSourceSafePayload(artifact, 'agentFixTaskArtifact');
+  return sha256(stableStringify(validateAgentFixTaskArtifact(artifact)));
+}
+
+async function readLocalArtifact({ rootPath, ref, type }) {
+  if (!ref || ref.type !== type || ref.storage !== 'local' || !ref.uri) {
+    throw new Error(`Agent Fix Task generation requires a local ${type} artifact reference`);
+  }
+  const resolvedRoot = path.resolve(rootPath);
+  const target = path.resolve(resolvedRoot, ref.uri);
+  const relative = path.relative(resolvedRoot, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Agent Fix Task artifact ref for ${type} escapes the bound root`);
+  }
+  const raw = await fs.readFile(target, 'utf8');
+  if (!ref.hash) {
+    throw new Error(`Agent Fix Task generation requires ${type} artifact refs to include a hash`);
+  }
+  const actualHash = sha256(raw);
+  if (actualHash.toLowerCase() !== String(ref.hash).toLowerCase()) {
+    throw new Error(`Agent Fix Task ${type} artifact hash mismatch: expected ${ref.hash}, got ${actualHash}`);
+  }
+  const parsed = JSON.parse(raw);
+  assertSourceSafePayload(parsed, `agentFixTask.${type}`);
+  return parsed;
+}
+
+function findArtifactRef(state, type, preferredKeys = []) {
+  const artifacts = state?.artifacts || {};
+  for (const key of preferredKeys) {
+    if (artifacts[key]?.type === type) return artifacts[key];
+  }
+  return Object.values(artifacts).find((ref) => ref?.type === type) || null;
+}
+
+export async function writeAgentFixTaskArtifact({ rootPath, runId, artifact }) {
+  const safeArtifact = validateAgentFixTaskArtifact(artifact);
+  const safeRunId = validateRunIdSegment(runId, 'runId');
+  const relativeUri = `.vibesecur/deep-scans/${safeRunId}/${TASKS_FILE}`;
+  const target = path.join(path.resolve(rootPath), relativeUri);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const serialized = `${JSON.stringify(stableSort(safeArtifact), null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, serialized, 'utf8');
+  await fs.rename(tmp, target);
+  return {
+    uri: relativeUri,
+    hash: sha256(serialized),
+  };
+}
+
+export function ralphTaskStepper() {
+  return {
+    id: AGENT_FIX_TASK_STEPPER_ID,
+    version: AGENT_FIX_TASK_STEPPER_VERSION,
+    title: 'Ralph Agent Fix Task Stepper',
+    category: 'ralph_loop',
+    requiredInputs: ['security_test_plan', 'deterministic_scan'],
+    producedArtifacts: ['agent_fix_tasks'],
+    defaultTimeoutMs: 30000,
+    async run({ runId, config = {}, state = {}, tools = {} }) {
+      const rootPath = tools.rootPath || config.rootPath || '.';
+      const startedAt = nowIso();
+      const testPlanRef = findArtifactRef(state, 'security_test_plan', ['tests.plan']);
+      const deterministicScanRef = findArtifactRef(state, 'deterministic_scan', ['rules.scan']);
+      const securityTestPlan = await readLocalArtifact({
+        rootPath,
+        ref: testPlanRef,
+        type: 'security_test_plan',
+      });
+      const deterministicScan = await readLocalArtifact({
+        rootPath,
+        ref: deterministicScanRef,
+        type: 'deterministic_scan',
+      });
+      const artifact = buildAgentFixTaskArtifact({
+        securityTestPlan,
+        deterministicScan,
+        generatedAt: config.generatedAt || startedAt,
+        sourceRefs: {
+          securityTestPlan: testPlanRef.id,
+          deterministicScan: deterministicScanRef.id,
+        },
+      });
+      const contentHash = hashAgentFixTaskArtifact(artifact);
+      const written = await writeAgentFixTaskArtifact({ rootPath, runId, artifact });
+      const safeRunId = validateRunIdSegment(runId, 'runId');
+      const ref = createArtifactRef({
+        id: `artifact-${safeRunId}-agent-fix-tasks`,
+        type: 'agent_fix_tasks',
+        storage: 'local',
+        uri: written.uri,
+        hash: written.hash,
+        preview: 'Ralph Agent Fix Tasks: source-safe repair instructions, verification hints, and accepted-risk paths only.',
+        metadata: {
+          schemaVersion: AGENT_FIX_TASK_SCHEMA_VERSION,
+          contentHash,
+          generatedBy: AGENT_FIX_TASK_STEPPER_ID,
+          totalTasks: artifact.summary.totalTasks,
+          readyCount: artifact.summary.readyCount,
+          manualCount: artifact.summary.manualCount,
+          blockedCount: artifact.summary.blockedCount,
+        },
+      });
+
+      return {
+        stepperId: AGENT_FIX_TASK_STEPPER_ID,
+        version: AGENT_FIX_TASK_STEPPER_VERSION,
+        status: 'passed',
+        startedAt,
+        finishedAt: nowIso(),
+        evidence: [{
+          type: 'hash',
+          label: 'Agent Fix Task artifact hash',
+          hash: ref.hash,
+          preview: 'Source-safe Ralph task artifact written locally.',
+          summary: `${artifact.summary.totalTasks} task(s), ${artifact.summary.readyCount} ready for local agent work.`,
+          metadata: {
+            artifactId: ref.id,
+            contentHash,
+            securityTestPlanArtifactId: testPlanRef.id,
+            deterministicScanArtifactId: deterministicScanRef.id,
+          },
+        }],
+        findings: [],
+        artifacts: [ref],
+        receipts: [],
+        summary: `Ralph Agent Fix Tasks generated: ${artifact.summary.totalTasks} task(s), ${artifact.summary.readyCount} ready, ${artifact.summary.blockedCount} blocked, ${artifact.summary.manualCount} manual.`,
+        nextActions: ['Give Agent Fix Tasks to the local coding agent, then rerun Vibesecur for verification evidence.'],
+      };
+    },
+  };
+}