@zhixuan92/multi-model-agent-core 4.0.5 → 4.1.0

package/dist/tools/execute-plan/tool-config.js

@@ -5,6 +5,7 @@ import { executePlanHeadlineTemplate } from '../../reporting/headline-templates/
 import { executePlanReportSchema } from '../../reporting/report-parser-slots/execute-plan-report.js';
 import { DEFAULT_TASK_TIMEOUT_MS } from '../../config/schema.js';
 import { REVIEWER_AWARENESS_AP } from '../../review/templates/finding-criteria.js';
+import { EXECUTE_PLAN_PURPOSE_ORIENTATION, EXECUTE_PLAN_SCOPE_RULE, EXECUTE_PLAN_FAILURE_MODES, PLAN_FIDELITY_REMINDER, } from './implementer-criteria.js';
 export const executePlanInputSchema = z.object({
     filePaths: z.array(z.string()).length(1, { message: "execute_plan requires exactly one plan filePath" }),
     taskDescriptors: z.array(z.string()).min(1),
@@ -29,9 +30,22 @@ export function registerExecutePlan(registry) {
 /**
  * Build a compact worker prompt for one plan task. Extracted from the legacy
  * executor — just the section matched by the slot, not the full plan file.
+ *
+ * The prompt is structured top-down: orientation (why this exists) →
+ * task descriptor → matched plan section → file paths → fidelity rules
+ * (RESTORED in 4.1.0; the older `compileExecutePlan` had them, the
+ * slot-style refactor that became the canonical path dropped them) →
+ * failure-mode taxonomy → reviewer awareness. Without the orientation
+ * + fidelity blocks, workers default to "implement the goal" and treat
+ * the plan as a starting suggestion rather than the contract.
  */
 function buildExecutePlanPrompt(filePaths, task, taskSection) {
     const parts = [
+        // Orientation goes FIRST — fidelity-first framing before the
+        // task descriptor, so the worker reads the section through the
+        // execution lens instead of the "improve it" lens.
+        EXECUTE_PLAN_PURPOSE_ORIENTATION,
+        '',
         `Execute this task from the plan: "${task}"`,
         '',
     ];
@@ -39,10 +53,10 @@ function buildExecutePlanPrompt(filePaths, task, taskSection) {
         parts.push('Relevant plan section:', '', '---', taskSection.trim(), '---', '');
     }
     else {
-        parts.push('No unique plan section matched that task heading. The full plan file is at:', ...filePaths.map((p) => `  - ${p}`), 'Read the plan file(s) yourself to find the task.', '');
+        parts.push('No unique plan section matched that task heading. The full plan file is at:', ...filePaths.map((p) => `  - ${p}`), 'Read the plan file(s) yourself to find the task. If still no unique match, report that and stop — do not implement anything.', '');
     }
-    parts.push('Plan files for reference (read on demand if you need adjacent context):', ...filePaths.map((p) => `  - ${p}`), '');
-    parts.push('Implement the task fully. Follow any acceptance criteria, file paths, and', 'constraints in the plan section above. If you cannot find or understand', 'the task, report that explicitly and do not implement anything.', '', 
+    parts.push('Plan files for reference (read on demand if you need adjacent context — but do not enlarge scope into other tasks):', ...filePaths.map((p) => `  - ${p}`), '');
+    parts.push('Implement the task fully. Follow any acceptance criteria, file paths, and', 'constraints in the plan section above. If you cannot find or understand', 'the task, report that explicitly and do not implement anything.', '', EXECUTE_PLAN_SCOPE_RULE, '', EXECUTE_PLAN_FAILURE_MODES, '', PLAN_FIDELITY_REMINDER, '', 
     // Tool sweep #12: share spec + quality reviewer rubric so the
     // worker self-aligns on what each reviewer will judge against.
     REVIEWER_AWARENESS_AP);

package/dist/tools/execute-plan/tool-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-config.js","sourceRoot":"","sources":["../../../src/tools/execute-plan/tool-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-config.js","sourceRoot":"","sources":["../../../src/tools/execute-plan/tool-config.ts"],"names":[],"mappings":"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"}

package/dist/tools/investigate/implementer-criteria.d.ts

@@ -1,17 +1,60 @@
 /**
  * Investigate-specific implementer criteria.
  *
+ * INVESTIGATE'S PURPOSE — read this before adding categories.
+ * mma-investigate answers a question about the codebase. The caller is
+ * about to ACT on your answer — write code, edit a file, choose between
+ * approaches. The success criterion is:
+ *
+ *   "If the caller acts on this answer literally — opens the cited
+ *    files, follows the cited chain, takes the synthesis at face value
+ *    — will they end up with correct code?"
+ *
+ * That criterion is what makes a finding load-bearing. A wrong file
+ * path, a stale quote, a hand-waved synthesis, an overstated confidence
+ * — all become bugs the caller writes. The investigate-equivalent of
+ * "fix is unimplementable" is "the answer points at a file that does
+ * not contain what you said it contained."
+ *
  * Investigate answers a question about the codebase. Findings can be
  * code-level citations, project-level synthesis, or NEGATIVE results
- * ("searched X, not found"). The shared evidence rule that demands a
- * code quote for every finding wrongly suppresses negative results,
- * which are often the most useful answer to "is X still used?" or
- * "where does Y live?".
+ * ("searched X, not found"). Negative findings are legitimate answers
+ * to "is X still used?" or "where does Y live?" and must not be
+ * suppressed.
  *
  * Note: investigate does NOT use SEVERITY_LADDER — its findings are
- * citations and synthesis, not severity-rated issues.
+ * citations and synthesis, not severity-rated issues. Confidence is the
+ * calibration dial, not severity.
+ */
+/**
+ * The orientation block. Goes at the TOP of every investigate prompt.
+ *
+ * Without an explicit purpose statement, workers default to "give a
+ * plausible-sounding answer" — which produces hallucinated citations
+ * and overstated confidence. With this orientation, every claim is
+ * ground-truthed against the file system.
  */
+export declare const INVESTIGATE_PURPOSE_ORIENTATION: string;
 export declare const EVIDENCE_RULE_INVESTIGATE: string;
 export declare const SCOPE_RULE_INVESTIGATE: string;
+/**
+ * The failure-mode taxonomy for investigations.
+ *
+ * Without this block, workers tend to give plausible-sounding answers
+ * with shaky citations. The 8 categories below are the specific ways
+ * an investigation answer becomes a bug when the caller acts on it.
+ */
+export declare const INVESTIGATE_FAILURE_MODES: string;
+/**
+ * Confidence-discipline reminder.
+ *
+ * The shared SEVERITY_LADDER does not apply to investigate (findings
+ * are citations, not severity-rated). Instead, confidence is the
+ * calibration dial. The common failure mode is over-confidence —
+ * stating "high confidence" because the worker sounds certain,
+ * not because the evidence is strong. This block tells the worker
+ * confidence reflects evidence strength only.
+ */
+export declare const CONFIDENCE_REMINDER_INVESTIGATE: string;
 export declare const ANNOTATOR_AWARENESS_INVESTIGATE: string;
 //# sourceMappingURL=implementer-criteria.d.ts.map

package/dist/tools/investigate/implementer-criteria.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"implementer-criteria.d.ts","sourceRoot":"","sources":["../../../src/tools/investigate/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,yBAAyB,QAK1B,CAAC;AAEb,eAAO,MAAM,sBAAsB,QAIvB,CAAC;AAEb,eAAO,MAAM,+BAA+B,QAOhC,CAAC"}
+{"version":3,"file":"implementer-criteria.d.ts","sourceRoot":"","sources":["../../../src/tools/investigate/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,QAahC,CAAC;AAEb,eAAO,MAAM,yBAAyB,QAO1B,CAAC;AAEb,eAAO,MAAM,sBAAsB,QAKvB,CAAC;AAEb;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,QAiB1B,CAAC;AAEb;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,QAYhC,CAAC;AAEb,eAAO,MAAM,+BAA+B,QAShC,CAAC"}

package/dist/tools/investigate/implementer-criteria.js

@@ -1,33 +1,123 @@
 /**
  * Investigate-specific implementer criteria.
  *
+ * INVESTIGATE'S PURPOSE — read this before adding categories.
+ * mma-investigate answers a question about the codebase. The caller is
+ * about to ACT on your answer — write code, edit a file, choose between
+ * approaches. The success criterion is:
+ *
+ *   "If the caller acts on this answer literally — opens the cited
+ *    files, follows the cited chain, takes the synthesis at face value
+ *    — will they end up with correct code?"
+ *
+ * That criterion is what makes a finding load-bearing. A wrong file
+ * path, a stale quote, a hand-waved synthesis, an overstated confidence
+ * — all become bugs the caller writes. The investigate-equivalent of
+ * "fix is unimplementable" is "the answer points at a file that does
+ * not contain what you said it contained."
+ *
  * Investigate answers a question about the codebase. Findings can be
  * code-level citations, project-level synthesis, or NEGATIVE results
- * ("searched X, not found"). The shared evidence rule that demands a
- * code quote for every finding wrongly suppresses negative results,
- * which are often the most useful answer to "is X still used?" or
- * "where does Y live?".
+ * ("searched X, not found"). Negative findings are legitimate answers
+ * to "is X still used?" or "where does Y live?" and must not be
+ * suppressed.
  *
  * Note: investigate does NOT use SEVERITY_LADDER — its findings are
- * citations and synthesis, not severity-rated issues.
+ * citations and synthesis, not severity-rated issues. Confidence is the
+ * calibration dial, not severity.
+ */
+/**
+ * The orientation block. Goes at the TOP of every investigate prompt.
+ *
+ * Without an explicit purpose statement, workers default to "give a
+ * plausible-sounding answer" — which produces hallucinated citations
+ * and overstated confidence. With this orientation, every claim is
+ * ground-truthed against the file system.
  */
+export const INVESTIGATE_PURPOSE_ORIENTATION = [
+    'Why this investigation exists:',
+    'mma-investigate is the answer-and-act loop. The caller will use your answer to make code edits — open the cited files, take the synthesis at face value, choose an approach based on your confidence rating. A wrong file path becomes a bug; a stale quote becomes a wrong edit; an overstated confidence becomes a misallocated effort.',
+    '',
+    'For your output to clear that bar, every load-bearing claim must answer:',
+    '- Where exactly is this — file:line for present things, or "searched <pattern> in <path>, not found" for absent things?',
+    '- Did I read the file just now, or am I reasoning from training data? (only the former counts as evidence)',
+    '- For synthesis claims (e.g. "X is used by Y via Z"), is each link in the chain backed by a file:line?',
+    '- Is my confidence calibrated to evidence strength, or to how certain I sound?',
+    '',
+    'A claim without a citation is a guess. A citation that does not match the file currently on disk is a hallucination. A "high confidence" verdict on a synthesis with one weak link is overstatement.',
+    '',
+    'The completion test: would a caller who reads only your investigation report and the named files end up with the same answer if they re-investigated themselves — or would they find the cited file does not say what you said it said?',
+].join('\n');
 export const EVIDENCE_RULE_INVESTIGATE = [
     'Evidence grounding (REQUIRED for every citation):',
-    '- For present things: `file:line` (or `file:line-line` for spans) plus a quote or summary of what you found.',
+    '- For present things: `file:line` (or `file:line-line` for spans) plus a quote or summary of what you found. The cited line MUST contain the cited content as of your read — do NOT cite from training-data memory.',
     '- For absent things: explicit `searched <pattern> in <path>, no matches` — negative findings are legitimate answers and should be emitted, not suppressed.',
-    '- For synthesis findings (e.g. "X uses Y indirectly via Z"): cite each link in the chain by `file:line`.',
+    '- For synthesis findings (e.g. "X uses Y indirectly via Z"): cite each link in the chain by `file:line`. A synthesis claim with even one un-cited link is a hand-wave.',
+    '- For project-level claims that no single file demonstrates (e.g. "the codebase has no shared error type"): write the negative ("searched the repo for `class.*Error` declarations: only X, Y, Z found, none shared") rather than asserting the absence without evidence.',
+    '- If you have not read a file, do NOT cite from it. Reasoning-from-training-data is the most common hallucination source — refuse it explicitly.',
 ].join('\n');
 export const SCOPE_RULE_INVESTIGATE = [
     'Scope:',
     '- Wherever the question leads. The question may not name files; you choose where to look.',
-    '- Out of scope: drift into issues unrelated to the question; opportunistic code review of the code you are investigating (raise that separately, not as an investigation finding).',
+    '- If the question is broad (e.g. "how does X work overall?"), break it into sub-questions and answer each with citations rather than producing one un-grounded narrative.',
+    '- Out of scope: drift into issues unrelated to the question; opportunistic code review of the code you are investigating (raise that separately, not as an investigation finding); fixes / suggestions / improvements (this is a read-only Q&A — propose nothing).',
+].join('\n');
+/**
+ * The failure-mode taxonomy for investigations.
+ *
+ * Without this block, workers tend to give plausible-sounding answers
+ * with shaky citations. The 8 categories below are the specific ways
+ * an investigation answer becomes a bug when the caller acts on it.
+ */
+export const INVESTIGATE_FAILURE_MODES = [
+    'Patterns to consciously check for. Apply on EVERY investigation:',
+    '',
+    '1. WRONG FILE — a close-named file in a different package/module is cited instead of the actual one (e.g. `src/foo/utils.ts` when the real answer is in `src/bar/utils.ts`). When a name is ambiguous, list all matches and identify which one the question is about.',
+    '2. STALE QUOTE — the cited content was at the cited line in your training data but the file has been refactored. Always re-read before quoting; do NOT quote from memory. If the file does not currently contain the quoted content, the citation is invalid.',
+    '3. HALLUCINATED CITATION — a `file:line` that does not exist on disk. Verify each citation by actually reading the file at the cited line range. Hallucinated citations are the most caller-actionable failure mode — the caller opens the file and finds nothing there.',
+    '4. CONFIDENCE OVERSTATEMENT — claiming "high confidence" when the chain has gaps, when there are multiple plausible answers, or when the citation is partial. Confidence reflects EVIDENCE strength, not how certain you sound.',
+    '5. CITATION GAP — a load-bearing claim made without a `file:line`. Synthesis findings without per-link citations are hand-waves. The fix: add the citation, OR downgrade the claim to "I infer X from Y, Z; verify by re-reading <file>".',
+    '6. QUESTION SHIFT — answered an adjacent question rather than the one asked. Re-read the question literally before writing the Summary. If the asked question is "where is X declared?" do not answer "where is X used?" without saying so.',
+    '7. SYNTHESIS WITHOUT GROUNDING — combined facts into a conclusion that no single citation supports. Either: (a) cite each link explicitly, or (b) mark the conclusion as inference and lower confidence.',
+    '8. ASSUMED-CURRENT-STATE — wrote answer from training-data assumption ("normally Foo is implemented this way") instead of the file currently on disk. The codebase may have diverged. Always read; never assume.',
+    '',
+    'Confidence calibration for investigations:',
+    '- high: every load-bearing claim has a file:line citation you read this session; the citation matches the question precisely; no plausible alternative answers were found in your search.',
+    '- medium: most claims are cited; one or two links rely on inference from cited facts; alternative answers exist but were ruled out with evidence.',
+    '- low: partial answer; significant gaps in the citation chain; the file system has answers you have not searched; or the question is broader than the time spent investigating.',
+    '- Use `(none)` for Citations and `low` for Confidence ONLY when the question is genuinely project-level and no code evidence applies. Most "I think it works this way" answers should be `low` confidence with a partial citation, not zero citations.',
+].join('\n');
+/**
+ * Confidence-discipline reminder.
+ *
+ * The shared SEVERITY_LADDER does not apply to investigate (findings
+ * are citations, not severity-rated). Instead, confidence is the
+ * calibration dial. The common failure mode is over-confidence —
+ * stating "high confidence" because the worker sounds certain,
+ * not because the evidence is strong. This block tells the worker
+ * confidence reflects evidence strength only.
+ */
+export const CONFIDENCE_REMINDER_INVESTIGATE = [
+    'Confidence-discipline reminder:',
+    '- Confidence reflects EVIDENCE STRENGTH (how completely the citation chain supports the answer), not ASSERTION STRENGTH (how certain you sound).',
+    '- For each load-bearing claim, ask: "if the caller followed this citation and re-read the file themselves, would they reach the same conclusion?" If yes for every claim → `high`. If yes for most but inference fills the gaps → `medium`. If significant gaps remain → `low`.',
+    '- Do NOT use confidence to communicate certainty about the question being answered. Use it to communicate certainty that your answer is CORRECT given your evidence.',
+    '- A short investigation that found a clean answer can legitimately be `high`. A long investigation that found a partial answer is `medium` or `low`, no matter how thorough it felt.',
+    '',
+    'Citation-chain walk (REQUIRED on every load-bearing claim):',
+    '- Before writing the Summary, list every claim that drives the answer. For each, ask: "do I have a file:line for this, and did I read the file in this session?"',
+    '- If the answer to either is no, the claim is inference. Either downgrade Confidence, or add the citation by reading the file now.',
+    '- Worked example. Question: "how does the audit prompt assemble the failure-mode taxonomy?" Naive answer: "The audit tool config imports DOC_AUDIT_FAILURE_MODES from implementer-criteria.ts and joins it into the prompt — confidence: high." Better answer: cite the import line (e.g. `tool-config.ts:14 — import { DOC_AUDIT_FAILURE_MODES, ... }`) AND the consumer line where it is joined into the prompt (e.g. `tool-config.ts:152 — DOC_AUDIT_FAILURE_MODES,` inside the FINDING_FORMAT_INSTRUCTIONS array). Two citations, both verified by reading the file → high confidence is now backed. The naive version asserts the same conclusion but with no actual file:line; if the file has been refactored, the answer is silently wrong.',
+    '- Most workers miss findings of this shape on first pass because the answer "feels right". The citation-chain walk forces the file-system check.',
 ].join('\n');
 export const ANNOTATOR_AWARENESS_INVESTIGATE = [
     'After your output, an annotator validates each finding against this investigate rubric:',
-    '- Does each finding answer some part of the question?',
-    '- Are present-thing citations to real `file:line` from files you actually read?',
-    '- Are negative findings explicit ("searched X, not found") rather than silent omissions?',
-    '- Does the confidence reflect the strength of evidence?',
-    'Self-check before emitting. Findings that fail any check are downgraded or dropped.',
+    '- Does each citation answer some part of the question (not an adjacent question)?',
+    '- Are present-thing citations to real `file:line` from files actually read this session?',
+    '- Are negative findings explicit ("searched X in Y, not found") rather than silent omissions?',
+    '- For synthesis claims, is each link in the chain cited?',
+    '- Does the confidence reflect evidence strength (not assertion strength)?',
+    '- Is the answer to the asked question, not a shifted version of it?',
+    'Self-check before emitting. Findings that fail any check are downgraded or dropped — but negative findings ("searched, not found") and inference-with-citations ("I infer X from Y:42, Z:18") are FULLY VALID. Do NOT downgrade negative findings for lacking a code quote, and do NOT downgrade inference-with-citations as "speculation" if the cited links are real.',
 ].join('\n');
 //# sourceMappingURL=implementer-criteria.js.map

package/dist/tools/investigate/implementer-criteria.js.map

@@ -1 +1 @@
-{"version":3,"file":"implementer-criteria.js","sourceRoot":"","sources":["../../../src/tools/investigate/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,mDAAmD;IACnD,8GAA8G;IAC9G,4JAA4J;IAC5J,0GAA0G;CAC3G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,QAAQ;IACR,2FAA2F;IAC3F,oLAAoL;CACrL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,yFAAyF;IACzF,uDAAuD;IACvD,iFAAiF;IACjF,0FAA0F;IAC1F,yDAAyD;IACzD,qFAAqF;CACtF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"implementer-criteria.js","sourceRoot":"","sources":["../../../src/tools/investigate/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,gCAAgC;IAChC,2UAA2U;IAC3U,EAAE;IACF,0EAA0E;IAC1E,yHAAyH;IACzH,4GAA4G;IAC5G,wGAAwG;IACxG,gFAAgF;IAChF,EAAE;IACF,sMAAsM;IACtM,EAAE;IACF,yOAAyO;CAC1O,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,mDAAmD;IACnD,qNAAqN;IACrN,4JAA4J;IAC5J,wKAAwK;IACxK,2QAA2Q;IAC3Q,kJAAkJ;CACnJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,QAAQ;IACR,2FAA2F;IAC3F,2KAA2K;IAC3K,oQAAoQ;CACrQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,kEAAkE;IAClE,EAAE;IACF,uQAAuQ;IACvQ,+PAA+P;IAC/P,0QAA0Q;IAC1Q,iOAAiO;IACjO,2OAA2O;IAC3O,6OAA6O;IAC7O,0MAA0M;IAC1M,kNAAkN;IAClN,EAAE;IACF,4CAA4C;IAC5C,2LAA2L;IAC3L,mJAAmJ;IACnJ,iLAAiL;IACjL,wPAAwP;CACzP,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,iCAAiC;IACjC,kJAAkJ;IAClJ,iRAAiR;IACjR,sKAAsK;IACtK,sLAAsL;IACtL,EAAE;IACF,6DAA6D;IAC7D,kKAAkK;IAClK,oIAAoI;IACpI,qtBAAqtB;IACrtB,kJAAkJ;CACnJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,yFAAyF;IACzF,mFAAmF;IACnF,0FAA0F;IAC1F,+FAA+F;IAC/F,0DAA0D;IAC1D,2EAA2E;IAC3E,qEAAqE;IACrE,yWAAyW;CAC1W,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/dist/tools/investigate/tool-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-config.d.ts","sourceRoot":"","sources":["../../../src/tools/investigate/tool-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAGvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2DAA2D,CAAC;AAUzG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAYvE;AAKD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAyB,SAAQ,KAAK;IACrD,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;IAC9C,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,0BAA0B,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;CAC7B;AAqDD,eAAO,MAAM,UAAU,EAAE,UAAU,CAAC,wBAAwB,EAAE,gBAAgB,EAAE,uBAAuB,CA2DtG,CAAC"}
+{"version":3,"file":"tool-config.d.ts","sourceRoot":"","sources":["../../../src/tools/investigate/tool-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAGvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2DAA2D,CAAC;AAazG,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAYvE;AAKD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAyB,SAAQ,KAAK;IACrD,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;IAC9C,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,0BAA0B,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;CAC7B;AAkED,eAAO,MAAM,UAAU,EAAE,UAAU,CAAC,wBAAwB,EAAE,gBAAgB,EAAE,uBAAuB,CA2DtG,CAAC"}

package/dist/tools/investigate/tool-config.js

@@ -4,7 +4,7 @@ import { investigateReportSchema } from '../../reporting/report-parser-slots/inv
 import { investigateHeadlineTemplate } from '../../reporting/headline-templates/investigate.js';
 import { deriveInvestigateWorkerStatus } from '../../reporting/derive-investigate-status.js';
 import { DEFAULT_TASK_TIMEOUT_MS } from '../../config/schema.js';
-import { EVIDENCE_RULE_INVESTIGATE, SCOPE_RULE_INVESTIGATE, ANNOTATOR_AWARENESS_INVESTIGATE, } from './implementer-criteria.js';
+import { INVESTIGATE_PURPOSE_ORIENTATION, EVIDENCE_RULE_INVESTIGATE, SCOPE_RULE_INVESTIGATE, ANNOTATOR_AWARENESS_INVESTIGATE, INVESTIGATE_FAILURE_MODES, CONFIDENCE_REMINDER_INVESTIGATE, } from './implementer-criteria.js';
 export function registerInvestigate(registry) {
     registry.register({
         routeName: 'investigate',
@@ -20,6 +20,12 @@ export function registerInvestigate(registry) {
 }
 function compilePrompt(input) {
     const promptParts = [];
+    // Orientation goes FIRST — the worker needs to know why this
+    // investigation exists (caller will act on this answer; wrong file
+    // path becomes a bug) before reading the format spec / taxonomy.
+    // Without it, workers default to plausible-sounding answers with
+    // shaky citations.
+    promptParts.push(INVESTIGATE_PURPOSE_ORIENTATION);
     promptParts.push([
         'Produce an investigation report in this EXACT structured format. The deterministic',
         'parser extracts citations, confidence, and unresolved items by section — do NOT emit',
@@ -29,14 +35,15 @@ function compilePrompt(input) {
         'One paragraph stating the answer to the question, in plain prose.',
         '',
         '## Citations',
-        'One bullet per evidence item, in this exact format:',
-        '`- file/path.ts:LINE — claim` (em-dash, OR `--` is also accepted)',
-        'Use a `LINE-LINE` range when an evidence span covers multiple lines.',
-        'If the question is fully project-level (no code evidence applies), write `(none)`',
-        'on its own line — but only when Confidence is `low`.',
+        'One bullet per evidence item. Each bullet must start with `-` and contain `<file>:<LINE> — <claim>` (em-dash, OR `--` is also accepted). The parser tolerates an optional pair of backticks wrapping the path:line portion (e.g. `` `src/foo.ts:42` — claim ``) but the canonical form is without backticks.',
+        'Examples (use either form):',
+        '  - src/foo.ts:42 — claim about line 42',
+        '  - src/foo.ts:42-58 — claim about a span',
+        'Use a LINE-LINE range when an evidence span covers multiple lines.',
+        'If the question is fully project-level (no code evidence applies), write `(none)` on its own line — but only when Confidence is `low`.',
         '',
         '## Confidence',
-        'One of `high`, `medium`, or `low`, optionally followed by ` — <one-line rationale>`.',
+        'One of high, medium, or low, optionally followed by ` — <one-line rationale>`. Do NOT wrap the level in backticks; emit it as plain text.',
         '',
         '## Unresolved',
         'Optional bullets describing follow-up questions; write `(none)` if there are none.',
@@ -59,7 +66,7 @@ function compilePrompt(input) {
     // but evidence-grounding + scope-discipline + annotator-awareness
     // apply just as much. Workers that cite hallucinated lines or
     // speculate about unread files now have the rubric inline.
-    promptParts.push(EVIDENCE_RULE_INVESTIGATE, SCOPE_RULE_INVESTIGATE, ANNOTATOR_AWARENESS_INVESTIGATE);
+    promptParts.push(INVESTIGATE_FAILURE_MODES, CONFIDENCE_REMINDER_INVESTIGATE, EVIDENCE_RULE_INVESTIGATE, SCOPE_RULE_INVESTIGATE, ANNOTATOR_AWARENESS_INVESTIGATE);
     return promptParts.join('\n\n');
 }
 export const toolConfig = {

package/dist/tools/investigate/tool-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-config.js","sourceRoot":"","sources":["../../../src/tools/investigate/tool-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-config.js","sourceRoot":"","sources":["../../../src/tools/investigate/tool-config.ts"],"names":[],"mappings":"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"}

package/dist/tools/review/implementer-criteria.d.ts

@@ -1,11 +1,57 @@
 /**
  * Review-specific implementer criteria.
  *
+ * REVIEW'S PURPOSE — read this before adding categories.
+ * mma-review is the pre-merge gate. The maintainer accepting your verdict
+ * will NOT re-investigate before pressing merge — your output is treated
+ * as authoritative. The success criterion is:
+ *
+ *   "After fixes, will the merge be safe, correct, and maintainable —
+ *    such that a regression is unlikely to ship?"
+ *
+ * That criterion makes a finding load-bearing. A nit that doesn't change
+ * whether the merge is safe is low-priority no matter how clean the
+ * suggested rewrite reads. A cross-file ripple that breaks a caller
+ * not in the diff is the audit-equivalent of an unimplementable fix —
+ * load-bearing even though the named file looks fine in isolation.
+ *
  * Review examines source code in named files against a focus area
  * (security/correctness/performance/style). Findings should be
- * line-quotable — that's the natural shape of code defects.
+ * line-quotable — that's the natural shape of code defects — but
+ * cross-file findings backed by call-site references are also valid.
+ */
+/**
+ * The orientation block. Goes at the TOP of every review prompt.
+ *
+ * This is the load-bearing addition. Without an explicit purpose
+ * statement, workers default to "find issues in this file" — which
+ * produces line-by-line proofreading and misses the cross-file rippe,
+ * test-gap, and implicit-contract findings that actually block merges.
  */
+export declare const REVIEW_PURPOSE_ORIENTATION: string;
 export declare const EVIDENCE_RULE_REVIEW: string;
 export declare const SCOPE_RULE_REVIEW: string;
+/**
+ * The failure-mode taxonomy for code reviews.
+ *
+ * Without this block, workers default to line-by-line proofreading of
+ * the named file and miss cross-file ripples, test gaps, and
+ * implicit-contract regressions — the findings that actually block
+ * merges. The 10 categories below are what a careful maintainer would
+ * scan for before pressing merge.
+ */
+export declare const CODE_REVIEW_FAILURE_MODES: string;
+/**
+ * Counter-balance to the SEVERITY_LADDER's anti-inflation hint.
+ *
+ * The shared severity ladder ends with "Workers commonly inflate —
+ * resist the urge." That bias is correct in the limit (no, the missing
+ * comma is not critical) but produces UNDER-finding when combined with
+ * a thin per-tool rubric. For code review specifically, the typical
+ * failure is missing the cross-file ripple or test gap because the
+ * worker only looked at the diff in the named file. This block tells
+ * the worker that under-finding is the more common review failure.
+ */
+export declare const THOROUGHNESS_REMINDER_REVIEW: string;
 export declare const ANNOTATOR_AWARENESS_REVIEW: string;
 //# sourceMappingURL=implementer-criteria.d.ts.map

package/dist/tools/review/implementer-criteria.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"implementer-criteria.d.ts","sourceRoot":"","sources":["../../../src/tools/review/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,oBAAoB,QAKrB,CAAC;AAEb,eAAO,MAAM,iBAAiB,QAIlB,CAAC;AAEb,eAAO,MAAM,0BAA0B,QAO3B,CAAC"}
+{"version":3,"file":"implementer-criteria.d.ts","sourceRoot":"","sources":["../../../src/tools/review/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,QAmB3B,CAAC;AAEb,eAAO,MAAM,oBAAoB,QAQrB,CAAC;AAEb,eAAO,MAAM,iBAAiB,QAOlB,CAAC;AAEb;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAmB1B,CAAC;AAEb;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,QAW7B,CAAC;AAEb,eAAO,MAAM,0BAA0B,QAO3B,CAAC"}

package/dist/tools/review/implementer-criteria.js

@@ -1,27 +1,128 @@
 /**
  * Review-specific implementer criteria.
  *
+ * REVIEW'S PURPOSE — read this before adding categories.
+ * mma-review is the pre-merge gate. The maintainer accepting your verdict
+ * will NOT re-investigate before pressing merge — your output is treated
+ * as authoritative. The success criterion is:
+ *
+ *   "After fixes, will the merge be safe, correct, and maintainable —
+ *    such that a regression is unlikely to ship?"
+ *
+ * That criterion makes a finding load-bearing. A nit that doesn't change
+ * whether the merge is safe is low-priority no matter how clean the
+ * suggested rewrite reads. A cross-file ripple that breaks a caller
+ * not in the diff is the audit-equivalent of an unimplementable fix —
+ * load-bearing even though the named file looks fine in isolation.
+ *
  * Review examines source code in named files against a focus area
  * (security/correctness/performance/style). Findings should be
- * line-quotable — that's the natural shape of code defects.
+ * line-quotable — that's the natural shape of code defects — but
+ * cross-file findings backed by call-site references are also valid.
+ */
+/**
+ * The orientation block. Goes at the TOP of every review prompt.
+ *
+ * This is the load-bearing addition. Without an explicit purpose
+ * statement, workers default to "find issues in this file" — which
+ * produces line-by-line proofreading and misses the cross-file rippe,
+ * test-gap, and implicit-contract findings that actually block merges.
  */
+export const REVIEW_PURPOSE_ORIENTATION = [
+    'Why this review exists:',
+    'mma-review is the pre-merge gate. The maintainer accepting your verdict will NOT re-investigate before merging — your verdict is treated as authoritative. A miss here ships to production.',
+    '',
+    'Your job is to find anything that would make the merge unsafe, including issues that look fine in the named files in isolation:',
+    '- a changed function with no test (or with a test that does not exercise the change)',
+    '- a changed signature whose direct callers (visible in the named files or via grep on the symbol) were not updated',
+    '- a change that introduces a new edge case (null/empty/timeout/error path) the code does not handle',
+    '- a race or concurrency hazard the change exposes (shared state mutation, missing lock, await-after-check pattern)',
+    '- a resource leak the change introduces (unclosed handle, untracked promise, file descriptor not freed)',
+    '- a backward-compatibility break in a public API or wire schema',
+    '- a security regression (auth bypass, injection, untrusted input flowing to a sink, data exposure)',
+    '- a performance regression (N+1 query, unbounded loop, blocking I/O on a hot path, unnecessary deep clone)',
+    '- an implicit-contract assumption — the change relies on the caller doing X but the contract does not state X',
+    '- a pre-existing bug entangled with the change (NOT a finding against this diff — separate cleanly)',
+    '',
+    'A finding that points at any of these is high-value EVEN IF the prose of the change reads cleanly. Conversely, a stylistic nit that does not change merge safety is low-priority no matter how clean the suggested rewrite reads.',
+    '',
+    'The completion test: would a maintainer who reads only your review and the diff (not the surrounding code) understand which changes are required, why each is required, and where each lives — well enough to apply the fix and re-merge?',
+].join('\n');
 export const EVIDENCE_RULE_REVIEW = [
     'Evidence grounding (REQUIRED for every finding):',
     '- Cite `file:line` (or `file:line-line` for a span) where the issue lives.',
-    '- Quote the exact code excerpt or command output that demonstrates the issue. Don\'t paraphrase — quote.',
-    '- If you cannot quote evidence directly from the named files, do NOT raise the finding. Note "investigation needed" in your summary instead.',
+    '- Quote the exact code excerpt or command output that demonstrates the issue. Do not paraphrase — quote.',
+    '- For CROSS-FILE findings (a change in named file A breaks a caller B), cite both: the line in A that triggers the break, AND the call site in B that breaks. If B is not in the named files but is reachable via grep on the changed symbol, name it explicitly. Cross-file findings backed by call-site references are FULLY VALID — do not drop them as out-of-scope.',
+    '- For TEST-GAP findings, name the test file you would expect to cover the change AND quote the diff line that has no test coverage. If no test file exists for the changed area, that itself is the finding.',
+    '- For IMPLICIT-CONTRACT findings, quote the line in the named file that depends on the assumption AND name the contract source (the public docstring, the type, the README) that does not state the assumption.',
+    '- If you cannot quote evidence in one of these forms, do NOT raise the finding. Note "investigation needed" in your summary instead.',
 ].join('\n');
 export const SCOPE_RULE_REVIEW = [
     'Scope:',
     '- The named files. Behavior of direct callers/callees can be referenced when visible in those files.',
-    '- Out of scope: speculation about untouched files; doc/spec issues (those belong in an audit, not a review); style nits when the focus area is security/correctness/performance.',
+    '- Cross-file ripples ARE in scope when the changed symbol is searchable: if the named files change a public function, look for its call sites in the rest of the repo and flag any caller that would break. This is the highest-value cross-file work for a code review.',
+    '- Test gaps ARE in scope: if the named files change behavior and a test file is the natural sibling (e.g. `foo.ts` → `tests/foo.test.ts`), check whether the test exercises the change.',
+    '- Out of scope: speculation about untouched files unrelated to the diff; doc/spec issues (those belong in an audit, not a review); style nits when the focus area is security/correctness/performance.',
+    '- Pre-existing bugs (the diff did not introduce them) belong in their own backlog item, not in this review. Note them in a "Pre-existing — out of scope" section if you spot them, but DO NOT mix them into the merge-blocking findings.',
+].join('\n');
+/**
+ * The failure-mode taxonomy for code reviews.
+ *
+ * Without this block, workers default to line-by-line proofreading of
+ * the named file and miss cross-file ripples, test gaps, and
+ * implicit-contract regressions — the findings that actually block
+ * merges. The 10 categories below are what a careful maintainer would
+ * scan for before pressing merge.
+ */
+export const CODE_REVIEW_FAILURE_MODES = [
+    'Look for these kinds of issues — applicable to ALL code reviews regardless of focus. The focus area (security/correctness/performance/style) tells you which lens to weight, but every code review should sweep the full taxonomy:',
+    '',
+    '1. TEST GAP — the diff changes behavior, but no test exercises the change. Either: no test file exists, OR the test file exists but the changed branch is not covered. **Always check for the natural sibling test file when reviewing source-code changes.**',
+    '2. CROSS-FILE RIPPLE — a changed signature, return shape, public type, or wire schema is referenced from another file that was not updated. **If the named files change a public symbol, grep for the symbol and flag any unupdated caller.**',
+    '3. PRE-EXISTING-BUG-VS-NEW-REGRESSION — a defect exists in the named files but the diff did not introduce it. Do NOT blame the diff for prior bugs; note them in a separate "Pre-existing — out of scope" section. Conversely, if the diff DID introduce or worsen a defect, flag it as a regression.',
+    '4. MISSING EDGE CASE — the change adds a code path but does not handle null/undefined/empty/timeout/error/zero/negative inputs the path could see. Walk the change against each natural boundary value.',
+    '5. RACE / CONCURRENCY — the change introduces shared state mutation, removes a lock, splits a previously-atomic operation, or adds an await between a check and an action (TOCTOU). Flag these even when no test reproduces.',
+    '6. RESOURCE LEAK — the change opens a handle (file, socket, lock, transaction, AbortController) without a guaranteed close path; or introduces an untracked promise that may reject silently.',
+    '7. BACKWARD-COMPAT BREAK — the change modifies a public API, exported type, wire schema, environment variable, or CLI flag in a way that breaks existing callers. Flag and require a migration note.',
+    '8. SECURITY REGRESSION — the change introduces or worsens auth bypass, injection (SQL/command/prompt), untrusted input flowing to a sink (eval/exec/HTML/SQL), data exposure, or weakened sandboxing. Apply the security lens to every change, not just security-flagged ones.',
+    '9. PERFORMANCE REGRESSION — the change adds N+1 queries, unbounded loops, blocking I/O on a hot path, unnecessary deep clones, or shifts work from build/init time to request time. Apply the performance lens to every change, not just performance-flagged ones.',
+    '10. IMPLICIT-CONTRACT ASSUMPTION — the changed code relies on the caller (or environment) doing X but the contract (docstring, type, README) does not state X. The change works for in-repo callers but will silently break when the contract is read literally.',
+    '',
+    'Severity calibration for code reviews:',
+    '- critical: the merge would corrupt data, expose credentials, allow auth bypass, break a public API in production, or cause production outage. A reader who applied the fix incorrectly could ship the regression.',
+    '- high: the merge would introduce a real bug, security gap, or substantial regression that blocks release. Cross-file ripple where a caller is broken. Missing edge case in a code path that production traffic will hit.',
+    '- medium: a real issue worth fixing soon: test gap on a non-trivial change, race condition with low contention, performance regression on a non-hot path, missing edge case on an unlikely input.',
+    '- low: stylistic / naming / dead-code / minor-refactor opportunity. Does not change merge safety.',
+].join('\n');
+/**
+ * Counter-balance to the SEVERITY_LADDER's anti-inflation hint.
+ *
+ * The shared severity ladder ends with "Workers commonly inflate —
+ * resist the urge." That bias is correct in the limit (no, the missing
+ * comma is not critical) but produces UNDER-finding when combined with
+ * a thin per-tool rubric. For code review specifically, the typical
+ * failure is missing the cross-file ripple or test gap because the
+ * worker only looked at the diff in the named file. This block tells
+ * the worker that under-finding is the more common review failure.
+ */
+export const THOROUGHNESS_REMINDER_REVIEW = [
+    'Thoroughness expectation for code reviews:',
+    '- For non-trivial diffs (>30 changed lines OR a public symbol changed), zero or 1-2 findings is unusual and usually indicates the rubric was applied too narrowly. Sweep the full failure-mode taxonomy above before declaring "no findings."',
+    '- The SEVERITY_LADDER warns against inflation. That warning is calibrated — but the typical UNDER-finding in code review is missing the cross-file ripple or test gap because the worker only looked at the diff in the named file. Apply the failure-mode taxonomy thoroughly first; THEN calibrate severity downward where the impact is small.',
+    '- Do not invent findings to hit a quota. But if you have applied all 10 failure modes and still have only stylistic nits, double-check categories 1, 2, 4, and 10 (test gap, cross-file ripple, missing edge case, implicit-contract assumption) — these are the ones reviewers most often miss on first pass and the ones most likely to ship a regression.',
+    '',
+    'Cross-file pass (REQUIRED when the named files change a public symbol — exported function, exported type, route handler, or wire-schema field):',
+    '- Make ONE explicit pass: identify the changed public symbols, grep for their call sites in the rest of the repo, and check whether each call site is consistent with the new signature/return-shape/contract.',
+    '- For each (changed symbol, call site) pair, ask: does the call site as currently written still work after this change?',
+    '- Worked example. A diff in `src/foo.ts` renames `getUserById(id)` to `getUserById(id, opts)` and makes `opts` required. The grep finds 3 call sites in `src/handlers/auth.ts`, `src/handlers/billing.ts`, `tests/integration/users.test.ts`. None pass `opts`. Flag this as HIGH (or CRITICAL if `auth.ts` would no-op silently rather than error). The fact that `src/foo.ts` looks clean in isolation is exactly the kind of false-clean that ships regressions.',
+    '- Most reviewers miss findings of this shape on first pass because they only read the named files. The cross-file pass forces the grep.',
 ].join('\n');
 export const ANNOTATOR_AWARENESS_REVIEW = [
     'After your output, an annotator validates each finding against this code-review rubric:',
-    '- Is the finding within the requested focus area?',
-    '- Does the evidence quote real code from the named files?',
-    '- Is the severity calibrated to actual impact?',
-    '- Is the finding within the requested scope, or is it about untouched code?',
-    'Self-check before emitting. Findings that fail any check are downgraded or dropped.',
+    '- Is the finding within the requested focus area (or universally applicable: security, performance, correctness apply to every review)?',
+    '- Does the evidence quote real code from the named files OR cite a real call site reachable via grep on the changed symbol?',
+    '- Is the severity calibrated to actual merge-safety impact (would a reader who applied the fix incorrectly ship a regression)?',
+    '- Is the finding within scope (named files + cross-file ripples on changed symbols + sibling test files), or is it speculation about unrelated code?',
+    'Self-check before emitting. Findings that fail any check are downgraded or dropped — but cross-file ripple findings backed by call-site references and test-gap findings backed by sibling-test-file references are FULLY VALID, do NOT downgrade them as "speculation about untouched files."',
 ].join('\n');
 //# sourceMappingURL=implementer-criteria.js.map

package/dist/tools/review/implementer-criteria.js.map

@@ -1 +1 @@
-{"version":3,"file":"implementer-criteria.js","sourceRoot":"","sources":["../../../src/tools/review/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,kDAAkD;IAClD,4EAA4E;IAC5E,0GAA0G;IAC1G,8IAA8I;CAC/I,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ;IACR,sGAAsG;IACtG,kLAAkL;CACnL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,yFAAyF;IACzF,mDAAmD;IACnD,2DAA2D;IAC3D,gDAAgD;IAChD,6EAA6E;IAC7E,qFAAqF;CACtF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"implementer-criteria.js","sourceRoot":"","sources":["../../../src/tools/review/implementer-criteria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,yBAAyB;IACzB,6LAA6L;IAC7L,EAAE;IACF,iIAAiI;IACjI,sFAAsF;IACtF,oHAAoH;IACpH,qGAAqG;IACrG,oHAAoH;IACpH,yGAAyG;IACzG,iEAAiE;IACjE,oGAAoG;IACpG,4GAA4G;IAC5G,+GAA+G;IAC/G,qGAAqG;IACrG,EAAE;IACF,mOAAmO;IACnO,EAAE;IACF,2OAA2O;CAC5O,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,kDAAkD;IAClD,4EAA4E;IAC5E,0GAA0G;IAC1G,0WAA0W;IAC1W,8MAA8M;IAC9M,iNAAiN;IACjN,sIAAsI;CACvI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ;IACR,sGAAsG;IACtG,0QAA0Q;IAC1Q,yLAAyL;IACzL,wMAAwM;IACxM,0OAA0O;CAC3O,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,oOAAoO;IACpO,EAAE;IACF,+PAA+P;IAC/P,+OAA+O;IAC/O,uSAAuS;IACvS,yMAAyM;IACzM,8NAA8N;IAC9N,+LAA+L;IAC/L,sMAAsM;IACtM,gRAAgR;IAChR,oQAAoQ;IACpQ,kQAAkQ;IAClQ,EAAE;IACF,wCAAwC;IACxC,oNAAoN;IACpN,2NAA2N;IAC3N,mMAAmM;IACnM,mGAAmG;CACpG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,4CAA4C;IAC5C,+OAA+O;IAC/O,mVAAmV;IACnV,8VAA8V;IAC9V,EAAE;IACF,iJAAiJ;IACjJ,gNAAgN;IAChN,yHAAyH;IACzH,qcAAqc;IACrc,yIAAyI;CAC1I,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,yFAAyF;IACzF,yIAAyI;IACzI,6HAA6H;IAC7H,gIAAgI;IAChI,sJAAsJ;IACtJ,gSAAgS;CACjS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/dist/tools/review/tool-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-config.d.ts","sourceRoot":"","sources":["../../../src/tools/review/tool-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAEvE,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,6CAA6C,CAAC;AAWhG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAYlE;AAwED,eAAO,MAAM,UAAU,EAAE,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAsC9D,CAAC"}
+{"version":3,"file":"tool-config.d.ts","sourceRoot":"","sources":["../../../src/tools/review/tool-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAElF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAEvE,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,6CAA6C,CAAC;AAchG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAYlE;AA2GD,eAAO,MAAM,UAAU,EAAE,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAsC9D,CAAC"}