feat(requirements): ingest structured task and acceptance-criteria context (#672)

Author: kunaldhongade

docs/agent.md

@@ -22,10 +22,18 @@ not require a git diff, run configured commands, call models, or send telemetry.
 ```bash
 npx codedecay agent preflight \
   --task "Add a dashboard filter for reviewed uploads" \
+  --requirements .codedecay/requirements.yml \
   --format markdown
 ```
 
-The preflight report separates deterministic repo evidence from suggestions:
+The optional requirements artifact is repo-local JSON or YAML. It can provide
+`acceptanceCriteria`, `currentBehavior`, `expectedBehavior`, `affectedFlows`,
+`nonGoals`, `invariants`, `architectureConstraints`, and
+`unresolvedQuestions`. CodeDecay records the artifact as provenance and keeps
+requirement evidence separate from its own suggestions.
+
+The preflight report separates requirement evidence, deterministic repo
+evidence, and suggestions:
 
 - likely impacted areas from the task description
 - candidate files and route/API surfaces from repo paths
@@ -34,6 +42,12 @@ The preflight report separates deterministic repo evidence from suggestions:
 - configured checks listed as follow-up proof with `willRun=false`
 - proof plan and non-goals for the receiving agent
 
+Candidate files require domain-specific task terms or stronger repo evidence.
+Generic words such as `api` alone do not make every API-related file a
+candidate. When CodeDecay cannot ground the task in the repository, it returns
+low confidence, no candidate files, and an unresolved question instead of
+inventing scope.
+
 Treat preflight as a before-coding brief. After the agent edits code, run
 `codedecay redteam`, `codedecay agent`, and the relevant project checks to
 gather merge evidence.

docs/github-action.md

@@ -271,10 +271,16 @@ and fix tasks for a user-owned agent:
     base: ${{ github.event.pull_request.base.sha }}
     head: ${{ github.event.pull_request.head.sha }}
     cwd: .
+    task: Add a billing export API
+    requirements: .codedecay/requirements.yml
     format: markdown
     output: codedecay-agent.md
 ```
 
+`task` and `requirements` are explicit agent-mode inputs. The requirements path
+must resolve inside `cwd`; the action does not scrape the pull-request body,
+discover remote requirements, or call a model.
+
 Supported modes are `analyze`, `redteam`, `agent`, and `product`. The action
 does not expose arbitrary command passthrough. Product mode only forwards the
 explicit product verification inputs documented above and still relies on

docs/mcp.md

@@ -95,6 +95,21 @@ Example preflight input:
 ```json
 {
   "task": "Add a GET /api/users export endpoint",
+  "requirements": {
+    "acceptanceCriteria": [
+      {
+        "id": "AC-1",
+        "text": "Authorized users can export rows.",
+        "requiredProof": ["Call the real export route."]
+      }
+    ],
+    "affectedFlows": [
+      {
+        "name": "User export",
+        "kind": "api"
+      }
+    ]
+  },
   "format": "markdown"
 }
 ```

packages/agent/src/bundle.ts

@@ -45,6 +45,7 @@ export function createAgentTaskBundle(report: RedteamReport, options: CreateAgen
     generatedAt: report.generatedAt,
     purpose: agentProfile.description,
     agentProfile,
+    requirements: report.requirements,
     summary,
     prompt: createPortableAgentPrompt(summary, agentProfile),
     instructions: [...DEFAULT_INSTRUCTIONS],

packages/agent/src/preflight/render.ts

@@ -31,13 +31,56 @@ export function renderAgentPreflightMarkdown(report: AgentPreflightReport): stri
     `| Memory matches | ${report.summary.memoryMatches} |`,
     `| Design constraints | ${report.summary.designConstraints} |`,
     `| Configured checks listed | ${report.summary.configuredChecks} |`,
+    `| Acceptance criteria | ${report.summary.acceptanceCriteria} |`,
+    `| Unresolved questions | ${report.summary.unresolvedQuestions} |`,
+    `| Insufficient repo context | ${report.summary.insufficientContext ? "yes" : "no"} |`,
+    "",
+    "### Requirement Evidence",
+    "",
+    `Requirement confidence: ${report.requirements.confidence}`,
+    "",
+    "Provenance:"
+  ];
+
+  appendList(
+    lines,
+    report.requirements.sources.map((source) => {
+      const location = source.location ? ` at \`${source.location}\`` : "";
+      return `\`${source.id}\` (${source.kind}): ${source.label}${location}`;
+    })
+  );
+  lines.push("", "Acceptance criteria:");
+  appendList(
+    lines,
+    report.requirements.acceptanceCriteria.map((criterion) => {
+      const proof = criterion.requiredProof.length > 0
+        ? ` Required proof: ${criterion.requiredProof.join(" ")}`
+        : "";
+      return `${criterion.id}: ${criterion.text} [sources: ${criterion.sourceIds.join(", ")}].${proof}`;
+    })
+  );
+  lines.push("", "Affected flows:");
+  appendList(
+    lines,
+    report.requirements.affectedFlows.map(
+      (flow) => `${flow.kind}: ${flow.name} [sources: ${flow.sourceIds.join(", ")}]`
+    )
+  );
+  lines.push("", "Unresolved questions:");
+  appendList(
+    lines,
+    report.requirements.unresolvedQuestions.map(
+      (question) => `${question.text} [sources: ${question.sourceIds.join(", ")}]`
+    )
+  );
+  lines.push(
     "",
     "### Deterministic Repo Evidence",
     "",
     `No git diff required: ${report.deterministicEvidence.taskSignals.noDiffRequired ? "yes" : "no"}`,
     "",
     "Task signals:"
-  ];
+  );
 
   appendList(lines, report.deterministicEvidence.taskSignals.tokens.map((token) => `\`${token}\``), "- none");
   lines.push("", "Matched task keywords:");

