gru-ai 0.2.0 → 0.3.0

package/.claude/hooks/validate-gate.sh

@@ -35,12 +35,20 @@ set -euo pipefail
 #   path = relative to directive dir, supports {project-id} and {task-id} placeholders
 #   required_fields = comma-separated jq paths (for json type only)
 #
-# Weight skip rules (from directive-watcher.ts SKIPPED_STEPS):
-#   lightweight: skips challenge, brainstorm, approve (Morgan still plans, audit + project-brainstorm still run)
-#   medium: skips challenge
+# Pipeline step order (from SKILL.md):
+#   triage → checkpoint → read → context → audit → brainstorm → clarification →
+#   plan → approve → project-brainstorm → setup → execute → review-gate → wrapup → completion
+#
+# Weight skip rules (from SKILL.md / 00-delegation-and-triage.md):
+#   lightweight: skips brainstorm (no C-suite challenges, no separate brainstorm agents)
+#   medium: skips brainstorm (COO's inline challenge is included, but no brainstorm step)
 #   heavyweight: skips nothing
 #   strategic: skips nothing
 #
+# Note: 'challenge' was merged into 'brainstorm' — it is no longer a separate step ID.
+# Clarification is auto-approved (not skipped) for lightweight/medium — it still runs.
+# Approve is auto-approved (not skipped) for lightweight/medium — it still runs.
+#
 # .skip marker convention:
 #   For weight-conditional steps, a file named "{step}.skip" in the directive dir
 #   satisfies the gate. Example: brainstorm.skip means brainstorm was legitimately
@@ -49,8 +57,8 @@ set -euo pipefail
 
 # Steps that can be skipped per weight class
 # Format: SKIP_<WEIGHT> is a space-separated list of skippable steps
-SKIP_lightweight="challenge brainstorm project-brainstorm audit approve"
-SKIP_medium="challenge"
+SKIP_lightweight="brainstorm"
+SKIP_medium="brainstorm"
 SKIP_heavyweight=""
 SKIP_strategic=""
 
@@ -77,14 +85,18 @@ TARGET_STEP="$2"
 TASK_ID="${3:-}"
 
 # Resolve to repo root for consistent paths
-REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-
-# If directive-dir is relative, make it relative to repo root
-if [[ ! "$DIRECTIVE_DIR" = /* ]]; then
+# If directive-dir is absolute and contains .context/directives/, derive repo root
+# from it (supports worktrees where git rev-parse returns the wrong root).
+if [[ "$DIRECTIVE_DIR" = /* ]] && [[ "$DIRECTIVE_DIR" == */.context/directives/* ]]; then
+  REPO_ROOT="${DIRECTIVE_DIR%%/.context/directives/*}"
+  DIRECTIVE_DIR_ABS="$DIRECTIVE_DIR"
+  DIRECTIVE_DIR="${DIRECTIVE_DIR#${REPO_ROOT}/}"
+elif [[ ! "$DIRECTIVE_DIR" = /* ]]; then
+  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
   DIRECTIVE_DIR_ABS="${REPO_ROOT}/${DIRECTIVE_DIR}"
 else
+  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
   DIRECTIVE_DIR_ABS="$DIRECTIVE_DIR"
-  # Make relative for output
   DIRECTIVE_DIR="${DIRECTIVE_DIR#${REPO_ROOT}/}"
 fi
 
@@ -227,85 +239,106 @@ check_directive_field() {
   add_artifact "directive.json:${field_path}"
 }
 
+# Check a pipeline step is completed or skipped
+check_step_completed_or_skipped() {
+  local step_id="$1"   # the step that must be completed
+
+  # First check if the step has a completed status in directive.json
+  local status
+  status=$(jq -r ".pipeline.\"${step_id}\".status // empty" "$DIRECTIVE_JSON" 2>/dev/null)
+
+  if [[ "$status" == "completed" || "$status" == "skipped" ]]; then
+    add_artifact "directive.json:pipeline.${step_id}.status"
+    return 0
+  fi
+
+  # Check .skip marker for weight-conditional steps
+  if is_skippable "$step_id"; then
+    local skip_marker="${DIRECTIVE_DIR_ABS}/${step_id}.skip"
+    if [[ -f "$skip_marker" ]]; then
+      add_artifact "${DIRECTIVE_DIR}/${step_id}.skip"
+      return 0
+    fi
+    # Skippable but not completed/skipped — still valid (step was legitimately not run)
+    add_artifact "${DIRECTIVE_DIR}/${step_id} (skippable, not yet run)"
+    return 0
+  fi
+
+  add_violation "prerequisite_incomplete" "Prerequisite step '${step_id}' not completed (status: ${status:-missing}) (weight: ${WEIGHT})"
+  return 0
+}
+
 # ---------------------------------------------------------------------------
 # Gate Definitions: what each step requires before it can run
 # ---------------------------------------------------------------------------
-# The NEXT step's gate validates the PREVIOUS step's artifact.
-# Chain: triage -> read -> context -> challenge -> brainstorm -> plan -> audit ->
-#        approve -> project-brainstorm -> setup -> execute -> review-gate -> wrapup -> completion
-# Note: approve runs BEFORE project-brainstorm (project-brainstorm depends on approval).
+# The gate for each step checks that its PREREQUISITE step is completed.
+#
+# Pipeline order (from SKILL.md):
+#   triage → checkpoint → read → context → audit → brainstorm → clarification →
+#   plan → approve → project-brainstorm → setup → execute → review-gate → wrapup → completion
 # ---------------------------------------------------------------------------
 
-gate_read() {
+gate_checkpoint() {
   # Requires: triage completed (weight set in directive.json)
   check_directive_field ".weight" "triage"
   check_directive_field ".pipeline.triage.status" "triage"
 }
 
+gate_read() {
+  # Requires: checkpoint completed (or skipped — checkpoint just checks for resume)
+  # Checkpoint is not skippable per se but is always fast — require triage at minimum
+  check_directive_field ".weight" "triage"
+  check_directive_field ".pipeline.triage.status" "triage"
+}
+
 gate_context() {
   # Requires: read completed
-  check_directive_field ".pipeline.read.status" "read"
+  check_step_completed_or_skipped "read"
 }
 
-gate_brainstorm() {
+gate_audit() {
   # Requires: context completed
-  check_directive_field ".pipeline.context.status" "context"
+  check_step_completed_or_skipped "context"
 }
 
-gate_plan() {
-  # Requires: brainstorm completed (or .skip for lightweight)
-  check_file "brainstorm.md" "brainstorm"
+gate_brainstorm() {
+  # Requires: audit completed (or skipped — audit always runs for all weights)
+  check_step_completed_or_skipped "audit"
 }
 
-gate_audit() {
-  # Requires: plan completed (plan.json exists)
-  check_json "plan.json" "plan" ".projects"
+gate_clarification() {
+  # Requires: brainstorm completed (or skipped for lightweight/medium)
+  check_step_completed_or_skipped "brainstorm"
 }
 
-gate_approve() {
-  # Requires: audit completed (audit artifact exists) + plan.json
-  # Audit can produce audit.md, investigation.md, or conflicts-audit.md
-  local found=false
-  for f in audit.md investigation.md conflicts-audit.md; do
-    if [[ -f "${DIRECTIVE_DIR_ABS}/${f}" ]]; then
-      add_artifact "${DIRECTIVE_DIR}/${f}"
-      found=true
-      break
-    fi
-  done
-  if [[ "$found" == "false" ]]; then
-    if is_skippable "audit"; then
-      local skip_marker="${DIRECTIVE_DIR_ABS}/audit.skip"
-      if [[ -f "$skip_marker" ]]; then
-        add_artifact "${DIRECTIVE_DIR}/audit.skip"
-      else
-        add_violation "missing_artifact" "Missing audit artifact: audit.md (weight: ${WEIGHT})"
-      fi
-    else
-      add_violation "missing_artifact" "Missing audit artifact: audit.md (weight: ${WEIGHT})"
-    fi
-  fi
-
-  # Also require plan.json
-  check_json "plan.json" "plan" ".projects"
+gate_plan() {
+  # Requires: clarification completed (or skipped)
+  # Clarification is auto-approved for lightweight/medium but still produces a
+  # pipeline.clarification.status entry. Check it completed or was skipped.
+  check_step_completed_or_skipped "clarification"
 }
 
-gate_challenge() {
-  # Requires: context completed
-  check_directive_field ".pipeline.context.status" "context"
+gate_approve() {
+  # Requires: plan completed (plan.json exists with .projects)
+  check_json "plan.json" "plan" ".projects"
+  check_step_completed_or_skipped "plan"
 }
 
 gate_project_brainstorm() {
   # Requires: approve completed (approve runs before project-brainstorm)
-  check_directive_field ".pipeline.approve.status" "approve"
+  check_step_completed_or_skipped "approve"
   # Also require plan.json (input to brainstorm)
   check_json "plan.json" "plan" ".projects"
 }
 
+gate_setup() {
+  # Requires: project-brainstorm completed
+  check_step_completed_or_skipped "project-brainstorm"
+}
+
 gate_execute() {
-  # Requires: project-brainstorm completed (project.json with tasks exists)
-  # Also requires approval
-  check_directive_field ".pipeline.approve.status" "approve"
+  # Requires: setup completed + project.json(s) with tasks exist
+  check_step_completed_or_skipped "setup"
 
   # Check project.json(s) exist with tasks (output of project-brainstorm)
   local found_project=false
@@ -318,16 +351,7 @@ gate_execute() {
     done
   fi
   if [[ "$found_project" == "false" ]]; then
-    if is_skippable "project-brainstorm"; then
-      local skip_marker="${DIRECTIVE_DIR_ABS}/project-brainstorm.skip"
-      if [[ -f "$skip_marker" ]]; then
-        add_artifact "${DIRECTIVE_DIR}/project-brainstorm.skip"
-      else
-        add_violation "missing_artifact" "No projects/*/project.json found (project-brainstorm not completed)"
-      fi
-    else
-      add_violation "missing_artifact" "No projects/*/project.json found (project-brainstorm not completed)"
-    fi
+    add_violation "missing_artifact" "No projects/*/project.json found (project-brainstorm not completed)"
   fi
 
   # Per-task gate: if task-id provided, check that specific task exists in a project
@@ -349,12 +373,10 @@ gate_execute() {
   fi
 }
 
-gate_setup() {
-  # Requires: project-brainstorm completed (or skipped for lightweight)
-  check_directive_field ".pipeline.approve.status" "approve"
-}
-
 gate_review_gate() {
+  # Requires: execute completed
+  check_step_completed_or_skipped "execute"
+
   # Per-task gate: requires build-{task-id}.md exists for the task being reviewed
   if [[ -n "$TASK_ID" ]]; then
     # Find which project this task belongs to
@@ -381,6 +403,12 @@ gate_review_gate() {
         local task_ids
         task_ids=$(jq -r '.tasks[].id' "${pdir}project.json" 2>/dev/null)
         for tid in $task_ids; do
+          local task_status
+          task_status=$(jq -r --arg tid "$tid" '.tasks[] | select(.id == $tid) | .status' "${pdir}project.json" 2>/dev/null)
+          # Skipped/blocked tasks don't need build artifacts
+          if [[ "$task_status" == "skipped" || "$task_status" == "blocked" ]]; then
+            continue
+          fi
           if [[ ! -f "${pdir}build-${tid}.md" ]]; then
             add_violation "missing_artifact" "Missing build artifact: projects/${project_id}/build-${tid}.md"
           else
@@ -393,7 +421,9 @@ gate_review_gate() {
 }
 
 gate_wrapup() {
-  # Requires: all tasks have review-{task-id}.md
+  # Requires: review-gate completed + all non-skipped tasks have review artifacts
+  check_step_completed_or_skipped "review-gate"
+
   for pdir in "${DIRECTIVE_DIR_ABS}"/projects/*/; do
     if [[ -f "${pdir}project.json" ]]; then
       local project_id
@@ -418,22 +448,146 @@ gate_wrapup() {
 }
 
 gate_completion() {
-  # Requires: digest.md exists
-  check_file "digest.md" "wrapup"
+  # Requires: wrapup completed + digest file exists at wrapup.digest_path
+  check_step_completed_or_skipped "wrapup"
+
+  # Check that the digest file exists. Wrapup writes to .context/reports/{name}-{date}.md
+  # and stores the path in directive.json at wrapup.digest_path
+  local digest_path
+  digest_path=$(jq -r '.wrapup.digest_path // empty' "$DIRECTIVE_JSON" 2>/dev/null)
+
+  if [[ -n "$digest_path" ]]; then
+    # digest_path may be relative to repo root or absolute
+    local full_digest_path
+    if [[ "$digest_path" = /* ]]; then
+      full_digest_path="$digest_path"
+    else
+      full_digest_path="${REPO_ROOT}/${digest_path}"
+    fi
+    if [[ -f "$full_digest_path" ]]; then
+      add_artifact "$digest_path"
+    else
+      add_violation "missing_artifact" "Digest file not found at wrapup.digest_path: ${digest_path}"
+    fi
+  else
+    # Fallback: check for report field (older convention: report = filename without extension)
+    local report
+    report=$(jq -r '.report // empty' "$DIRECTIVE_JSON" 2>/dev/null)
+    if [[ -n "$report" ]]; then
+      local report_path=".context/reports/${report}.md"
+      local full_report_path="${REPO_ROOT}/${report_path}"
+      if [[ -f "$full_report_path" ]]; then
+        add_artifact "$report_path"
+      else
+        add_violation "missing_artifact" "Digest file not found: ${report_path} (from directive.json .report)"
+      fi
+    else
+      add_violation "missing_field" "directive.json missing wrapup.digest_path (digest not written by wrapup step)"
+    fi
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Pipeline state consistency check
+# ---------------------------------------------------------------------------
+# Verifies that directive.json.current_step matches the target step and that
+# ALL prior steps in the pipeline have status "completed" or "skipped".
+# This catches the failure mode where the orchestrator executes steps but
+# forgets to update directive.json — a mechanical enforcement, not advisory.
+
+FULL_PIPELINE_ORDER=(triage checkpoint read context audit brainstorm clarification plan approve project-brainstorm setup execute review-gate wrapup completion)
+
+check_pipeline_state_consistency() {
+  local target="$1"
+
+  # 1. Check current_step matches target
+  local current_step
+  current_step=$(jq -r '.current_step // empty' "$DIRECTIVE_JSON" 2>/dev/null)
+
+  if [[ -n "$current_step" && "$current_step" != "$target" ]]; then
+    # Find positions of current_step and target in pipeline order
+    local current_pos=-1
+    local target_pos=-1
+    for i in "${!FULL_PIPELINE_ORDER[@]}"; do
+      if [[ "${FULL_PIPELINE_ORDER[$i]}" == "$current_step" ]]; then
+        current_pos=$i
+      fi
+      if [[ "${FULL_PIPELINE_ORDER[$i]}" == "$target" ]]; then
+        target_pos=$i
+      fi
+    done
+
+    # Only flag if target is AHEAD of current_step (steps were skipped)
+    if [[ $target_pos -gt $current_pos && $current_pos -ge 0 ]]; then
+      # Build list of steps between current_step and target that need updating
+      local stale_steps=""
+      for (( j=current_pos; j<target_pos; j++ )); do
+        local step_id="${FULL_PIPELINE_ORDER[$j]}"
+        local step_status
+        step_status=$(jq -r ".pipeline.\"${step_id}\".status // \"pending\"" "$DIRECTIVE_JSON" 2>/dev/null)
+        if [[ "$step_status" != "completed" && "$step_status" != "skipped" ]]; then
+          if [[ -n "$stale_steps" ]]; then
+            stale_steps="${stale_steps}, ${step_id}"
+          else
+            stale_steps="${step_id}"
+          fi
+        fi
+      done
+
+      if [[ -n "$stale_steps" ]]; then
+        add_violation "stale_pipeline_state" "directive.json.current_step is '${current_step}' but entering '${target}'. These steps were executed but not updated in directive.json: [${stale_steps}]. Update their pipeline status to 'completed' with output.summary, then set current_step to '${target}'."
+      fi
+    fi
+  fi
+
+  # 2. Check ALL prior steps have status completed or skipped
+  for step_id in "${FULL_PIPELINE_ORDER[@]}"; do
+    # Stop when we reach the target step
+    if [[ "$step_id" == "$target" ]]; then
+      break
+    fi
+
+    local step_status
+    step_status=$(jq -r ".pipeline.\"${step_id}\".status // \"pending\"" "$DIRECTIVE_JSON" 2>/dev/null)
+
+    if [[ "$step_status" == "completed" || "$step_status" == "skipped" ]]; then
+      continue
+    fi
+
+    # Check if this step is skippable for this weight
+    if is_skippable "$step_id"; then
+      continue
+    fi
+
+    # Step is not completed, not skipped, and not skippable — violation
+    local has_output
+    has_output=$(jq -r ".pipeline.\"${step_id}\".output.summary // empty" "$DIRECTIVE_JSON" 2>/dev/null)
+    if [[ -z "$has_output" ]]; then
+      add_violation "step_not_persisted" "Step '${step_id}' has status '${step_status}' with no output.summary. It was likely executed but not persisted to directive.json. Set pipeline.${step_id}.status to 'completed' with output.summary before proceeding."
+    else
+      add_violation "step_incomplete" "Step '${step_id}' has status '${step_status}' (expected 'completed' or 'skipped')"
+    fi
+  done
 }
 
+# Run consistency check before per-step gates (skip for triage — first step)
+if [[ "$TARGET_STEP" != "triage" ]]; then
+  check_pipeline_state_consistency "$TARGET_STEP"
+fi
+
 # ---------------------------------------------------------------------------
 # Run the gate for the target step
 # ---------------------------------------------------------------------------
 
 case "$TARGET_STEP" in
   triage)             ;; # No prerequisites for first step
+  checkpoint)         gate_checkpoint ;;
   read)               gate_read ;;
   context)            gate_context ;;
-  challenge)          gate_challenge ;;
+  audit)              gate_audit ;;
   brainstorm)         gate_brainstorm ;;
+  clarification)      gate_clarification ;;
   plan)               gate_plan ;;
-  audit)              gate_audit ;;
   approve)            gate_approve ;;
   project-brainstorm) gate_project_brainstorm ;;
   setup)              gate_setup ;;

package/.claude/hooks/validate-project-json.sh

@@ -12,6 +12,7 @@
 #
 # Exit 0, no output = valid
 # Exit 0, JSON output = validation result (valid: true/false, violations: [...])
+# Exit 1 = validation failure (violations found)
 
 set -euo pipefail
 
@@ -44,7 +45,7 @@ violations=()
 if [[ ! -f "$PROJECT_PATH" ]]; then
   violations+=("project.json does not exist at ${PROJECT_PATH}. The approve step must create it before execution begins.")
   echo "{\"valid\": false, \"violations\": $(printf '%s\n' "${violations[@]}" | jq -R . | jq -s .)}"
-  exit 0
+  exit 1
 fi
 
 # Validate required fields
@@ -102,8 +103,42 @@ for i in $(seq 0 $((TASK_COUNT - 1))); do
   fi
 done
 
+## DOD completion check: completed tasks must have at least one dod[].met = true
+for i in $(seq 0 $((TASK_COUNT - 1))); do
+  TASK_ID=$(jq -r ".tasks[$i].id // \"task-$i\"" "$PROJECT_PATH" 2>/dev/null)
+  TASK_STATUS=$(jq -r ".tasks[$i].status // \"\"" "$PROJECT_PATH" 2>/dev/null)
+  if [[ "$TASK_STATUS" == "completed" ]]; then
+    # Count how many DOD items have met=true
+    MET_COUNT=$(jq "[.tasks[$i].dod[]? | select(.met == true)] | length" "$PROJECT_PATH" 2>/dev/null || echo "0")
+    TOTAL_DOD=$(jq ".tasks[$i].dod | length" "$PROJECT_PATH" 2>/dev/null || echo "0")
+    if [[ "$TOTAL_DOD" -gt 0 && "$MET_COUNT" -eq 0 ]]; then
+      violations+=("tasks[$TASK_ID] is marked completed but ALL dod items have met=false — task was completed without DOD verification")
+    fi
+  fi
+done
+
+## Browser test check: if browser_test is true, warn if no design-review.md
+warnings=()
+BROWSER_TEST=$(jq -r '.browser_test // false' "$PROJECT_PATH" 2>/dev/null)
+if [[ "$BROWSER_TEST" == "true" ]]; then
+  PROJECT_DIR=$(dirname "$PROJECT_PATH")
+  if [[ ! -f "${PROJECT_DIR}/design-review.md" ]]; then
+    warnings+=("browser_test is true but no design-review.md found in ${PROJECT_DIR} — visual review may not have been recorded")
+  fi
+fi
+
 if [[ ${#violations[@]} -eq 0 ]]; then
-  echo '{"valid": true, "violations": []}'
+  if [[ ${#warnings[@]} -gt 0 ]]; then
+    echo "{\"valid\": true, \"violations\": [], \"warnings\": $(printf '%s\n' "${warnings[@]}" | jq -R . | jq -s .)}"
+  else
+    echo '{"valid": true, "violations": []}'
+  fi
+  exit 0
 else
-  echo "{\"valid\": false, \"violations\": $(printf '%s\n' "${violations[@]}" | jq -R . | jq -s .)}"
+  if [[ ${#warnings[@]} -gt 0 ]]; then
+    echo "{\"valid\": false, \"violations\": $(printf '%s\n' "${violations[@]}" | jq -R . | jq -s .), \"warnings\": $(printf '%s\n' "${warnings[@]}" | jq -R . | jq -s .)}"
+  else
+    echo "{\"valid\": false, \"violations\": $(printf '%s\n' "${violations[@]}" | jq -R . | jq -s .)}"
+  fi
+  exit 1
 fi

package/.claude/hooks/validate-reviews.sh

@@ -7,10 +7,10 @@
 # Usage: echo '{"directive_dir":".context/directives/my-dir","project_id":"my-project"}' | ./validate-reviews.sh
 #
 # Checks project.json for completed tasks and verifies that:
-# 1. Tasks with "review" in their phases array were actually reviewed
-#    (at least one DOD criterion evidence of external review)
-# 2. No completed task has ALL dod items marked true with zero reviewer spawns
-#    (self-certification detection)
+# 1. Project has reviewers assigned (existing check)
+# 2. Review artifact files exist: review-{task-id}.md in the project directory
+# 3. Task agent != project reviewers (catches self-review)
+# 4. Self-certification heuristic (all DOD met with no review artifact)
 #
 # Exit 0, JSON output = validation result (valid: true/false, violations: [...])
 
@@ -40,10 +40,14 @@ if [[ ! -f "$PROJECT_PATH" ]]; then
   exit 0
 fi
 
+# Derive project directory from project.json path
+PROJECT_DIR=$(dirname "$PROJECT_PATH")
+
 violations=()
 
-# Get project-level reviewers
-PROJECT_REVIEWERS=$(jq -r '.reviewers | length' "$PROJECT_PATH" 2>/dev/null || echo "0")
+# Get project-level reviewers as newline-separated list (bash 3.2 safe — no associative arrays)
+PROJECT_REVIEWERS_COUNT=$(jq -r '.reviewers | length' "$PROJECT_PATH" 2>/dev/null || echo "0")
+PROJECT_REVIEWERS_LIST=$(jq -r '.reviewers[]?' "$PROJECT_PATH" 2>/dev/null || echo "")
 
 TASK_COUNT=$(jq '.tasks | length' "$PROJECT_PATH" 2>/dev/null || echo "0")
 
@@ -60,16 +64,51 @@ for i in $(seq 0 $((TASK_COUNT - 1))); do
   HAS_REVIEW_PHASE=$(jq -r ".tasks[$i].phases | if . then (. | index(\"review\")) else null end" "$PROJECT_PATH" 2>/dev/null)
 
   if [[ "$HAS_REVIEW_PHASE" != "null" && "$HAS_REVIEW_PHASE" != "" ]]; then
-    # Task has a review phase and is completed — verify project has reviewers
-    if [[ "$PROJECT_REVIEWERS" -eq 0 ]]; then
+
+    # --- Check 1: Project has reviewers assigned ---
+    if [[ "$PROJECT_REVIEWERS_COUNT" -eq 0 ]]; then
       violations+=("Task '${TASK_ID}' is completed with review phase but has NO reviewers assigned")
     fi
 
-    # Check if ALL DOD criteria are met — flag if the task was likely self-certified
-    # (This is a heuristic: if all DOD = true but no review artifact directory exists, suspicious)
+    # --- Check 2: Review artifact file exists ---
+    # 09-execute-projects.md specifies: review-{task-id}.md or build-{task-id}.md
+    REVIEW_ARTIFACT="${PROJECT_DIR}/review-${TASK_ID}.md"
+    BUILD_ARTIFACT="${PROJECT_DIR}/build-${TASK_ID}.md"
+    if [[ ! -f "$REVIEW_ARTIFACT" && ! -f "$BUILD_ARTIFACT" ]]; then
+      violations+=("Task '${TASK_ID}' has no review artifact (expected review-${TASK_ID}.md or build-${TASK_ID}.md in ${PROJECT_DIR})")
+    fi
+
+    # --- Check 3: Self-review detection (task agent == project reviewer) ---
+    # Get the task-level agent (could be a string or array)
+    TASK_AGENT=$(jq -r ".tasks[$i].agent | if type == \"array\" then .[0] else . end // empty" "$PROJECT_PATH" 2>/dev/null)
+
+    if [[ -n "$TASK_AGENT" && -n "$PROJECT_REVIEWERS_LIST" ]]; then
+      # Check if the task agent appears in the project reviewers list
+      SELF_REVIEW="false"
+      while IFS= read -r reviewer; do
+        if [[ -n "$reviewer" && "$reviewer" = "$TASK_AGENT" ]]; then
+          SELF_REVIEW="true"
+          break
+        fi
+      done <<EOF
+$PROJECT_REVIEWERS_LIST
+EOF
+      if [[ "$SELF_REVIEW" = "true" ]]; then
+        # Self-review: task builder is also a reviewer — only flag if they are the ONLY reviewer
+        if [[ "$PROJECT_REVIEWERS_COUNT" -eq 1 ]]; then
+          violations+=("Task '${TASK_ID}' builder ('${TASK_AGENT}') is the only project reviewer — self-review detected")
+        fi
+      fi
+    fi
+
+    # --- Check 4: Self-certification heuristic ---
+    # All DOD met + no review artifact = likely self-certified
     DOD_COUNT=$(jq ".tasks[$i].dod | length" "$PROJECT_PATH" 2>/dev/null || echo "0")
     DOD_MET=$(jq "[.tasks[$i].dod[] | select(.met == true)] | length" "$PROJECT_PATH" 2>/dev/null || echo "0")
-    DOD_UNMET=$(jq "[.tasks[$i].dod[] | select(.met == false)] | length" "$PROJECT_PATH" 2>/dev/null || echo "0")
+
+    if [[ "$DOD_COUNT" -gt 0 && "$DOD_MET" -eq "$DOD_COUNT" && ! -f "$REVIEW_ARTIFACT" ]]; then
+      violations+=("Task '${TASK_ID}' has ALL DOD criteria met but no review artifact — possible self-certification")
+    fi
 
     # Check for VISUAL GATE criteria that require browser verification
     VISUAL_GATES=$(jq -r "[.tasks[$i].dod[] | select(.criterion | test(\"VISUAL GATE|browser screenshot|verified by human\"; \"i\")) | select(.met == true)] | length" "$PROJECT_PATH" 2>/dev/null || echo "0")