create-ccc-tutor 0.1.0

package/template/.harness/scripts/post-migration.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# post-migration.sh — backend-specific steps after a schema migration is applied locally.
+#
+# Called manually by the user (or invoked from /db-schema's Step 10).
+# Only relevant if backend_db_type is configured. Projects without a backend
+# don't have this script (or it just exits 0).
+#
+# Typical responsibilities:
+#   1. Refresh backend caches that don't auto-reload on `migration up`
+#      (e.g., PostgREST schema cache in some local stacks)
+#   2. Regenerate typed bindings (so the typecheck doesn't fail on stale types)
+#   3. Notify the live backend (managed Postgres / Supabase / etc.) if needed
+
+set -euo pipefail
+
+# Ensure brew-installed tools (jq, etc.) are on PATH even in non-interactive
+# shells where ~/.zprofile isn't loaded. macOS Apple Silicon path comes first.
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# ─────────────────────────────────────────────────────────────────────
+# CUSTOMIZE: per-backend post-migration steps
+# ─────────────────────────────────────────────────────────────────────
+
+# Example 1 — Supabase (local Docker stack):
+# docker compose -f supabase/docker-compose.yml restart postgrest \
+#   || echo "warning: PostgREST restart failed; new RPCs may not appear in schema cache"
+# supabase gen types typescript --local > src/lib/supabase/types.ts \
+#   || echo "warning: type regeneration failed"
+
+# Example 2 — Prisma:
+# npx prisma migrate dev --skip-seed
+# npx prisma generate
+
+# Example 3 — Drizzle:
+# npx drizzle-kit push
+# # types regen happens automatically with drizzle-kit
+
+# Example 4 — Raw Postgres + pgtyped:
+# psql "$DATABASE_URL" -f "$(ls -t supabase/migrations/*.sql | head -1)"
+# npx pgtyped -c pgtyped.config.json
+
+# Example 5 — Django:
+# python manage.py migrate
+# python manage.py inspectdb > types.py  # if using inspectdb workflow
+
+# Example 6 — None (no backend / no codegen step):
+# exit 0
+
+# ─────────────────────────────────────────────────────────────────────
+# Run
+# ─────────────────────────────────────────────────────────────────────
+echo "ℹ️  post-migration.sh has no commands configured."
+echo "    Edit .harness/scripts/post-migration.sh to add your backend's"
+echo "    cache-refresh + typed-bindings-regenerate steps."
+echo ""
+echo "    Without this, Stage 4 (/execution-plan) may operate on stale types."
+
+exit 0

package/template/.harness/scripts/precommit-cycles.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Pre-commit dependency-cycle check.
+#
+# Only meaningful if the project has declared a dependency_flow (e.g.,
+# `shared → ui → features → app`). If dependency_flow is empty, this script
+# should exit 0 silently — /init removes the hook entry in that case.
+
+set -euo pipefail
+
+# Ensure brew-installed tools (jq, etc.) are on PATH even in non-interactive
+# shells where ~/.zprofile isn't loaded. macOS Apple Silicon path comes first.
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Filter: only fire on `git commit` invocations. The PreToolUse hook contract
+# passes the tool call payload via stdin; we parse it and silently exit if
+# the Bash command isn't a git commit.
+#
+# (We do this filtering here instead of relying on settings.json's `if`
+# clause because that clause was found NOT to be honored consistently —
+# see harness-testing-2026-05-25.md § P0.Z.)
+
+# Read stdin (Claude Code passes JSON with tool_input.command for Bash hooks)
+HOOK_INPUT="$(cat 2>/dev/null || true)"
+if [ -n "$HOOK_INPUT" ]; then
+  # Try to extract the Bash command. If jq is available, use it. Otherwise
+  # fall back to grep (best-effort).
+  if command -v jq >/dev/null 2>&1; then
+    BASH_CMD="$(printf '%s' "$HOOK_INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")"
+  else
+    # Best-effort fallback: extract "command":"..." substring via grep
+    BASH_CMD="$(printf '%s' "$HOOK_INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*"command"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/' || echo "")"
+  fi
+  # Silent exit unless this is a git commit invocation
+  case "$BASH_CMD" in
+    git\ commit*|*\ git\ commit*)
+      # proceed
+      ;;
+    *)
+      exit 0
+      ;;
+  esac
+fi
+
+# === Original hook logic continues below ===
+
+# ─────────────────────────────────────────────────────────────────────
+# CUSTOMIZE: pick your stack's cycle-detection command
+# ─────────────────────────────────────────────────────────────────────
+# JS/TS (madge):       COMMAND=(npx madge --circular src/)
+# JS/TS (dpdm):        COMMAND=(npx dpdm --no-warning src/)
+# Python:              COMMAND=(pylint --disable=all --enable=cyclic-import .)
+# Go:                  COMMAND=(go vet ./...)  # detects import cycles
+# Rust:                # rustc detects cycles natively
+# None / skip:         exit 0
+# ─────────────────────────────────────────────────────────────────────
+
+COMMAND=(npx madge --circular src/)
+
+# ─────────────────────────────────────────────────────────────────────
+# Run
+# ─────────────────────────────────────────────────────────────────────
+if ! command -v "${COMMAND[0]}" >/dev/null 2>&1; then
+  echo "warning: ${COMMAND[0]} not found; skipping cycle check" >&2
+  exit 0
+fi
+
+if ! "${COMMAND[@]}"; then
+  echo ""
+  echo "❌ Dependency cycle detected."
+  echo "If this is a deliberate exception, document the cycle in your"
+  echo "commit body with reasoning, then bypass with --no-verify (per"
+  echo "AGENTS.md § Anti-flag rules), but expect the auditor to question it."
+  exit 1
+fi

