ai-engineering-loop 1.0.2 → 1.0.4

package/lib/orchestration.js

@@ -0,0 +1,409 @@
+/**
+ * AI Engineering Loop — Runtime Capability Registry & Orchestration Core
+ * 
+ * Invariants:
+ * 1. AI Engineering Loop must NEVER claim independent agent execution without runtime
+ *    evidence of an actual separate LLM execution.
+ * 2. Distinction between CONFIGURATION_SUPPORTED, INVOCATION_AVAILABLE, and EXECUTION_PROVEN:
+ *    - CONFIGURATION_SUPPORTED: The platform understands subagent configuration (e.g. AGENT.md, subagent: true).
+ *    - INVOCATION_AVAILABLE: An invocation tool or authenticated CLI is callable in the active runtime.
+ *    - EXECUTION_PROVEN: A separate child session produced an actual model response with independent context.
+ * 3. Artifact isolation is strictly reported as CONTEXT_ISOLATION_ONLY (Independent LLM execution: NOT PROVEN).
+ * 4. browser_subagent is browser automation and must NOT be classified as an LLM subagent.
+ * 5. agentapi send-message is an IPC communication capability and must NEVER activate agent execution.
+ */
+
+const crypto = require('crypto');
+
+// 1. Standard 5 Execution Modes
+const EXECUTION_MODES = {
+  TRUE_INDEPENDENT_AGENT: {
+    id: 'TRUE_INDEPENDENT_AGENT',
+    label: 'True Independent Agent',
+    isIndependentExecutionProven: true,
+    description: 'Separate child conversation/process exists, actual LLM execution occurs, and child has independent conversational context'
+  },
+  ISOLATED_AGENT_INSTANCE: {
+    id: 'ISOLATED_AGENT_INSTANCE',
+    label: 'Isolated Agent Instance',
+    isIndependentExecutionProven: true,
+    description: 'Separate conversation or agent instance exists with verified independent model execution'
+  },
+  FRESH_PROCESS_AGENT: {
+    id: 'FRESH_PROCESS_AGENT',
+    label: 'Fresh Process Agent',
+    isIndependentExecutionProven: true,
+    description: 'Separate OS process successfully executes an LLM agent with fresh context'
+  },
+  CONTEXT_ISOLATION_ONLY: {
+    id: 'CONTEXT_ISOLATION_ONLY',
+    label: 'Context Isolation Only',
+    isIndependentExecutionProven: false,
+    description: 'Isolated review context within the same LLM session; independent agent execution is NOT proven'
+  },
+  UNAVAILABLE: {
+    id: 'UNAVAILABLE',
+    label: 'Unavailable',
+    isIndependentExecutionProven: false,
+    description: 'No review execution mechanism is available'
+  }
+};
+
+/**
+ * 2. Standardized Capability Evidence Factory with 3-Stage Lifecycle
+ */
+function createCapabilityEvidence({
+  mechanism,
+  classification,
+  configurationSupported = false,
+  invocationAvailable = false,
+  executionProven = false,
+  available = false,
+  commandOrApi = null,
+  result = null,
+  executionIdentity = null,
+  conversationId = null,
+  parentConversationId = null,
+  childConversationId = null,
+  childModelResponse = null,
+  modelExecutionProven = false,
+  independentContextProven = false,
+  historyInherited = null,
+  isDocumentationOnly = false,
+  isBrowserAutomationOnly = false,
+  reason = null,
+  timestamp = new Date().toISOString()
+}) {
+  if (!mechanism || !classification) {
+    throw new Error('Capability evidence must include mechanism and classification');
+  }
+
+  const modelExecuted = Boolean(modelExecutionProven || (childModelResponse && executionIdentity));
+  const fullyProven = Boolean(executionProven || (modelExecuted && childConversationId && independentContextProven));
+
+  return {
+    mechanism,
+    classification,
+    configurationSupported: Boolean(configurationSupported),
+    invocationAvailable: Boolean(invocationAvailable),
+    executionProven: fullyProven,
+    available: Boolean(available || fullyProven),
+    commandOrApi,
+    result,
+    executionIdentity,
+    conversationId,
+    parentConversationId,
+    childConversationId,
+    childModelResponse,
+    modelExecutionProven: modelExecuted,
+    independentContextProven: Boolean(independentContextProven),
+    historyInherited,
+    isDocumentationOnly: Boolean(isDocumentationOnly),
+    isBrowserAutomationOnly: Boolean(isBrowserAutomationOnly),
+    reason,
+    timestamp
+  };
+}
+
+/**
+ * 3. Evaluate whether a capability candidate satisfies execution proof
+ */
+function isCapabilityProvenForMode(evidence, targetModeId) {
+  if (!evidence) {
+    return false;
+  }
+
+  // Reject non-agent capabilities (such as IPC send-message)
+  if (
+    evidence.classification === 'NOT_AN_AGENT_EXECUTION_CAPABILITY' ||
+    evidence.classification === 'IPC_MESSAGE_DISPATCH'
+  ) {
+    return false;
+  }
+
+  // Reject browser automation tools (browser_subagent is NOT an LLM subagent)
+  if (evidence.isBrowserAutomationOnly || evidence.classification === 'BROWSER_AUTOMATION_TOOL') {
+    return false;
+  }
+
+  // Reject documentation-only or configuration-only claims
+  if (evidence.isDocumentationOnly || (evidence.configurationSupported && !evidence.executionProven)) {
+    if (targetModeId !== 'CONTEXT_ISOLATION_ONLY') {
+      return false;
+    }
+  }
+
+  // Modes requiring true independent LLM execution
+  if (
+    targetModeId === 'TRUE_INDEPENDENT_AGENT' ||
+    targetModeId === 'ISOLATED_AGENT_INSTANCE' ||
+    targetModeId === 'FRESH_PROCESS_AGENT'
+  ) {
+    // Must satisfy all 4 pillars of execution proof:
+    const hasChildSession = Boolean(evidence.childConversationId || targetModeId === 'FRESH_PROCESS_AGENT');
+    const hasModelResponse = Boolean(evidence.modelExecutionProven || evidence.childModelResponse);
+    const hasExecIdentity = Boolean(evidence.executionIdentity);
+    const hasCleanContext = Boolean(evidence.independentContextProven && evidence.historyInherited !== true);
+
+    if (!evidence.executionProven && !(hasChildSession && hasModelResponse && hasExecIdentity && hasCleanContext)) {
+      return false;
+    }
+  }
+
+  // Context isolation mode requires verified artifact boundary
+  if (targetModeId === 'CONTEXT_ISOLATION_ONLY') {
+    return evidence.available === true;
+  }
+
+  return true;
+}
+
+/**
+ * 4. Deterministic Execution Mode Selection
+ * Evaluates registry strictly in priority order:
+ * 1. TRUE_INDEPENDENT_AGENT
+ * 2. ISOLATED_AGENT_INSTANCE
+ * 3. FRESH_PROCESS_AGENT
+ * 4. CONTEXT_ISOLATION_ONLY
+ * 5. UNAVAILABLE
+ */
+function selectExecutionMode(capabilityRegistry = {}) {
+  const {
+    nativeSubagent,
+    sdkAgent,
+    headlessProcessAgent,
+    artifactIsolation
+  } = capabilityRegistry;
+
+  // Priority 1: True Native Independent Sub-Agent
+  if (isCapabilityProvenForMode(nativeSubagent, 'TRUE_INDEPENDENT_AGENT')) {
+    return EXECUTION_MODES.TRUE_INDEPENDENT_AGENT;
+  }
+
+  // Priority 2: Programmatic SDK Agent Instance
+  if (isCapabilityProvenForMode(sdkAgent, 'ISOLATED_AGENT_INSTANCE')) {
+    return EXECUTION_MODES.ISOLATED_AGENT_INSTANCE;
+  }
+
+  // Priority 3: Headless Subprocess Agent
+  if (isCapabilityProvenForMode(headlessProcessAgent, 'FRESH_PROCESS_AGENT')) {
+    return EXECUTION_MODES.FRESH_PROCESS_AGENT;
+  }
+
+  // Priority 4: Guaranteed Fallback - Context Isolation Only
+  if (isCapabilityProvenForMode(artifactIsolation, 'CONTEXT_ISOLATION_ONLY')) {
+    return EXECUTION_MODES.CONTEXT_ISOLATION_ONLY;
+  }
+
+  // Priority 5: Unavailable
+  return EXECUTION_MODES.UNAVAILABLE;
+}
+
+/**
+ * 5. Build Clean-Slate Artifact Isolation Barrier
+ */
+function buildReviewContextBarrier({
+  goalContract,
+  gitDiff,
+  verificationLogs,
+  projectContext,
+  activeIteration = 1,
+  priorFindingSignatures = []
+}) {
+  if (!goalContract || !gitDiff) {
+    throw new Error('Goal contract and git diff are mandatory for review barrier');
+  }
+
+  return {
+    iteration: activeIteration,
+    diffHash: crypto.createHash('sha256').update(gitDiff).digest('hex').slice(0, 16),
+    goalContract: {
+      objective: goalContract.objective,
+      acceptanceCriteria: goalContract.acceptanceCriteria || [],
+      technicalConstraints: goalContract.technicalConstraints || [],
+      outOfScope: goalContract.outOfScope || []
+    },
+    projectContext: {
+      profile: projectContext?.profile || 'standard',
+      architecture: projectContext?.architecture || '',
+      conventions: projectContext?.conventions || '',
+      verificationCommands: projectContext?.verificationCommands || ''
+    },
+    gitDiff: gitDiff.trim(),
+    verificationLogs: {
+      exitCode: verificationLogs?.exitCode ?? 0,
+      summary: verificationLogs?.summary || 'Deterministic checks passed 100%'
+    },
+    priorFindingSignatures: [...priorFindingSignatures]
+  };
+}
+
+/**
+ * 6. Validate Verification Evidence Contract
+ */
+function validateVerificationEvidence(evidence) {
+  if (!evidence) return { valid: false, reason: 'Evidence object missing' };
+
+  const requiredFields = ['command', 'executionIdentity', 'startTime', 'endTime', 'exitCode', 'stdout', 'timeoutStatus'];
+  for (const field of requiredFields) {
+    if (evidence[field] === undefined || evidence[field] === null || evidence[field] === '') {
+      return { valid: false, reason: `Missing required evidence field: ${field}` };
+    }
+  }
+
+  if (evidence.exitCode !== 0) {
+    return { valid: false, reason: `Verification failed with non-zero exit code: ${evidence.exitCode}` };
+  }
+
+  if (evidence.timeoutStatus !== 'COMPLETED') {
+    return { valid: false, reason: `Verification did not complete cleanly: ${evidence.timeoutStatus}` };
+  }
+
+  const vaguePatterns = ['command was launched', 'test appears to have passed', 'running in background', 'seems green'];
+  const outLower = (evidence.stdout + ' ' + (evidence.summary || '')).toLowerCase();
+  for (const pattern of vaguePatterns) {
+    if (outLower.includes(pattern) && (!evidence.testCounts || evidence.testCounts.passed === 0)) {
+      return { valid: false, reason: `Rejected vague or speculative assertion: "${pattern}"` };
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * 7. Validate Finding Ledger Schema
+ */
+function validateFindingLedger(ledger) {
+  if (!ledger || !Array.isArray(ledger.findings)) {
+    return { valid: false, reason: 'Finding ledger must contain an array of findings' };
+  }
+
+  const validSeverities = ['BLOCKER', 'HIGH', 'MEDIUM', 'LOW'];
+  const validValidities = ['VALID', 'INVALID'];
+  const validDispositions = ['STRONG', 'ACCEPTABLE', 'WEAK'];
+
+  for (let i = 0; i < ledger.findings.length; i++) {
+    const f = ledger.findings[i];
+    if (!f.id || !f.location || !f.failureScenario || !f.evidence) {
+      return { valid: false, reason: `Finding at index ${i} missing required id, location, failureScenario, or evidence` };
+    }
+
+    if (!validSeverities.includes(f.severity)) {
+      return { valid: false, reason: `Invalid severity at index ${i}: ${f.severity}. Must be: ${validSeverities.join(', ')}` };
+    }
+
+    if (!validValidities.includes(f.validity)) {
+      return { valid: false, reason: `Invalid validity at index ${i}: ${f.validity}. Must be VALID or INVALID` };
+    }
+
+    if (!validDispositions.includes(f.disposition)) {
+      return { valid: false, reason: `Invalid disposition at index ${i}: ${f.disposition}. Must be STRONG, ACCEPTABLE, or WEAK` };
+    }
+
+    if (f.validity === 'VALID' && (f.severity === 'BLOCKER' || f.severity === 'HIGH') && !f.concreteAlternativeDiff) {
+      return { valid: false, reason: `VALID ${f.severity} finding ${f.id} must provide concreteAlternativeDiff` };
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * 8. Compute Judge Verdict based primarily on Validity + Severity
+ */
+function computeJudgeVerdict({
+  goalContract,
+  verificationEvidence,
+  findingLedger,
+  activeIteration = 1,
+  maxIterations = 3
+}) {
+  const verifCheck = validateVerificationEvidence(verificationEvidence);
+  if (!verifCheck.valid) {
+    return {
+      verdict: 'ITERATE',
+      reason: `Deterministic verification failed: ${verifCheck.reason}`,
+      action: 'Maker must rerun deterministic test suite and obtain clean exit code 0.'
+    };
+  }
+
+  const findings = findingLedger?.findings || [];
+  const blockingFindings = [];
+  const acceptableFindings = [];
+  const dismissedFindings = [];
+
+  for (const f of findings) {
+    if (f.validity === 'INVALID') {
+      dismissedFindings.push({
+        id: f.id,
+        reason: `Dismissed invalid finding: ${f.failureScenario} (Evidence disproved)`
+      });
+      continue;
+    }
+
+    if (f.severity === 'BLOCKER' || f.severity === 'HIGH') {
+      blockingFindings.push(f);
+    } else {
+      acceptableFindings.push(f);
+    }
+  }
+
+  if (blockingFindings.length > 0) {
+    if (activeIteration >= maxIterations) {
+      return {
+        verdict: 'ESCALATE',
+        reason: `Max iteration ceiling (${maxIterations}) reached with ${blockingFindings.length} open blocking findings.`,
+        blockingFindings,
+        action: 'Human escalation triggered with actionable diagnostic ledger.'
+      };
+    }
+
+    return {
+      verdict: 'ITERATE',
+      reason: `${blockingFindings.length} VALID BLOCKER/HIGH findings require code revision.`,
+      blockingFindings,
+      action: 'Maker must apply concrete alternative diffs and author regression tests.'
+    };
+  }
+
+  return {
+    verdict: 'PASS',
+    reason: `All acceptance criteria verified; 0 open blocking findings; ${dismissedFindings.length} invalid findings dismissed; ${acceptableFindings.length} acceptable tradeoffs documented.`,
+    acceptableTradeoffs: acceptableFindings,
+    dismissedFindings,
+    action: 'Proceed to Context Impact Assessment and Delivery Adapter.'
+  };
+}
+
+/**
+ * 9. Truthful Review Report Generator
+ * Enforces mandatory reporting headers and strictly prevents misleading phrasing.
+ */
+function formatExecutionReport({ selectedMode, capabilityRegistry = {} }) {
+  const isContextOnly = selectedMode.id === EXECUTION_MODES.CONTEXT_ISOLATION_ONLY.id;
+
+  const nativeSubagentState = capabilityRegistry.nativeSubagent?.invocationAvailable
+    ? 'AVAILABLE'
+    : 'UNAVAILABLE';
+
+  const lines = [
+    `Execution Mode: ${selectedMode.id}`,
+    `Independent LLM Execution: ${selectedMode.isIndependentExecutionProven ? 'PROVEN' : 'NOT PROVEN'}`,
+    `Native Subagent Invocation: ${nativeSubagentState}`,
+    `Review Method: ${isContextOnly ? 'Clean-Slate Artifact Isolation Barrier' : selectedMode.label}`
+  ];
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  EXECUTION_MODES,
+  createCapabilityEvidence,
+  isCapabilityProvenForMode,
+  selectExecutionMode,
+  buildReviewContextBarrier,
+  validateVerificationEvidence,
+  validateFindingLedger,
+  computeJudgeVerdict,
+  formatExecutionReport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-loop",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A reusable, framework-agnostic AI Engineering Operating System for autonomous coding agents.",
   "main": "bin/ai-engineering-loop.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "init": "node bin/ai-engineering-loop.js",
-    "publish:npm": "node scripts/publish-npm.js"
+    "test": "node --test tests/*.test.js"
   },
   "repository": {
     "type": "git",

package/policies/evidence-policy.md

@@ -10,9 +10,23 @@ An agent may not state that code is functional, bug-free, optimized, or ready fo
 
 ---
 
-## 2. The Evidence Hierarchy
+## 2. Verification Evidence Contract
 
-Evidence is ranked in order of reliability and truth value:
+A verification `PASS` is strictly invalid without concrete execution evidence. The system categorically rejects vague statements such as *"command was launched"* or *"test appears to have passed"*.
+
+### Mandatory Execution Evidence Properties:
+1. **`command`**: Exact CLI command executed.
+2. **`executionIdentity`**: Execution ID / PID / timestamp.
+3. **`startTime` & `endTime`**: Documenting execution duration.
+4. **`exitCode`**: Must be `0`.
+5. **`stdout` & `stderr`**: Raw machine logs captured.
+6. **`timeoutStatus`**: Must be `"COMPLETED"`.
+7. **`testCounts`**: Explicit counts of passed, failed, and skipped tests.
+8. **`assertionEvidence`**: Specific assertion proof matching the active Goal Contract's Acceptance Criteria.
+
+---
+
+## 3. The Evidence Hierarchy
 
 ```mermaid
 flowchart TD
@@ -20,7 +34,7 @@ flowchart TD
     E2[Level 2: Concrete Codebase Artifacts<br>Actual file contents, git commit history, schema files]
     E3[Level 3: Adversarial Code Diffs<br>Exact before/after reproduction snippets]
     E4[Level 4: Theoretical / Analytical Deduction<br>Reasoning through architectural implications]
-    E5[Level 5: Unsupported Assertion<br>'Looks correct', 'Should work fine' - REJECTED]
+    E5[Level 5: Unsupported Assertion<br>'Looks correct', 'Command launched' - REJECTED]
 
     E1 --> E2 --> E3 --> E4 -.-> E5
 ```
@@ -49,22 +63,26 @@ flowchart TD
 
 ---
 
-## 3. Evidence Requirements for Common Agent Claims
+## 4. Capability Discovery & Orchestration Evidence Rules
+
+To prevent misleading claims of multi-agent execution, capability selection must adhere to strict evidence standards:
+
+1. **Documentation is NOT capability proof**: Mentioning `subagent: true` in markdown is not proof of subagent execution.
+2. **Configuration is NOT execution proof**: A YAML config file is not evidence of a running agent.
+3. **IPC existence is NOT execution proof**: The existence of an IPC binary (`agentapi`) or successful message dispatch (`send-message`) is an IPC capability, **NOT** an LLM agent execution capability.
+4. **Conversation creation without model response is NOT an agent**: A conversation ID without an actual captured LLM response is not execution proof.
+5. **Persona simulation is NEVER an agent**: Switching roles within the same session is self-review, not independent adversarial review.
+6. **Artifact isolation is strictly labeled**: When review is conducted within the same session via artifact boundaries, it is **strictly reported as `CONTEXT_ISOLATION_ONLY`** with `Independent LLM execution: NOT PROVEN`.
+
+---
+
+## 5. Evidence Requirements for Common Agent Claims
 
 | Claim Type | Mandatory Evidence Required | Prohibited Substitute |
 |---|---|---|
 | **"Bug is fixed"** | Reproducing test that previously failed now passes with exit code 0. | "The logic was corrected." |
 | **"No regressions"** | Full test suite execution log showing 0 failures. | "I only touched a single function." |
 | **"Type safe"** | `tsc --noEmit` / compiler run output with 0 errors. | "I added type annotations." |
-| **"Review finding is invalid (Halu)"** | File path & line showing the suggested API does not exist or behavior is intentional. | "I disagree with the reviewer." |
+| **"Review finding is invalid"** | File path & line showing the suggested API does not exist or behavior is intentional. | "I disagree with the reviewer." |
 | **"Acceptance criteria AC-X met"** | Test function name & assertion specifically targeting AC-X. | "Implemented according to spec." |
-
----
-
-## 4. Evidentiary Audit Trail
-
-Every artifact created during the engineering loop (Goal Contract, Maker Log, Review Findings, Judge Verdict) must maintain an unbroken chain of evidence:
-
-1. **Exact Commands Run**: Included in verbatim code blocks.
-2. **Standard Output / Error Logs**: Verbatim output snippets without truncation of error counts.
-3. **Traceable File Links**: Every cited file must use clickable format (`file:///path/to/file#L1-L10`).
+| **"Independent subagent executed"** | Verified parent $\rightarrow$ child session ID + separate process + captured child model response. | "I switched to Devil's Advocate persona." |

package/policies/finding-policy.md

@@ -1,102 +1,70 @@
 # Finding Policy Specification
 
-## 1. Purpose
+## 1. Purpose & Core Philosophy
 
-The **Finding Policy** defines the standardized schema, severity definitions, categories, and lifecycle states for all issues identified by review agents (such as the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) or external review bots).
+The **Finding Policy** defines the standardized schema, severity definitions, validity rules, and lifecycle states for all issues identified by review agents (such as the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) or external review bots).
 
 A standardized finding schema ensures that:
-1. Every criticism is actionable, localized, and backed by evidence.
+1. Every criticism is actionable, localized, and backed by factual code evidence.
 2. Review findings can be parsed, hashed, and tracked across autonomous iterations.
-3. The [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) can evaluate findings objectively without subjective ambiguity.
+3. The [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) can evaluate findings deterministically based on **Validity + Severity** without subjective bias.
 
 ---
 
-## 2. Standardized Finding Schema
+## 2. Standardized Dual-Axis Finding Schema
 
-Every finding MUST be structured according to the following specification:
+Every finding MUST be structured according to the following dual-axis specification:
 
 ```yaml
 id: "<CATEGORY_PREFIX>-<3_DIGIT_NUMBER>" # e.g. COR-001, SEC-002, PERF-001
 title: "<Short, descriptive summary of the problem>"
-severity: "<CRITICAL | HIGH | MEDIUM | LOW | INFO>"
-category: "<Correctness | ErrorHandling | Security | Concurrency | Performance | Maintainability | TestingGaps>"
+topic: "<correctness | error_handling | security | concurrency | performance | maintainability | testing_gaps>"
+
+# Axis 1: Factual Validity
+validity: "<VALID | INVALID>" # VALID: Real technical flaw | INVALID: Reviewer hallucination or misunderstanding
+
+# Axis 2: Objective Severity
+severity: "<BLOCKER | HIGH | MEDIUM | LOW>"
+
+# Reviewer Disposition / Recommendation
+disposition: "<STRONG | ACCEPTABLE | WEAK>"
+
 location:
   file: "<Relative file path>"
   startLine: <Integer>
   endLine: <Integer>
+
+acceptanceCriteria: "<AC-1..N impacted, or 'GENERAL_REGRESSION'>"
 evidence: "<Exact code snippet, command output, or trace exhibiting the flaw>"
-problem: "<Detailed technical explanation of what is wrong>"
-impact: "<Concrete operational, business, or runtime consequence>"
-recommendation: "<Actionable suggestion and concrete code diff showing the fix>"
-confidence: "<HIGH | MEDIUM | LOW>"
-status: "<NEW | TRIAGED_VALID | TRIAGED_INVALID | TRIAGED_UNCERTAIN | RESOLVED | VERIFIED>"
-triageReason: "<Required when status is TRIAGED_INVALID or TRIAGED_UNCERTAIN>"
+failureScenario: "<Concrete step-by-step failure trace describing what breaks at runtime>"
+reproduction: "<Executable test case or sequence demonstrating the bug>"
+concreteAlternativeDiff: |
+  ```diff
+  - old_flawed_code()
+  + new_verified_fix()
+  ```
 ```
 
 ---
 
-## 3. Severity Matrix & Definitions
+## 3. Severity Matrix & Decision Impact
 
-| Severity Level | Definition | Impact on Build / Loop |
+| Severity Level | Definition | Impact on Verdict |
 |---|---|---|
-| **`CRITICAL` (SEV-1)** | Complete system crash, remote code execution, severe data corruption, authentication bypass, or massive data loss. | **BLOCKING**: Hard block. Must be resolved immediately; cannot pass DoD. |
-| **`HIGH` (SEV-2)** | Core business logic defect, unhandled null exception on primary user path, IDOR/authorization gap, or significant performance regression. | **BLOCKING**: Must be resolved before `PASS` verdict. |
-| **`MEDIUM` (SEV-3)** | Edge-case logic failure, missing error telemetry, suboptimal query with limited dataset, or unhandled rare boundary condition. | **NON-BLOCKING**: Can pass DoD if documented in backlog, unless directly violating an Acceptance Criterion. |
-| **`LOW` (SEV-4)** | Minor maintainability issue, non-critical testing gap, minor code duplication, or naming ambiguity. | **ADVISORY**: Does not block completion. |
-| **`INFO` (SEV-5)** | Informational observation, architectural note, or praise for a well-designed pattern. | **INFORMATIONAL**: No action required. |
-
----
-
-## 4. Review Categories
-
-Findings are categorized under one of the 7 standard domains:
-
-1. **`Correctness` (`COR`)**: Functional bugs, logic errors, type mismatches, inverted conditionals, timezone bugs, calculation errors.
-2. **`ErrorHandling` (`ERR`)**: Swallowed errors, unhandled rejections, missing fallbacks, crashing async boundaries.
-3. **`Security` (`SEC`)**: Injection, broken auth/access control, secret exposure, sensitive data logging, unsanitized inputs.
-4. **`Concurrency` (`CONC`)**: Race conditions, un-synchronized shared memory, non-atomic database operations, thread safety issues.
-5. **`Performance` (`PERF`)**: N+1 queries, memory leaks, unbounded array loops, unindexed filters, heavy synchronous blocking operations.
-6. **`Maintainability` (`MAINT`)**: High coupling, breaking existing architecture, anti-patterns, dead code, circular dependencies.
-7. **`TestingGaps` (`TEST`)**: Untested boundary conditions, weak/tautological assertions, missing negative test cases.
+| **`BLOCKER`** | System crash, severe data corruption, auth bypass, or direct violation of an explicit Acceptance Criterion. | **BLOCKING**: Forces `ITERATE` verdict. Cannot pass DoD. |
+| **`HIGH`** | Core business logic defect, unhandled null exception on primary user path, or critical performance regression. | **BLOCKING**: Forces `ITERATE` verdict. Must be fixed with regression test. |
+| **`MEDIUM`** | Edge-case logic failure, missing error telemetry, or suboptimal query with limited dataset. | **TRADE-OFF**: Merged if ACs are met; documented as acceptable tradeoff in MR. |
+| **`LOW`** | Minor maintainability issue, non-critical testing gap, minor code duplication, or naming ambiguity. | **TRADE-OFF**: Merged; documented in MR notes. |
 
 ---
 
-## 5. Finding Status & Validity Rules
-
-Review findings are hypotheses, not absolute truths. Every finding exists in one of the following states:
+## 4. Validity Rules & Falsification Principle
 
-- **`NEW`**: Initial discovery by reviewer.
-- **`TRIAGED_VALID`**: Author and Judge confirm that the defect is real and violates technical or contract requirements. Must be fixed by Maker.
-- **`TRIAGED_INVALID` (False Positive / "Halu")**: Author demonstrates with evidence that the reviewer's concern is factually incorrect, based on an API that does not exist, or flags intentional/designed behavior.
-- **`TRIAGED_UNCERTAIN`**: Ambiguous requirement where the codebase documentation is silent or contradictory. Triggers escalation.
-- **`RESOLVED`**: Maker has applied code fix and passing test suite.
-- **`VERIFIED`**: Devil's Advocate and Judge re-evaluated and confirmed the issue is fully solved.
-
----
+Review findings are hypotheses, not absolute truths.
 
-## 6. Concrete Example
+- **`VALID`**: The defect exists in the code and produces an unhandled failure or contract breach under realistic conditions.
+- **`INVALID` (Dismissed)**: The reviewer made an assumption disproved by the codebase, referenced a non-existent API, or flagged intentional behavior.
 
-```yaml
-id: "COR-001"
-title: "Unsafe timezone conversion in attendance clock-in calculation"
-severity: "HIGH"
-category: "Correctness"
-location:
-  file: "src/server/attendance/utils/calculate-duration.ts"
-  startLine: 28
-  endLine: 34
-evidence: |
-  const checkInHour = new Date(record.clockIn).getHours();
-problem: |
-  Using Date.prototype.getHours() extracts the local server timezone hour instead of converting to the employee's designated timezone (e.g. Asia/Jakarta).
-impact: |
-  Employees clocking in between 00:00 and 07:00 UTC will be marked as late or absent depending on the server hosting region.
-recommendation: |
-  Use timezone-aware date parsing with dayjs/date-fns-tz:
-  ```diff
-  - const checkInHour = new Date(record.clockIn).getHours();
-  + const checkInHour = dayjs(record.clockIn).tz(userTimezone).hour();
-  ```
-confidence: "HIGH"
-status: "TRIAGED_VALID"
-```
+> [!IMPORTANT]
+> **Decision Rule**: The Judge Agent evaluates findings primarily on **Validity + Severity**.
+> A reviewer's subjective disposition (`STRONG`, `ACCEPTABLE`, `WEAK`) **never overrides evidence**. An `INVALID` finding cannot block delivery, even if the reviewer labeled it `STRONG` or `BLOCKER`.