gru-ai 0.1.0 → 0.2.0

package/.claude/hooks/detect-stale-docs.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# detect-stale-docs.sh — Post-directive hook to detect potentially stale documentation
+#
+# After a directive completes, scans .context/ and .claude/ docs for references
+# to files that were modified in the directive. If the doc itself was NOT modified,
+# it is flagged as potentially stale.
+#
+# Staleness heuristic:
+#   "References a file" = doc contains a literal file path substring (grep -F)
+#   "Stale" = doc references a file modified in the directive, but the doc
+#             itself was NOT modified in the same directive
+#
+# Usage:
+#   ./detect-stale-docs.sh file1.ts file2.tsx ...
+#   ./detect-stale-docs.sh --from-diff <base-branch>
+#   echo "file1.ts\nfile2.ts" | ./detect-stale-docs.sh --stdin
+#
+# Output: list of potentially stale docs with the files they reference
+# Exit 0 always (output is informational, not blocking)
+
+set -euo pipefail
+
+# Anchor to repo root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo "Error: not in a git repo" >&2
+  exit 1
+}
+cd "$REPO_ROOT"
+
+# --- Collect modified files ---
+MODIFIED_FILES=()
+
+if [[ "${1:-}" == "--from-diff" ]]; then
+  # Get modified files from git diff against a base branch
+  BASE_BRANCH="${2:-main}"
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && MODIFIED_FILES+=("$f")
+  done < <(git diff --name-only "$BASE_BRANCH" 2>/dev/null)
+elif [[ "${1:-}" == "--stdin" ]]; then
+  # Read file list from stdin
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && MODIFIED_FILES+=("$f")
+  done
+else
+  # Read file list from arguments
+  for f in "$@"; do
+    [[ -n "$f" ]] && MODIFIED_FILES+=("$f")
+  done
+fi
+
+if [[ ${#MODIFIED_FILES[@]} -eq 0 ]]; then
+  exit 0  # No modified files — nothing to check
+fi
+
+# --- Build newline-separated list of modified docs (for exclusion) ---
+# Compatible with bash 3.x (no associative arrays)
+MODIFIED_DOCS=""
+for f in "${MODIFIED_FILES[@]}"; do
+  case "$f" in
+    .context/*.md|.claude/*.md)
+      MODIFIED_DOCS="${MODIFIED_DOCS}${f}"$'\n'
+      ;;
+  esac
+done
+
+# --- Create temp file with patterns (one per line) for grep -f ---
+PATTERNS_FILE=$(mktemp)
+trap 'rm -f "$PATTERNS_FILE"' EXIT
+printf '%s\n' "${MODIFIED_FILES[@]}" > "$PATTERNS_FILE"
+
+# --- Phase 1: Find all candidate docs in a single grep pass ---
+# Use grep -Fl -f to find all .md files that contain ANY modified file path.
+# This is much faster than iterating: one grep invocation covers all docs + patterns.
+CANDIDATE_DOCS=()
+while IFS= read -r doc; do
+  [[ -n "$doc" ]] && CANDIDATE_DOCS+=("$doc")
+done < <(
+  find .context/ .claude/ -name '*.md' -type f 2>/dev/null \
+    | grep -v '/worktrees/' \
+    | grep -v 'node_modules' \
+    | xargs grep -Fl -f "$PATTERNS_FILE" 2>/dev/null || true
+)
+
+if [[ ${#CANDIDATE_DOCS[@]} -eq 0 ]]; then
+  echo "No potentially stale docs detected."
+  exit 0
+fi
+
+# --- Phase 2: For each candidate, determine which files it references ---
+# Only runs on the (small) set of docs that matched in Phase 1.
+# Also filters out docs that were themselves modified (zero false positives).
+
+STALE_RESULTS=()
+
+for doc in "${CANDIDATE_DOCS[@]}"; do
+  # Skip docs that were also modified in this directive
+  if echo "$MODIFIED_DOCS" | grep -qxF "$doc" 2>/dev/null; then
+    continue
+  fi
+
+  # Determine which specific modified files this doc references
+  REFERENCED=()
+  for modified in "${MODIFIED_FILES[@]}"; do
+    if grep -qF "$modified" "$doc" 2>/dev/null; then
+      REFERENCED+=("$modified")
+    fi
+  done
+
+  if [[ ${#REFERENCED[@]} -gt 0 ]]; then
+    REFS_STR=$(printf '%s, ' "${REFERENCED[@]}")
+    REFS_STR="${REFS_STR%, }"  # trim trailing comma+space
+    STALE_RESULTS+=("$doc -> references modified: $REFS_STR")
+  fi
+done
+
+# --- Output ---
+if [[ ${#STALE_RESULTS[@]} -eq 0 ]]; then
+  echo "No potentially stale docs detected."
+  exit 0
+fi
+
+echo "## Potentially Stale Docs"
+echo ""
+echo "The following docs reference files that were modified but were not themselves updated:"
+echo ""
+for result in "${STALE_RESULTS[@]}"; do
+  echo "- $result"
+done
+echo ""
+echo "Consider reviewing these docs for accuracy."
+
+exit 0

package/.claude/hooks/tests/gate/01-valid-lightweight-skip/approve.skip

@@ -0,0 +1 @@
+Skipped: lightweight directive does not require approval

package/.claude/hooks/tests/gate/01-valid-lightweight-skip/audit.skip

@@ -0,0 +1 @@
+Skipped: lightweight directive does not require audit

package/.claude/hooks/tests/gate/01-valid-lightweight-skip/brainstorm.skip

@@ -0,0 +1 @@
+Skipped: lightweight directive does not require brainstorm

package/.claude/hooks/tests/gate/01-valid-lightweight-skip/directive.json

@@ -0,0 +1,12 @@
+{
+  "id": "test-lightweight",
+  "title": "Test lightweight directive",
+  "status": "in_progress",
+  "weight": "lightweight",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "read": { "status": "completed" },
+    "context": { "status": "completed" },
+    "approve": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/01-valid-lightweight-skip/project-brainstorm.skip

@@ -0,0 +1 @@
+Skipped: lightweight directive does not require project brainstorm

package/.claude/hooks/tests/gate/02-valid-heavyweight/audit.md

@@ -0,0 +1,2 @@
+# Audit Results
+Technical audit for heavyweight directive test.

package/.claude/hooks/tests/gate/02-valid-heavyweight/brainstorm.md

@@ -0,0 +1,2 @@
+# Brainstorm Output
+This is a test brainstorm document for the heavyweight directive.

package/.claude/hooks/tests/gate/02-valid-heavyweight/digest.md

@@ -0,0 +1,2 @@
+# Digest
+Test heavyweight directive completed.

package/.claude/hooks/tests/gate/02-valid-heavyweight/directive.json

@@ -0,0 +1,12 @@
+{
+  "id": "test-heavyweight",
+  "title": "Test heavyweight directive",
+  "status": "in_progress",
+  "weight": "heavyweight",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "read": { "status": "completed" },
+    "context": { "status": "completed" },
+    "approve": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/02-valid-heavyweight/plan.json

@@ -0,0 +1,14 @@
+{
+  "goal": "Test heavyweight",
+  "projects": [
+    {
+      "id": "test-project",
+      "title": "Test project",
+      "cast": { "builder": "riley", "auditor": "sarah", "reviewers": ["sarah"] },
+      "tasks": [
+        { "id": "task-1", "title": "First task" },
+        { "id": "task-2", "title": "Second task" }
+      ]
+    }
+  ]
+}

package/.claude/hooks/tests/gate/02-valid-heavyweight/projects/test-project/build-task-1.md

@@ -0,0 +1,2 @@
+# Build Report: task-1
+Build completed successfully.

package/.claude/hooks/tests/gate/02-valid-heavyweight/projects/test-project/build-task-2.md

@@ -0,0 +1,2 @@
+# Build Report: task-2
+Build completed successfully.

package/.claude/hooks/tests/gate/02-valid-heavyweight/projects/test-project/project.json

@@ -0,0 +1,9 @@
+{
+  "id": "test-project",
+  "title": "Test project",
+  "status": "in_progress",
+  "tasks": [
+    { "id": "task-1", "title": "First task", "status": "completed" },
+    { "id": "task-2", "title": "Second task", "status": "completed" }
+  ]
+}

package/.claude/hooks/tests/gate/02-valid-heavyweight/projects/test-project/review-task-1.md

@@ -0,0 +1,2 @@
+# Review: task-1
+Review passed.

package/.claude/hooks/tests/gate/02-valid-heavyweight/projects/test-project/review-task-2.md

@@ -0,0 +1,2 @@
+# Review: task-2
+Review passed.

package/.claude/hooks/tests/gate/03-fail-missing-brainstorm/directive.json

@@ -0,0 +1,11 @@
+{
+  "id": "test-no-brainstorm",
+  "title": "Test missing brainstorm for heavyweight",
+  "status": "in_progress",
+  "weight": "heavyweight",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "read": { "status": "completed" },
+    "context": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/04-fail-missing-review/directive.json

@@ -0,0 +1,12 @@
+{
+  "id": "test-no-review",
+  "title": "Test missing review artifacts",
+  "status": "in_progress",
+  "weight": "medium",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "read": { "status": "completed" },
+    "context": { "status": "completed" },
+    "approve": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/04-fail-missing-review/projects/test-project/build-task-a.md

@@ -0,0 +1,2 @@
+# Build: task-a
+Done.

package/.claude/hooks/tests/gate/04-fail-missing-review/projects/test-project/build-task-b.md

@@ -0,0 +1,2 @@
+# Build: task-b
+Done.

package/.claude/hooks/tests/gate/04-fail-missing-review/projects/test-project/project.json

@@ -0,0 +1,9 @@
+{
+  "id": "test-project",
+  "title": "Test project",
+  "status": "in_progress",
+  "tasks": [
+    { "id": "task-a", "title": "Task A", "status": "completed" },
+    { "id": "task-b", "title": "Task B", "status": "completed" }
+  ]
+}

package/.claude/hooks/tests/gate/04-fail-missing-review/projects/test-project/review-task-a.md

@@ -0,0 +1,2 @@
+# Review: task-a
+Passed.

package/.claude/hooks/tests/gate/05-valid-completion/digest.md

@@ -0,0 +1,2 @@
+# Digest
+Strategic directive completed successfully.

package/.claude/hooks/tests/gate/05-valid-completion/directive.json

@@ -0,0 +1,17 @@
+{
+  "id": "test-completion",
+  "title": "Test completion gate",
+  "status": "awaiting_completion",
+  "weight": "strategic",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "read": { "status": "completed" },
+    "context": { "status": "completed" },
+    "brainstorm": { "status": "completed" },
+    "plan": { "status": "completed" },
+    "audit": { "status": "completed" },
+    "approve": { "status": "completed" },
+    "execute": { "status": "completed" },
+    "wrapup": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/06-fail-missing-build/directive.json

@@ -0,0 +1,10 @@
+{
+  "id": "test-no-build",
+  "title": "Test missing build artifact for review gate",
+  "status": "in_progress",
+  "weight": "medium",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "approve": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/06-fail-missing-build/projects/test-project/project.json

@@ -0,0 +1,8 @@
+{
+  "id": "test-project",
+  "title": "Test project",
+  "status": "in_progress",
+  "tasks": [
+    { "id": "widget", "title": "Build widget", "status": "in_progress" }
+  ]
+}

package/.claude/hooks/tests/gate/07-valid-medium-full/audit.md

@@ -0,0 +1,2 @@
+# Audit
+Medium directive audit.

package/.claude/hooks/tests/gate/07-valid-medium-full/brainstorm.md

@@ -0,0 +1,2 @@
+# Brainstorm
+Medium directive brainstorm.

package/.claude/hooks/tests/gate/07-valid-medium-full/directive.json

@@ -0,0 +1,12 @@
+{
+  "id": "test-medium-full",
+  "title": "Test medium with all artifacts",
+  "status": "in_progress",
+  "weight": "medium",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "read": { "status": "completed" },
+    "context": { "status": "completed" },
+    "approve": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/07-valid-medium-full/plan.json

@@ -0,0 +1,10 @@
+{
+  "goal": "Test medium",
+  "projects": [
+    {
+      "id": "test-project",
+      "title": "Test project",
+      "tasks": [{ "id": "t1", "title": "Task 1" }]
+    }
+  ]
+}

package/.claude/hooks/tests/gate/07-valid-medium-full/projects/test-project/project.json

@@ -0,0 +1,8 @@
+{
+  "id": "test-project",
+  "title": "Test project",
+  "status": "in_progress",
+  "tasks": [
+    { "id": "t1", "title": "Task 1", "status": "pending" }
+  ]
+}

package/.claude/hooks/tests/gate/08-fail-invalid-json/brainstorm.md

@@ -0,0 +1,2 @@
+# Brainstorm
+Test brainstorm.

package/.claude/hooks/tests/gate/08-fail-invalid-json/directive.json

@@ -0,0 +1,10 @@
+{
+  "id": "test-invalid-json",
+  "title": "Test invalid JSON in plan",
+  "status": "in_progress",
+  "weight": "medium",
+  "pipeline": {
+    "triage": { "status": "completed" },
+    "context": { "status": "completed" }
+  }
+}

package/.claude/hooks/tests/gate/08-fail-invalid-json/plan.json

@@ -0,0 +1 @@
+{ this is not valid json !!!

package/.claude/hooks/tests/gate/09-malformed-directive-json/directive.json

@@ -0,0 +1 @@
+{"broken

package/.claude/hooks/tests/gate/run-tests.sh

@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+# run-tests.sh — Test runner for validate-gate.sh
+#
+# Exercises all fixture directories and reports pass/fail.
+# Exit 0 when all tests pass, exit 1 with details on failure.
+#
+# Usage: ./run-tests.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GATE_SCRIPT="$(cd "$SCRIPT_DIR/../.." && pwd)/validate-gate.sh"
+PASS_COUNT=0
+FAIL_COUNT=0
+FAILURES=()
+
+# Colors (if terminal supports them)
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m' # No Color
+
+run_test() {
+  local name="$1"
+  local fixture_dir="$2"
+  local target_step="$3"
+  local expect_valid="$4"  # "true" or "false"
+  local extra_args="${5:-}"
+  local expect_violation_substr="${6:-}"
+
+  # Make a working copy so directive.json writes don't pollute fixtures
+  local tmpdir
+  tmpdir=$(mktemp -d)
+  cp -R "$fixture_dir/" "$tmpdir/"
+
+  local output
+  if [[ -n "$extra_args" ]]; then
+    output=$("$GATE_SCRIPT" "$tmpdir" "$target_step" "$extra_args" 2>&1) || true
+  else
+    output=$("$GATE_SCRIPT" "$tmpdir" "$target_step" 2>&1) || true
+  fi
+
+  local actual_valid
+  actual_valid=$(echo "$output" | jq -r '.valid' 2>/dev/null || echo "parse_error")
+
+  local test_passed=true
+
+  if [[ "$actual_valid" != "$expect_valid" ]]; then
+    test_passed=false
+  fi
+
+  # If we expect a specific violation substring, check for it
+  if [[ -n "$expect_violation_substr" && "$expect_valid" == "false" ]]; then
+    if ! echo "$output" | jq -r '.violations[].message' 2>/dev/null | grep -q "$expect_violation_substr"; then
+      test_passed=false
+    fi
+  fi
+
+  # If gate passed (valid=true), verify it wrote to directive.json
+  if [[ "$expect_valid" == "true" && "$actual_valid" == "true" ]]; then
+    local gates_entry
+    gates_entry=$(jq -r ".gates.\"$target_step\".passed_at // empty" "$tmpdir/directive.json" 2>/dev/null)
+    if [[ -z "$gates_entry" ]]; then
+      test_passed=false
+      echo -e "  ${RED}FAIL${NC} $name — gate passed but did not write gates.$target_step to directive.json"
+      FAIL_COUNT=$((FAIL_COUNT + 1))
+      FAILURES+=("$name (gates write missing)")
+      rm -rf "$tmpdir"
+      return
+    fi
+  fi
+
+  if [[ "$test_passed" == "true" ]]; then
+    echo -e "  ${GREEN}PASS${NC} $name"
+    PASS_COUNT=$((PASS_COUNT + 1))
+  else
+    echo -e "  ${RED}FAIL${NC} $name"
+    echo "    Expected valid=$expect_valid, got valid=$actual_valid"
+    echo "    Output: $(echo "$output" | head -5)"
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    FAILURES+=("$name")
+  fi
+
+  rm -rf "$tmpdir"
+}
+
+echo ""
+echo "validate-gate.sh Test Suite"
+echo "==========================="
+echo ""
+
+# ---------------------------------------------------------------------------
+# Test 01: Valid lightweight with .skip markers
+# ---------------------------------------------------------------------------
+echo "01: Lightweight directive with .skip markers"
+
+run_test \
+  "plan gate passes with brainstorm.skip (lightweight)" \
+  "$SCRIPT_DIR/01-valid-lightweight-skip" \
+  "plan" \
+  "true"
+
+run_test \
+  "execute gate passes with approve.skip (lightweight)" \
+  "$SCRIPT_DIR/01-valid-lightweight-skip" \
+  "execute" \
+  "true"
+
+# ---------------------------------------------------------------------------
+# Test 02: Valid heavyweight — full artifact chain
+# ---------------------------------------------------------------------------
+echo ""
+echo "02: Heavyweight directive with all artifacts"
+
+run_test \
+  "plan gate passes (brainstorm.md exists)" \
+  "$SCRIPT_DIR/02-valid-heavyweight" \
+  "plan" \
+  "true"
+
+run_test \
+  "audit gate passes (plan.json exists with .projects)" \
+  "$SCRIPT_DIR/02-valid-heavyweight" \
+  "audit" \
+  "true"
+
+run_test \
+  "execute gate passes (approval in directive.json)" \
+  "$SCRIPT_DIR/02-valid-heavyweight" \
+  "execute" \
+  "true"
+
+run_test \
+  "review-gate passes for task-1 (build-task-1.md exists)" \
+  "$SCRIPT_DIR/02-valid-heavyweight" \
+  "review-gate" \
+  "true" \
+  "task-1"
+
+run_test \
+  "wrapup gate passes (all reviews exist)" \
+  "$SCRIPT_DIR/02-valid-heavyweight" \
+  "wrapup" \
+  "true"
+
+run_test \
+  "completion gate passes (digest.md exists)" \
+  "$SCRIPT_DIR/02-valid-heavyweight" \
+  "completion" \
+  "true"
+
+# ---------------------------------------------------------------------------
+# Test 03: Fail — missing brainstorm for heavyweight
+# ---------------------------------------------------------------------------
+echo ""
+echo "03: Missing brainstorm for heavyweight"
+
+run_test \
+  "plan gate fails (no brainstorm.md, heavyweight)" \
+  "$SCRIPT_DIR/03-fail-missing-brainstorm" \
+  "plan" \
+  "false" \
+  "" \
+  "Missing brainstorm artifact"
+
+# ---------------------------------------------------------------------------
+# Test 04: Fail — missing review artifact
+# ---------------------------------------------------------------------------
+echo ""
+echo "04: Missing review artifact blocks wrapup"
+
+run_test \
+  "wrapup gate fails (review-task-b.md missing)" \
+  "$SCRIPT_DIR/04-fail-missing-review" \
+  "wrapup" \
+  "false" \
+  "" \
+  "Missing review artifact"
+
+# ---------------------------------------------------------------------------
+# Test 05: Valid completion gate
+# ---------------------------------------------------------------------------
+echo ""
+echo "05: Valid completion gate"
+
+run_test \
+  "completion gate passes (digest.md exists, strategic)" \
+  "$SCRIPT_DIR/05-valid-completion" \
+  "completion" \
+  "true"
+
+# ---------------------------------------------------------------------------
+# Test 06: Fail — missing build artifact blocks review
+# ---------------------------------------------------------------------------
+echo ""
+echo "06: Missing build artifact blocks review"
+
+run_test \
+  "review-gate fails for task 'widget' (no build-widget.md)" \
+  "$SCRIPT_DIR/06-fail-missing-build" \
+  "review-gate" \
+  "false" \
+  "widget" \
+  "Missing build artifact"
+
+# ---------------------------------------------------------------------------
+# Test 07: Valid medium — full chain through execute
+# ---------------------------------------------------------------------------
+echo ""
+echo "07: Medium directive with full chain"
+
+run_test \
+  "plan gate passes (brainstorm.md exists, medium)" \
+  "$SCRIPT_DIR/07-valid-medium-full" \
+  "plan" \
+  "true"
+
+run_test \
+  "audit gate passes (plan.json valid)" \
+  "$SCRIPT_DIR/07-valid-medium-full" \
+  "audit" \
+  "true"
+
+run_test \
+  "approve gate passes (project.json with tasks)" \
+  "$SCRIPT_DIR/07-valid-medium-full" \
+  "approve" \
+  "true"
+
+run_test \
+  "execute gate passes (approval completed)" \
+  "$SCRIPT_DIR/07-valid-medium-full" \
+  "execute" \
+  "true"
+
+# ---------------------------------------------------------------------------
+# Test 08: Fail — invalid JSON in plan.json
+# ---------------------------------------------------------------------------
+echo ""
+echo "08: Invalid JSON in artifact"
+
+run_test \
+  "audit gate fails (plan.json is invalid JSON)" \
+  "$SCRIPT_DIR/08-fail-invalid-json" \
+  "audit" \
+  "false" \
+  "" \
+  "not valid JSON"
+
+# ---------------------------------------------------------------------------
+# Test 09: Fail — malformed directive.json
+# ---------------------------------------------------------------------------
+echo ""
+echo "09: Malformed directive.json"
+
+run_test \
+  "plan gate fails (directive.json is not valid JSON)" \
+  "$SCRIPT_DIR/09-malformed-directive-json" \
+  "plan" \
+  "false" \
+  "" \
+  "not valid JSON"
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "==========================="
+TOTAL=$((PASS_COUNT + FAIL_COUNT))
+echo -e "Results: ${GREEN}${PASS_COUNT}${NC} passed, ${RED}${FAIL_COUNT}${NC} failed, ${TOTAL} total"
+
+if [[ $FAIL_COUNT -gt 0 ]]; then
+  echo ""
+  echo "Failures:"
+  for f in "${FAILURES[@]}"; do
+    echo -e "  ${RED}-${NC} $f"
+  done
+  exit 1
+fi
+
+echo ""
+echo -e "${GREEN}All tests passed.${NC}"
+exit 0