package/template/.harness/scripts/precommit-typecheck.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Pre-commit typecheck. Blocks commit if type/syntax check fails.
+#
+# Called from .claude/settings.json + .codex/hooks.json on `git commit:*`.
+# Constitution § 5 (Spec and reality stay in sync) — typecheck is one of the
+# mechanical gates that catch reality drift at the syntax level.
+
+set -euo pipefail
+
+# Ensure brew-installed tools (jq, etc.) are on PATH even in non-interactive
+# shells where ~/.zprofile isn't loaded. macOS Apple Silicon path comes first.
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Filter: only fire on `git commit` invocations. The PreToolUse hook contract
+# passes the tool call payload via stdin; we parse it and silently exit if
+# the Bash command isn't a git commit.
+#
+# (We do this filtering here instead of relying on settings.json's `if`
+# clause because that clause was found NOT to be honored consistently —
+# see harness-testing-2026-05-25.md § P0.Z.)
+
+# Read stdin (Claude Code passes JSON with tool_input.command for Bash hooks)
+HOOK_INPUT="$(cat 2>/dev/null || true)"
+if [ -n "$HOOK_INPUT" ]; then
+  # Try to extract the Bash command. If jq is available, use it. Otherwise
+  # fall back to grep (best-effort).
+  if command -v jq >/dev/null 2>&1; then
+    BASH_CMD="$(printf '%s' "$HOOK_INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")"
+  else
+    # Best-effort fallback: extract "command":"..." substring via grep
+    BASH_CMD="$(printf '%s' "$HOOK_INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*"command"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/' || echo "")"
+  fi
+  # Silent exit unless this is a git commit invocation
+  case "$BASH_CMD" in
+    git\ commit*|*\ git\ commit*)
+      # proceed
+      ;;
+    *)
+      exit 0
+      ;;
+  esac
+fi
+
+# === Original hook logic continues below ===
+
+# ─────────────────────────────────────────────────────────────────────
+# CUSTOMIZE: pick your stack's typecheck command
+# ─────────────────────────────────────────────────────────────────────
+# TypeScript:    COMMAND=(npx tsc --noEmit)
+# TypeScript+pnpm: COMMAND=(pnpm exec tsc --noEmit)
+# Python+mypy:   COMMAND=(mypy .)
+# Python+pyright: COMMAND=(pyright)
+# Go:            COMMAND=(go vet ./...)
+# Rust:          COMMAND=(cargo check --all-targets)
+# Swift:         COMMAND=(swift build --build-tests)
+# None / skip:   exit 0
+# ─────────────────────────────────────────────────────────────────────
+
+COMMAND=(npx tsc --noEmit)
+
+# ─────────────────────────────────────────────────────────────────────
+# Run
+# ─────────────────────────────────────────────────────────────────────
+if ! command -v "${COMMAND[0]}" >/dev/null 2>&1; then
+  echo "warning: ${COMMAND[0]} not found; skipping typecheck" >&2
+  exit 0
+fi
+
+"${COMMAND[@]}"

