@curdx/flow 1.1.4 → 1.1.6

package/hooks/scripts/inject-karpathy.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# CurDX-Flow InstructionsLoaded Hook
+# Injects the L1 baseline (Karpathy 4 principles + mandatory tool rules + 3 red lines)
+# into every session after CLAUDE.md is loaded.
+#
+# This is what makes the baseline "always on" — it doesn't rely on CLAUDE.md being
+# present in every project, and it survives context compaction.
+
+set -u
+
+CONTEXT='## CurDX-Flow Mind Baseline (L1 — always on)
+
+### 1. Think Before Coding
+- State assumptions before any non-trivial task
+- When uncertain, use AskUserQuestion — do not silently assume
+- When confused, stop — do not push forward
+
+### 2. Simplicity First
+- YAGNI: do not write features beyond what was requested
+- No single-use abstractions
+- If 200 lines suffice, do not write 1000
+
+### 3. Surgical Changes
+- Modify only the lines that must change
+- Match existing style
+- Do not delete pre-existing dead code
+
+### 4. Goal-Driven
+- Define a verifiable success criterion first
+- Forbidden to say done/fixed/working without evidence
+
+## Mandatory Tools (L2 — enforced)
+
+- library/framework questions → **context7 first** (`mcp__context7__*`); forbidden to rely on training memory
+- planning / design / architecture / review → **sequential-thinking first** (≥5 thoughts)
+- before any task → **claude-mem search** (if installed)
+- UI code → **frontend-design skill** (if installed)
+- browser QA → **chrome-devtools MCP**
+
+## Three Red Lines (L3 — inherited from pua, universal)
+
+1. **Closed loop**: claiming "done"? Provide evidence (build output / passing tests / curl result)
+2. **Fact-driven**: verify before saying "probably". An unverified attribution is blame-shifting
+3. **Exhaust everything**: before saying "I cannot", complete the systematic 4-stage debugging'
+
+# Emit JSON with safe encoding
+if command -v python3 >/dev/null 2>&1; then
+  ESCAPED="$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+  printf '{"hookSpecificOutput":{"hookEventName":"InstructionsLoaded","additionalContext":%s}}\n' "$ESCAPED"
+fi
+
+exit 0