packages/agent/src/preflight/report.ts

@@ -1,5 +1,10 @@
-import { CODEDECAY_VERSION, dedupeStrings, isTestFilePath } from "@submuxhq/codedecay-core";
-import type { DesignMatcher } from "@submuxhq/codedecay-core";
+import {
+  CODEDECAY_VERSION,
+  dedupeStrings,
+  isTestFilePath,
+  normalizeRequirementContext
+} from "@submuxhq/codedecay-core";
+import type { DesignMatcher, RequirementContext } from "@submuxhq/codedecay-core";
 import type { AgentSuggestedCheck } from "../types";
 import type {
   AgentPreflightArea,
@@ -45,18 +50,64 @@ const MAX_CANDIDATE_FILES = 24;
 const MAX_CANDIDATE_ROUTES = 16;
 const MAX_MEMORY_MATCHES_PER_SECTION = 8;
 const MAX_DESIGN_CONSTRAINTS = 16;
+const GENERIC_SCOPE_TOKENS = new Set([
+  "add",
+  "api",
+  "change",
+  "component",
+  "create",
+  "endpoint",
+  "fix",
+  "function",
+  "handler",
+  "implement",
+  "logic",
+  "module",
+  "page",
+  "refactor",
+  "request",
+  "response",
+  "route",
+  "service",
+  "source",
+  "test",
+  "tests",
+  "update",
+  "user"
+]);
 
 export function createAgentPreflightReport(options: CreateAgentPreflightReportOptions): AgentPreflightReport {
   const task = options.task.trim();
   if (!task) {
     throw new Error("agent preflight requires --task <description>.");
   }
 
-  const tokens = tokenize(task);
+  let requirements = normalizeRequirementContext({
+    task,
+    context: options.requirements,
+    source: options.requirementSource ?? {
+      id: "task-input",
+      kind: "task",
+      label: "Agent preflight task"
+    }
+  });
+  const tokens = tokenize(requirementSearchText(requirements));
+  const scopeTokens = tokenize(requirementScopeText(requirements));
   const keywordMatches = collectKeywordMatches(tokens);
   const likelyAreas = collectLikelyAreas(keywordMatches, tokens);
-  const candidateFiles = collectCandidateFiles(options.repoFiles, likelyAreas, tokens);
-  const candidateRoutes = collectCandidateRoutes(candidateFiles, options.config);
+  const candidateFiles = collectCandidateFiles(options.repoFiles, likelyAreas, scopeTokens);
+  if (candidateFiles.length === 0 && requirements.unresolvedQuestions.length === 0) {
+    requirements = {
+      ...requirements,
+      unresolvedQuestions: [
+        {
+          text: `Which repository path implements ${strongScopeTokens(scopeTokens).slice(0, 4).join(" / ") || "this requirement"}?`,
+          sourceIds: [requirements.task.sourceIds[0] ?? "task-input"]
+        }
+      ]
+    };
+  }
+  const candidateRoutes = collectCandidateRoutes(candidateFiles, options.config, scopeTokens);
   const configuredChecks = collectConfiguredChecks(options.config);
   const memory = collectMemoryEvidence(options.memory, likelyAreas, candidateFiles, candidateRoutes, tokens);
   const designConstraints = collectDesignConstraints(options.config, likelyAreas, candidateFiles, candidateRoutes, tokens);
@@ -88,14 +139,23 @@ export function createAgentPreflightReport(options: CreateAgentPreflightReportOp
     mode: "agent-preflight",
     generatedAt: options.generatedAt ?? new Date().toISOString(),
     task,
+    requirements,
     summary: {
-      confidence: confidenceFor(likelyAreas.length, candidateFiles.length, memoryCount(memory)),
+      confidence: confidenceFor(
+        likelyAreas.length,
+        candidateFiles.length,
+        memoryCount(memory),
+        requirements.confidence
+      ),
       likelyAreas: likelyAreas.length,
       candidateFiles: candidateFiles.length,
       candidateRoutes: candidateRoutes.length,
       memoryMatches: memoryCount(memory),
       designConstraints: designConstraints.length,
-      configuredChecks: configuredChecks.length
+      configuredChecks: configuredChecks.length,
+      acceptanceCriteria: requirements.acceptanceCriteria.length,
+      unresolvedQuestions: requirements.unresolvedQuestions.length,
+      insufficientContext: candidateFiles.length === 0
     },
     deterministicEvidence,
     suggestions,
@@ -107,7 +167,7 @@ export function createAgentPreflightReport(options: CreateAgentPreflightReportOp
       agentOutputTrusted: false
     },
     limits: [
-      "Preflight does not inspect a PR diff; file and route candidates are heuristic matches from the task description and repo paths.",
+      "Preflight does not inspect a PR diff; file and route candidates require domain-specific task terms or stronger repo evidence.",
       "Preflight does not execute configured commands, open browsers, call models, install tools, or send telemetry.",
       "Memory and docs are treated as review context, not trusted executable instruction.",
       "Use the proof plan as a starting point, then verify with real tests, configured checks, or product/runtime evidence."
@@ -208,7 +268,11 @@ function collectCandidateFiles(
     .filter(isPreflightRepoFile)
     .map((path) => scoreCandidateFile(path, likelyAreas, tokens))
     .filter((candidate): candidate is AgentPreflightCandidateFile & { score: number } => candidate !== undefined)
-    .sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
+    .sort((left, right) =>
+      right.score - left.score ||
+      Number(isTestFilePath(left.path)) - Number(isTestFilePath(right.path)) ||
+      left.path.localeCompare(right.path)
+    );
 
   return scored.slice(0, MAX_CANDIDATE_FILES).map(({ score: _score, ...candidate }) => candidate);
 }
@@ -229,8 +293,14 @@ function scoreCandidateFile(
 ): (AgentPreflightCandidateFile & { score: number }) | undefined {
   const normalizedPath = path.toLowerCase();
   const pathAreas = pathAreasFor(path);
+  const tokenHits = strongScopeTokens(tokens).filter((token) => normalizedPath.includes(token));
+  if (tokenHits.length === 0) {
+    return undefined;
+  }
+
   const reasons: string[] = [];
-  let score = 0;
+  let score = Math.min(tokenHits.length * 4, 16);
+  reasons.push(`Path includes requirement term(s): ${tokenHits.slice(0, 5).join(", ")}.`);
 
   for (const area of likelyAreas) {
     if (pathAreas.includes(area.kind)) {
@@ -239,12 +309,6 @@ function scoreCandidateFile(
     }
   }
 
-  const tokenHits = tokens.filter((token) => token.length >= 3 && normalizedPath.includes(token));
-  if (tokenHits.length > 0) {
-    score += Math.min(tokenHits.length * 2, 8);
-    reasons.push(`Path includes task term(s): ${tokenHits.slice(0, 5).join(", ")}.`);
-  }
-
   if (pathAreas.includes("test") && likelyAreas.some((area) => area.kind === "test")) {
     score += 4;
     reasons.push("Task asks for test or proof work and this is a test path.");
@@ -331,7 +395,8 @@ function pathAreasFor(path: string): AgentPreflightAreaKind[] {
 
 function collectCandidateRoutes(
   candidateFiles: AgentPreflightCandidateFile[],
-  config: AgentPreflightConfigInput | undefined
+  config: AgentPreflightConfigInput | undefined,
+  tokens: string[]
 ): AgentPreflightCandidateRoute[] {
   const routes: AgentPreflightCandidateRoute[] = [];
 
@@ -344,12 +409,20 @@ function collectCandidateRoutes(
 
   for (const [targetId, target] of Object.entries(config?.productTesting?.targets ?? {})) {
     for (const endpoint of target?.apiEndpoints ?? []) {
+      const endpointText = `${endpoint.id ?? ""} ${endpoint.path}`.toLowerCase();
+      const matchedTerms = strongScopeTokens(tokens).filter((token) => endpointText.includes(token));
+      if (matchedTerms.length === 0) {
+        continue;
+      }
       routes.push({
         route: endpoint.path,
         kind: "product-api",
         methods: [endpoint.method.toUpperCase()],
         files: [],
-        reasons: [`Configured product target \`${targetId}\` includes endpoint \`${endpoint.id ?? endpoint.path}\`.`]
+        reasons: [
+          `Configured product target \`${targetId}\` includes endpoint \`${endpoint.id ?? endpoint.path}\`.`,
+          `Endpoint includes requirement term(s): ${matchedTerms.slice(0, 5).join(", ")}.`
+        ]
       });
     }
   }
@@ -799,8 +872,16 @@ function tokenize(value: string): string[] {
   ).slice(0, MAX_TASK_TOKENS);
 }
 
-function confidenceFor(areaCount: number, candidateFileCount: number, memoryMatches: number): AgentPreflightConfidence {
-  if (areaCount >= 2 && candidateFileCount >= 2) {
+function confidenceFor(
+  areaCount: number,
+  candidateFileCount: number,
+  memoryMatches: number,
+  requirementConfidence: AgentPreflightConfidence
+): AgentPreflightConfidence {
+  if (
+    (requirementConfidence === "high" && candidateFileCount >= 1) ||
+    (areaCount >= 2 && candidateFileCount >= 2)
+  ) {
     return "high";
   }
 
@@ -811,6 +892,30 @@ function confidenceFor(areaCount: number, candidateFileCount: number, memoryMatc
   return "low";
 }
 
+function requirementSearchText(requirements: RequirementContext): string {
+  return [
+    requirements.task.text,
+    ...requirements.currentBehavior.map((entry) => entry.text),
+    ...requirements.expectedBehavior.map((entry) => entry.text),
+    ...requirements.acceptanceCriteria.flatMap((entry) => [entry.text, ...entry.requiredProof]),
+    ...requirements.affectedFlows.flatMap((flow) => [flow.name, flow.description ?? ""]),
+    ...requirements.invariants.map((entry) => entry.text),
+    ...requirements.architectureConstraints.map((entry) => entry.text)
+  ].join(" ");
+}
+
+function requirementScopeText(requirements: RequirementContext): string {
+  return [
+    requirements.task.text,
+    ...requirements.affectedFlows.flatMap((flow) => [flow.name, flow.description ?? ""]),
+    ...requirements.architectureConstraints.map((entry) => entry.text)
+  ].join(" ");
+}
+
+function strongScopeTokens(tokens: string[]): string[] {
+  return tokens.filter((token) => token.length >= 3 && !GENERIC_SCOPE_TOKENS.has(token));
+}
+
 function confidenceRank(confidence: AgentPreflightConfidence): number {
   if (confidence === "high") {
     return 3;