package/template/.harness/scripts/scratchpad-recall.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# scratchpad-recall.sh — SessionStart hook for v2 working memory (Tier 1).
+#
+# Reads .harness/state/scratchpad.md and emits it as additionalContext so the
+# AI starts the session aware of:
+#   - Current objective (carried from prior session, if any)
+#   - Last step taken
+#   - Next step planned
+#   - Open blockers
+#
+# If the file doesn't exist (fresh project), copies from template. If empty,
+# emits a brief "no carryover" notice.
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRATCHPAD="$PROJECT_DIR/.harness/state/scratchpad.md"
+TEMPLATE="$PROJECT_DIR/.harness/state/scratchpad.md.template"
+
+# Drain stdin
+cat >/dev/null 2>&1 || true
+
+# Bootstrap from template if missing
+if [ ! -f "$SCRATCHPAD" ] && [ -f "$TEMPLATE" ]; then
+  cp "$TEMPLATE" "$SCRATCHPAD" 2>/dev/null || true
+fi
+
+# If still missing or empty, emit a brief notice
+if [ ! -f "$SCRATCHPAD" ] || [ ! -s "$SCRATCHPAD" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    jq -n '{
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: "📋 Working scratchpad (.harness/state/scratchpad.md) is empty — fresh start. Per CLAUDE.md § Working Scratchpad, you will rewrite it at end of your first turn."
+      }
+    }'
+  fi
+  exit 0
+fi
+
+# Cap: read at most 500 lines (defensive against runaway files)
+CONTENT=$(head -500 "$SCRATCHPAD")
+
+# Char cap: ~2000 chars (~500 tokens). If oversized, truncate and warn.
+if [ "${#CONTENT}" -gt 2000 ]; then
+  CONTENT=$(printf '%s' "$CONTENT" | head -c 2000)
+  CONTENT="$CONTENT
+
+⚠️ (scratchpad exceeded 500-token cap; truncated. Rewrite leaner this turn.)"
+fi
+
+# Build additionalContext: prepend header explaining what this is and how AI should treat it
+HEADER='## Working Scratchpad (Tier 1 memory — read at SessionStart)
+
+The file below is the AI working scratchpad: the agent-managed core memory for this project. It survives compaction and `/clear` because it lives on disk. Per `CLAUDE.md § Working Scratchpad`:
+
+- **Trust it**: it reflects state at end of last AI turn
+- **Update it**: at the end of THIS turn, the Stop hook will instruct you to rewrite it with the current objective, last step, next step, and blockers
+- **Keep it lean**: ≤500 tokens (~2000 chars). If you find yourself needing more, it belongs in `/remember` or `/handoff`, not the scratchpad
+
+Current contents:
+
+```markdown
+'
+
+FOOTER='
+```
+
+---'
+
+FULL="${HEADER}${CONTENT}${FOOTER}"
+
+if command -v jq >/dev/null 2>&1; then
+  printf '%s' "$FULL" | jq -Rs '{
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: .
+    }
+  }'
+fi
+
+exit 0

package/template/.harness/scripts/scratchpad-update.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# scratchpad-update.sh — Stop hook for v2 working memory (Tier 1).
+#
+# DESIGN NOTE (v2.1 — 2026-05-31):
+# Claude Code's Stop hook schema does NOT support `hookSpecificOutput.additionalContext`
+# (only PreToolUse / UserPromptSubmit / PostToolUse / PostToolBatch do). So this hook
+# CANNOT inject text instructions back to the AI.
+#
+# Instead, the scratchpad rewrite rule lives in CLAUDE.md § Working Scratchpad, which the
+# AI reads at SessionStart. The AI rewrites the scratchpad as the final act of each turn
+# because the CLAUDE.md rule tells it to — no hook nudge required.
+#
+# This hook's job is now just to:
+#   1. Ensure the scratchpad file + parent dir exist (defensive)
+#   2. Stay silent (suppressOutput=true) so it never spams the user's screen
+#
+# Returning `{}` would also work, but `{"suppressOutput": true}` is the explicit
+# "I have nothing to say" signal.
+
+set -eu
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+SCRATCHPAD="$PROJECT_DIR/.harness/state/scratchpad.md"
+TEMPLATE="$PROJECT_DIR/.harness/state/scratchpad.md.template"
+
+# Drain stdin
+cat >/dev/null 2>&1 || true
+
+# Ensure dir + file exist (so next SessionStart's scratchpad-recall finds something)
+mkdir -p "$(dirname "$SCRATCHPAD")" 2>/dev/null || true
+if [ ! -f "$SCRATCHPAD" ] && [ -f "$TEMPLATE" ]; then
+  cp "$TEMPLATE" "$SCRATCHPAD" 2>/dev/null || true
+fi
+
+# Emit a valid Stop schema response: suppress any output
+printf '{"suppressOutput": true}\n'
+
+exit 0