package/hooks/scripts/quick-mode-guard.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# CurDX-Flow PreToolUse Hook for AskUserQuestion
+# Blocks AskUserQuestion when the active spec has quickMode=true or mode=autonomous.
+# This prevents the autonomous loop from stalling waiting for user input.
+#
+# The hook reads Claude's PreToolUse input JSON from stdin. We only act when
+# the tool being invoked is AskUserQuestion.
+
+set -u
+
+# Read input (Claude sends JSON on stdin for PreToolUse)
+INPUT=$(cat 2>/dev/null || echo "{}")
+
+if ! command -v python3 >/dev/null 2>&1; then
+  # Without JSON parsing, allow everything (fail open)
+  exit 0
+fi
+
+# Parse the tool name being invoked
+TOOL_NAME=$(echo "$INPUT" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get("tool_name", ""))
+except Exception:
+    print("")
+' 2>/dev/null)
+
+# We only guard AskUserQuestion
+if [ "$TOOL_NAME" != "AskUserQuestion" ]; then
+  exit 0
+fi
+
+# Check if we're in a flow project with quick mode enabled
+[ ! -d ".flow" ] && exit 0
+
+ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
+[ -z "$ACTIVE" ] && exit 0
+
+STATE_FILE=".flow/specs/$ACTIVE/.state.json"
+[ ! -f "$STATE_FILE" ] && exit 0
+
+# Read quickMode + mode
+QUICK_MODE=$(python3 -c "
+import json
+try:
+    s = json.load(open('$STATE_FILE'))
+    qm = s.get('quickMode', False)
+    mode = s.get('mode', '')
+    print('true' if (qm or mode == 'autonomous') else 'false')
+except Exception:
+    print('false')
+" 2>/dev/null)
+
+if [ "$QUICK_MODE" = "true" ]; then
+  # Block and inject guidance
+  MSG="[CurDX-Flow quick-mode-guard] Active spec '$ACTIVE' is in quick mode or autonomous mode — AskUserQuestion is forbidden. Decide autonomously based on user preferences in .flow/CONTEXT.md plus the most reasonable assumption, and record your assumption in .progress.md."
+  ESCAPED=$(printf '%s' "$MSG" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')
+  printf '{"decision":"block","reason":%s}\n' "$ESCAPED"
+  exit 0
+fi
+
+# Allow
+exit 0

package/hooks/scripts/session-start.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# CurDX-Flow SessionStart Hook
+# Duties:
+#   1. Daily dependency check — nudge user to /flow-install-deps if recommended plugins missing
+#   2. Load active spec progress into session context
+#
+# Design notes:
+#   - Idempotent: marker file tracks last check date
+#   - Silent when everything is healthy (no noise)
+#   - Graceful degradation: missing `claude` CLI doesn't break hook
+
+set -u
+
+DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
+MARKER="$DATA_DIR/.deps-checked"
+TODAY="$(date +%Y-%m-%d)"
+ADDITIONAL_CONTEXT=""
+
+mkdir -p "$DATA_DIR" 2>/dev/null || true
+
+# ---------- 1. Dependency check (once per day) ----------
+LAST_CHECK=""
+[ -f "$MARKER" ] && LAST_CHECK="$(cat "$MARKER" 2>/dev/null)"
+
+if [ "$LAST_CHECK" != "$TODAY" ]; then
+  MISSING=()
+
+  # Skip if `claude` CLI is not on PATH
+  if command -v claude >/dev/null 2>&1; then
+    INSTALLED="$(claude plugin list 2>/dev/null || true)"
+
+    echo "$INSTALLED" | grep -q 'pua'             || MISSING+=("pua")
+    echo "$INSTALLED" | grep -q 'claude-mem'      || MISSING+=("claude-mem")
+    echo "$INSTALLED" | grep -q 'frontend-design' || MISSING+=("frontend-design")
+  fi
+
+  if [ "${#MISSING[@]}" -gt 0 ]; then
+    JOINED="$(IFS=,; echo "${MISSING[*]}")"
+    ADDITIONAL_CONTEXT+="## CurDX-Flow Recommended Plugins Check\n\nThe following recommended plugins were not detected: **${JOINED}**\n\nRun \`/curdx-flow:install-deps\` for interactive one-shot install. Run \`/curdx-flow:doctor\` for the full health report.\n\n"
+  fi
+
+  echo "$TODAY" > "$MARKER" 2>/dev/null || true
+fi
+
+# ---------- 2. Load .flow/ state (if project is a flow project) ----------
+if [ -d ".flow" ]; then
+  ADDITIONAL_CONTEXT+="## CurDX-Flow Project Active\n\n"
+
+  if [ -f ".flow/PROJECT.md" ]; then
+    ADDITIONAL_CONTEXT+="### Project Vision\n$(head -80 .flow/PROJECT.md)\n\n"
+  fi
+
+  if [ -f ".flow/.active-spec" ]; then
+    ACTIVE="$(cat .flow/.active-spec 2>/dev/null)"
+    if [ -n "$ACTIVE" ] && [ -d ".flow/specs/$ACTIVE" ]; then
+      ADDITIONAL_CONTEXT+="### Active Spec: \`$ACTIVE\`\n\n"
+      if [ -f ".flow/specs/$ACTIVE/.progress.md" ]; then
+        ADDITIONAL_CONTEXT+="$(head -40 ".flow/specs/$ACTIVE/.progress.md")\n\n"
+      fi
+    fi
+  fi
+fi
+
+# ---------- 3. Emit hook output ----------
+if [ -n "$ADDITIONAL_CONTEXT" ]; then
+  # Use python3 for safe JSON encoding (handles newlines, quotes)
+  if command -v python3 >/dev/null 2>&1; then
+    ESCAPED="$(printf '%s' "$ADDITIONAL_CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+  else
+    # Fallback: naive escape (only newlines and quotes)
+    ESCAPED="$(printf '%s' "$ADDITIONAL_CONTEXT" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{printf "\""} {printf "%s\\n", $0} END{printf "\""}')"
+  fi
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' "$ESCAPED"
+fi
+
+exit 0

package/hooks/scripts/stop-watcher.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# CurDX-Flow Stop Hook — StopHookLoop strategy implementation
+#
+# Fires when Claude's turn ends. Decides whether to block (force continue)
+# or allow the session to stop.
+#
+# Decision logic:
+#   1. Not a flow project? → allow stop
+#   2. No active spec? → allow stop
+#   3. Strategy is not "stop-hook"? → allow stop
+#   4. Phase != "execute"? → allow stop
+#   5. All tasks done OR "ALL_TASKS_COMPLETE" in transcript? → cleanup + allow stop
+#   6. Too many rounds (>100) or too many failures (>3)? → stop + warn
+#   7. Otherwise → block and force continue next task
+
+set -u
+
+DATA_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.claude/plugins/data/curdx-flow}"
+
+# ---------- helper: exit with "allow stop" ----------
+allow_stop() {
+  # No output = allow stop normally
+  exit 0
+}
+
+# ---------- helper: block and inject continuation ----------
+block_continue() {
+  local reason="$1"
+  # Safely JSON-encode via python3 if available
+  if command -v python3 >/dev/null 2>&1; then
+    printf '{"decision":"block","reason":%s}\n' \
+      "$(printf '%s' "$reason" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+  else
+    # Fallback: escape quotes and newlines naively
+    local escaped=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' ')
+    printf '{"decision":"block","reason":"%s"}\n' "$escaped"
+  fi
+  exit 0
+}
+
+# ---------- 1. Must be a flow project ----------
+[ ! -d ".flow" ] && allow_stop
+
+# ---------- 2. Must have active spec ----------
+ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
+[ -z "$ACTIVE" ] && allow_stop
+SPEC_DIR=".flow/specs/$ACTIVE"
+[ ! -d "$SPEC_DIR" ] && allow_stop
+
+STATE_FILE="$SPEC_DIR/.state.json"
+[ ! -f "$STATE_FILE" ] && allow_stop
+
+# ---------- 3-4. Strategy + phase check (use python3 for JSON parsing) ----------
+if ! command -v python3 >/dev/null 2>&1; then
+  # Without python3 we can't safely parse JSON. Allow stop.
+  allow_stop
+fi
+
+read STRATEGY PHASE TASK_INDEX TOTAL_TASKS FAILED ROUNDS <<EOF
+$(python3 <<'PY'
+import json, os, sys
+p = os.environ.get("STATE_FILE")
+try:
+    s = json.load(open(p))
+except Exception:
+    sys.exit(0)
+strategy = s.get("strategy", "auto")
+phase = s.get("phase", "")
+ex = s.get("execute_state", {}) or {}
+ti = ex.get("task_index", 0)
+tt = ex.get("total_tasks", 0)
+failed = ex.get("failed_attempts", 0)
+rounds = ex.get("global_iteration", 0)
+print(strategy, phase, ti, tt, failed, rounds)
+PY
+)
+EOF
+export STATE_FILE
+
+# Only activate for stop-hook strategy + execute phase
+[ "$STRATEGY" != "stop-hook" ] && allow_stop
+[ "$PHASE" != "execute" ] && allow_stop
+
+# ---------- 5. Check for completion signal in transcript ----------
+# Claude Code passes transcript path via stdin as JSON: {"transcript_path": "/path/..."}
+# We read stdin to detect ALL_TASKS_COMPLETE or TASK_FAILED
+INPUT=$(cat 2>/dev/null || echo "{}")
+TRANSCRIPT_PATH=$(echo "$INPUT" | python3 -c 'import json,sys;
+try: print(json.load(sys.stdin).get("transcript_path",""))
+except: print("")' 2>/dev/null)
+
+TRANSCRIPT_TAIL=""
+if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  # Read last 50KB only (efficiency)
+  TRANSCRIPT_TAIL=$(tail -c 51200 "$TRANSCRIPT_PATH" 2>/dev/null || echo "")
+fi
+
+# Check for explicit completion signals
+if echo "$TRANSCRIPT_TAIL" | grep -q "ALL_TASKS_COMPLETE"; then
+  # Cleanup: mark phase completed
+  python3 <<PY 2>/dev/null
+import json
+p = "$STATE_FILE"
+s = json.load(open(p))
+s.setdefault("phase_status", {})["execute"] = "completed"
+s["phase"] = "verify"  # move to verify phase
+json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
+PY
+  allow_stop
+fi
+
+# Check for fail signal (accumulate; actual stop decision below)
+if echo "$TRANSCRIPT_TAIL" | grep -q "TASK_FAILED"; then
+  # Increment failed_attempts
+  python3 <<PY 2>/dev/null
+import json
+p = "$STATE_FILE"
+s = json.load(open(p))
+s.setdefault("execute_state", {})
+s["execute_state"]["failed_attempts"] = s["execute_state"].get("failed_attempts", 0) + 1
+json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
+PY
+  # Re-read
+  FAILED=$(python3 -c "import json; print(json.load(open('$STATE_FILE'))['execute_state']['failed_attempts'])" 2>/dev/null || echo 0)
+fi
+
+# ---------- 6. Safety brakes ----------
+if [ "$FAILED" -ge 3 ]; then
+  # Too many failures — stop and surface
+  allow_stop
+fi
+
+if [ "$ROUNDS" -ge 100 ]; then
+  # Runaway loop protection
+  allow_stop
+fi
+
+# Check if all tasks done
+if [ "$TASK_INDEX" -ge "$TOTAL_TASKS" ] && [ "$TOTAL_TASKS" -gt 0 ]; then
+  # Mark complete
+  python3 <<PY 2>/dev/null
+import json
+p = "$STATE_FILE"
+s = json.load(open(p))
+s.setdefault("phase_status", {})["execute"] = "completed"
+s["phase"] = "verify"
+json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
+PY
+  allow_stop
+fi
+
+# ---------- 7. Block and continue ----------
+# Increment round counter
+python3 <<PY 2>/dev/null
+import json
+p = "$STATE_FILE"
+s = json.load(open(p))
+s.setdefault("execute_state", {})
+s["execute_state"]["global_iteration"] = s["execute_state"].get("global_iteration", 0) + 1
+json.dump(s, open(p, "w"), indent=2, ensure_ascii=False)
+PY
+
+NEXT_INDEX=$((TASK_INDEX + 1))
+REASON="[CurDX-Flow stop-hook] Spec '$ACTIVE' has tasks remaining ($TASK_INDEX/$TOTAL_TASKS). Continue to the next task. Dispatch flow-executor for task_id=next. On completion, emit TASK_COMPLETE or TASK_FAILED. When all tasks are done, emit ALL_TASKS_COMPLETE."
+
+block_continue "$REASON"

package/knowledge/atomic-commits.md

@@ -0,0 +1,262 @@
+# Atomic Commits — Atomic Commit Rules
+
+> One task, one commit. This is the iron rule for all execution agents in CurDX-Flow.
+>
+> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md`.
+
+---
+
+## Core Principle
+
+**One task = one commit = one rollback unit.**
+
+Why:
+- `git bisect` can pinpoint a problem to a specific task
+- `git revert <hash>` can undo a single task in isolation
+- PR review can walk through changes commit-by-commit
+- Downstream agents can trace "which AD / FR this change came from" via commit history
+
+---
+
+## Commit Message Format (Conventional Commits + CurDX-Flow extensions)
+
+```
+<type>(<scope>): <summary>
+
+[body - explain why, not what]
+
+[footer - reference IDs]
+```
+
+### Type (required)
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `feat` | New feature | `feat(auth): add JWT refresh endpoint` |
+| `fix` | Bug fix | `fix(login): handle empty email case` |
+| `refactor` | Refactor (behavior unchanged) | `refactor(db): extract connection pool` |
+| `test` | Tests | `test(auth): red - add login validation tests` |
+| `docs` | Documentation | `docs(readme): add install instructions` |
+| `chore` | Misc (deps, config) | `chore(deps): upgrade bcrypt to 5.1.0` |
+| `perf` | Performance | `perf(query): cache user lookups` |
+| `style` | Formatting (no behavior change) | `style: fix indentation in auth module` |
+| `build` | Build config | `build(tsconfig): enable strict mode` |
+| `ci` | CI config | `ci(github): add test workflow` |
+
+### TDD phase markers (used in Phase 3)
+
+| Phase | Type + suffix | Example |
+|-------|--------------|---------|
+| RED | `test(scope): red - ...` | `test(auth): red - login validation` |
+| GREEN | `feat(scope): green - ...` | `feat(auth): green - satisfy login test` |
+| YELLOW | `refactor(scope): yellow - ...` | `refactor(auth): yellow - extract validator` |
+
+### Scope
+
+- Module name (`auth`, `db`, `ui`, `api`)
+- Or file name (without extension)
+- Or `(spec-name)` if spanning multiple modules
+
+### Summary
+
+- Imperative mood (`add`, `fix`, not `added`, `fixes`)
+- Lowercase start (unless a proper noun)
+- No trailing period
+- ≤ 70 characters
+
+---
+
+## Body (optional but recommended)
+
+Explain **why**. Do not explain **what** (the diff shows what).
+
+```
+feat(auth): implement JWT refresh flow
+
+Tokens expire after 15 minutes. Without refresh, users get
+logged out mid-session. This adds a refresh endpoint that
+validates the refresh_token and issues a new access_token.
+
+Per AD-03: use rotating refresh tokens to mitigate theft.
+```
+
+Do NOT write:
+```
+feat(auth): implement JWT refresh flow
+
+Added refreshToken() function in auth.ts.
+Added POST /auth/refresh endpoint.
+Added tests for success and failure cases.
+```
+← the diff already shows this; it wastes commit message space.
+
+---
+
+## Footer (reference IDs)
+
+CurDX-Flow extension: if a task references FR / AC / AD / D-NN, list them in the footer:
+
+```
+feat(auth): implement JWT refresh flow
+
+Refresh tokens rotate on each use, preventing replay attacks.
+
+Requirements: FR-03, AC-2.1
+Design: AD-03
+Decisions: D-07 (session storage strategy)
+Task: spec/auth-system/tasks.md#3.2
+```
+
+Fields:
+- `Requirements:` lists implemented FR / AC
+- `Design:` lists related AD
+- `Decisions:` lists referenced project-level decisions (D-NN)
+- `Task:` optional, points at the task definition location
+
+---
+
+## Concrete Rules for Atomicity
+
+### 1. One commit does one thing
+
+✗ **Bad**:
+```
+feat: add login + fix typo + refactor db connection
+```
+
+✓ **Good** (split into 3 commits):
+```
+feat(auth): add login endpoint
+docs: fix typo in README
+refactor(db): extract connection factory
+```
+
+### 2. Do not mix "task code" and "cleanup"
+
+✗ **Bad**:
+```
+feat(auth): add JWT + remove unused imports in user.ts
+```
+
+✓ **Good**:
+```
+feat(auth): add JWT endpoint
+chore: remove unused imports in user.ts
+```
+
+### 3. Every commit must pass tests independently
+
+This is what makes `git bisect` work.
+
+- Do not commit "broken intermediate states"
+- Even WIP should build + test (even with few tests)
+- For a large change that truly must be split, use a feature branch and squash at the end
+
+### 4. The file change scope should match the commit message
+
+If the commit is `feat(auth): ...`, it should not include changes under `src/ui/`. Otherwise you actually did two things.
+
+---
+
+## The flow-executor Agent's Commit Flow
+
+```bash
+# Step 1: git add only the files involved in the task
+git add src/auth/login.ts src/auth/login.test.ts
+
+# Step 2: check that staged diff matches the commit message
+git diff --cached --stat
+
+# Step 3: ensure no unexpected changes sneaked in
+# (if you see a file that shouldn't be there, git reset HEAD <file>)
+
+# Step 4: commit
+git commit -m "feat(auth): green - implement login endpoint
+
+Per AD-03, uses bcrypt for password hashing.
+
+Requirements: FR-01
+Design: AD-03
+"
+
+# Step 5: record the hash
+COMMIT_HASH=$(git rev-parse --short HEAD)
+echo "✓ Committed: $COMMIT_HASH"
+```
+
+---
+
+## Forbidden Patterns
+
+### ✗ Giant commit
+```
+feat(auth): implement entire authentication system
+```
+Too large, cannot review, cannot bisect. Split into N small commits.
+
+### ✗ Hedging words
+```
+feat(auth): maybe fix login issue?
+```
+If unsure, do not commit yet. A commit is a definitive operation.
+
+### ✗ Meaningless commits
+```
+wip
+fix
+update
+```
+Future maintainers will curse you. At minimum write `wip(auth): placeholder for token refresh`.
+
+### ✗ `--amend` on a pushed commit
+```
+git commit --amend  # after push
+git push -f         # overwrite remote
+```
+Destroys shared history. Only amend local, unpushed commits.
+
+### ✗ Skipping hooks
+```
+git commit --no-verify
+```
+Unless the user explicitly requests it. Hooks exist for reasons (pre-commit lint, commit-msg check).
+
+---
+
+## Relationship to PR Review
+
+PR review reads each commit's message.
+
+- Good commit message → reviewer finishes in 5 minutes
+- Bad commit message → reviewer either rubber-stamps or blocks without reading
+
+CurDX-Flow's `/curdx-flow:ship` command (Phase 6) will turn atomic commits into a clean PR description. Poor commit quality yields poor PR descriptions.
+
+---
+
+## Real Example (commit history for a full spec execution)
+
+```
+$ git log --oneline auth-system spec
+
+abc123f feat(auth): green - implement login endpoint (Requirements: FR-01)
+def456g feat(auth): green - implement password hashing (Design: AD-03)
+ghi789h test(auth): red - add login endpoint tests
+jkl012i test(auth): red - add password hash tests
+mno345j chore(deps): add bcrypt@5.1.0
+pqr678k docs(auth): add design.md for JWT authentication
+stu901l docs(auth): add requirements.md
+vwx234m docs(auth): add research.md (initial spec)
+```
+
+Reading this history, anyone can understand:
+- First came research → requirements → design (doc commits)
+- Then a dependency was added
+- Then TDD red (tests) → green (implementation)
+- Every step is atomic
+
+This is the quality CurDX-Flow demands.
+
+---
+
+_CurDX-Flow internal rule. Violation counts as a flow-executor task failure._