@codyswann/lisa 1.48.0 → 1.49.0

package/plugins/lisa-nestjs/hooks/track-plan-sessions.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+#
+# track-plan-sessions.sh - Tracks which sessions work on each plan file
+#
+# Triggered by two hooks:
+#   1. PostToolUse (Write|Edit) - Detects plan file writes via absolute path comparison,
+#      stamps session ID into the plan's ## Sessions table, and saves a session-specific
+#      marker file so subsequent UserPromptSubmit events can reliably find the active plan.
+#   2. UserPromptSubmit - Finds the active plan file by checking for a session-specific
+#      marker file first (set by PostToolUse), falling back to the most recently CREATED
+#      .md file in plans/ (ls -tU on macOS sorts by birth time). This avoids the mtime bug
+#      where another plan file's modification time (e.g., from a hook writing a session ID
+#      to it, or format-on-edit touching it) could cause the wrong file to appear "newest."
+#
+# Marker files: $PLANS_DIR/.active-plan-<session-id> contain the absolute path to the
+# active plan file. Stale markers (>24h) are cleaned up on each invocation.
+#
+# Dedup: Session ID dedup is scoped to the ## Sessions section only, not the entire
+# file. This prevents false positives when session IDs appear elsewhere in plan content
+# (e.g., scratchpad directory paths like /private/tmp/claude-501/.../SESSION_ID/...).
+#
+# Debug logging: All key decisions are logged to $PLANS_DIR/.track-plan-debug.log for
+# diagnostics if session IDs land in the wrong plan file.
+#
+# Input (via stdin): JSON with session_id, permission_mode, hook_event_name, etc.
+#
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+PERMISSION_MODE=$(echo "$INPUT" | jq -r '.permission_mode // "default"')
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty')
+
+# Temporarily disable this hook
+exit 0
+
+# Session ID is required
+if [[ -z "$SESSION_ID" ]]; then
+  exit 0
+fi
+
+# Resolve plans directory from settings (default ./plans)
+PLANS_DIR="./plans"
+SETTINGS_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/settings.json"
+if [[ -f "$SETTINGS_FILE" ]]; then
+  CONFIGURED_DIR=$(jq -r '.plansDirectory // empty' "$SETTINGS_FILE")
+  if [[ -n "$CONFIGURED_DIR" ]]; then
+    PLANS_DIR="$CONFIGURED_DIR"
+  fi
+fi
+
+# Debug logging
+DEBUG_LOG="$PLANS_DIR/.track-plan-debug.log"
+
+log_debug() {
+  printf '[%s] [%s] [%s] %s\n' \
+    "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+    "$SESSION_ID" \
+    "$HOOK_EVENT" \
+    "$1" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+# Session-specific marker file for reliable active-plan detection
+MARKER_FILE="$PLANS_DIR/.active-plan-${SESSION_ID}"
+
+# Clean stale marker files older than 24h
+find "$PLANS_DIR" -name ".active-plan-*" -mmin +1440 -delete 2>/dev/null || true
+
+PLAN_FILE=""
+RESOLUTION_METHOD=""
+
+if [[ "$HOOK_EVENT" == "PostToolUse" ]]; then
+  # Trigger A: Plan file was written/edited
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+  if [[ -z "$FILE_PATH" ]]; then
+    log_debug "PostToolUse: no file_path in tool_input, exiting"
+    exit 0
+  fi
+
+  # Resolve PLANS_DIR to absolute path for comparison
+  ABS_PLANS_DIR=$(cd "$PLANS_DIR" 2>/dev/null && pwd)
+
+  if [[ -z "$ABS_PLANS_DIR" ]]; then
+    log_debug "PostToolUse: could not resolve PLANS_DIR=$PLANS_DIR to absolute path, exiting"
+    exit 0
+  fi
+
+  # Check if the written file is in the plans directory
+  if [[ "$FILE_PATH" == "$ABS_PLANS_DIR"/* ]]; then
+    PLAN_FILE="$FILE_PATH"
+    RESOLUTION_METHOD="PostToolUse-direct"
+    log_debug "PostToolUse: matched plan file=$PLAN_FILE"
+
+    # Save marker so UserPromptSubmit can find this plan reliably
+    echo "$PLAN_FILE" > "$MARKER_FILE"
+    log_debug "PostToolUse: saved marker file=$MARKER_FILE"
+  else
+    log_debug "PostToolUse: file_path=$FILE_PATH not in plans dir=$ABS_PLANS_DIR, exiting"
+    exit 0
+  fi
+
+elif [[ "$HOOK_EVENT" == "UserPromptSubmit" ]]; then
+  # Trigger B: Find the active plan file
+  # Priority 1: Session-specific marker file (reliable — set by PostToolUse when plan was written)
+  if [[ -f "$MARKER_FILE" ]]; then
+    PLAN_FILE=$(cat "$MARKER_FILE")
+    RESOLUTION_METHOD="marker-file"
+    log_debug "UserPromptSubmit: resolved via marker file=$PLAN_FILE"
+  else
+    # Priority 2: Most recently CREATED file (ls -tU on macOS sorts by birth time)
+    PLAN_FILE=$(ls -tU "$PLANS_DIR"/*.md 2>/dev/null | head -1)
+    RESOLUTION_METHOD="fallback-ls-tU"
+    log_debug "UserPromptSubmit: no marker file, fallback ls -tU resolved=$PLAN_FILE"
+  fi
+
+  if [[ -z "$PLAN_FILE" || ! -f "$PLAN_FILE" ]]; then
+    log_debug "UserPromptSubmit: no valid plan file found, exiting"
+    exit 0
+  fi
+else
+  exit 0
+fi
+
+# Verify the plan file exists
+if [[ ! -f "$PLAN_FILE" ]]; then
+  log_debug "plan file=$PLAN_FILE does not exist, exiting"
+  exit 0
+fi
+
+# Check if session ID already exists in the ## Sessions section (dedup)
+# Only search within the Sessions section to avoid false positives from session IDs
+# appearing in plan content (e.g., scratchpad paths contain session IDs)
+if sed -n '/^## Sessions$/,$p' "$PLAN_FILE" 2>/dev/null | grep -qF "$SESSION_ID"; then
+  log_debug "dedup: session ID already in $PLAN_FILE sessions section (resolved via $RESOLUTION_METHOD), skipping write"
+  exit 0
+fi
+
+# Determine phase from permission_mode
+PHASE=$( [[ "$PERMISSION_MODE" == "plan" ]] && echo "plan" || echo "implement" )
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Check if ## Sessions section exists
+if grep -q "^## Sessions" "$PLAN_FILE" 2>/dev/null; then
+  # Append row to existing table
+  printf '| %s | %s | %s |\n' "$SESSION_ID" "$TIMESTAMP" "$PHASE" >> "$PLAN_FILE"
+else
+  # Create ## Sessions section at end of file
+  {
+    echo ""
+    echo "## Sessions"
+    echo ""
+    echo "<!-- Auto-maintained by track-plan-sessions.sh -->"
+    echo "| Session ID | First Seen | Phase |"
+    echo "|------------|------------|-------|"
+    printf '| %s | %s | %s |\n' "$SESSION_ID" "$TIMESTAMP" "$PHASE"
+  } >> "$PLAN_FILE"
+fi
+
+log_debug "wrote session to $PLAN_FILE (resolved via $RESOLUTION_METHOD, phase=$PHASE)"
+
+exit 0

package/plugins/lisa-nestjs/hooks/verify-completion.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# =============================================================================
+# Verification Level Enforcement Hook (Stop)
+# =============================================================================
+# Checks whether the agent declared a verification level when the session
+# involved code changes. Does NOT re-run lint/typecheck/tests (husky does that).
+#
+# Logic:
+#   1. If no Write/Edit tools were used → exit 0 (research/conversation only)
+#   2. If code was written → check last assistant message for verification level
+#   3. If verification level found → exit 0
+#   4. If missing and stop_hook_active is false → block with instructions
+#   5. If missing and stop_hook_active is true → exit 0 (avoid infinite loops)
+#
+# @see .claude/rules/verfication.md "Self-Correction Loop" section
+# =============================================================================
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract transcript path
+TRANSCRIPT_PATH=$(echo "$INPUT" | grep -o '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+
+# Exit silently if no transcript available
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+    exit 0
+fi
+
+# Check if Write or Edit tools were used during the session
+# Look for tool_use entries with Write or Edit tool names
+if ! grep -q '"tool_name"[[:space:]]*:[[:space:]]*"\(Write\|Edit\|NotebookEdit\)"' "$TRANSCRIPT_PATH" 2>/dev/null; then
+    # No code changes — this was research/conversation, allow stop
+    exit 0
+fi
+
+# Code was written — check if a verification level was declared
+# Extract the last assistant message
+LAST_ASSISTANT=$(awk '/"type"[[:space:]]*:[[:space:]]*"assistant"/{line=$0} END{if(line) print line}' "$TRANSCRIPT_PATH" 2>/dev/null)
+
+if [ -z "$LAST_ASSISTANT" ]; then
+    exit 0
+fi
+
+# Extract the text content from the assistant message
+RESPONSE_TEXT=""
+if command -v jq >/dev/null 2>&1; then
+    RESPONSE_TEXT=$(echo "$LAST_ASSISTANT" | jq -r '.message.content[] | select(.type == "text") | .text' 2>/dev/null)
+else
+    RESPONSE_TEXT=$(echo "$LAST_ASSISTANT" | grep -o '"text"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//' | sed 's/"$//')
+fi
+
+if [ -z "$RESPONSE_TEXT" ]; then
+    exit 0
+fi
+
+# Check for verification level keywords (case-insensitive)
+if echo "$RESPONSE_TEXT" | grep -qi "FULLY VERIFIED\|PARTIALLY VERIFIED\|UNVERIFIED"; then
+    exit 0
+fi
+
+# Check if this is a retry (stop_hook_active flag)
+# The stop_hook_active field is set to true when a Stop hook has already blocked once
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | grep -o '"stop_hook_active"[[:space:]]*:[[:space:]]*true' || echo "")
+
+if [ -n "$STOP_HOOK_ACTIVE" ]; then
+    # Already blocked once — allow stop to prevent infinite loop
+    exit 0
+fi
+
+# No verification level declared after code changes — block
+cat << 'EOF'
+{"decision":"block","reason":"You changed code but didn't declare a verification level. Run your verification, then declare FULLY VERIFIED, PARTIALLY VERIFIED, or UNVERIFIED with evidence. See .claude/rules/verfication.md for requirements."}
+EOF
+
+exit 0

package/plugins/lisa-nestjs/rules/README.md

@@ -0,0 +1,240 @@
+# Claude Code Configuration
+
+This directory contains Claude Code configuration files that customize AI-assisted development workflows.
+
+## Directory Structure
+
+```
+.claude/
+├── settings.json              # Main Claude Code settings
+├── settings.local.json        # Local overrides (gitignored)
+├── settings.local.json.example # Template for local settings
+├── agents/                    # Custom agent definitions
+├── hooks/                     # Automation hooks
+├── rules/                     # Always-on governance rules
+└── skills/                    # Skill definitions (colon-namespaced)
+```
+
+## Settings
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASH_DEFAULT_TIMEOUT_MS` | 1800000 (30 min) | Default timeout for bash commands |
+| `BASH_MAX_TIMEOUT_MS` | 7200000 (2 hours) | Maximum allowed timeout |
+
+### Hooks
+
+| Event | Hook | Purpose |
+|-------|------|---------|
+| `SessionStart` | `install-pkgs.sh` | Install dependencies when session starts |
+| `PostToolUse` | `format-on-edit.sh` | Auto-format files after Write/Edit operations |
+| `Notification` | `notify-ntfy.sh` | Send notifications via ntfy.sh |
+| `Stop` | `notify-ntfy.sh` | Notify when session ends |
+
+## Plugins
+
+The `enabledPlugins` section in `settings.json` references Claude Code plugins. These extend Claude Code functionality with additional capabilities.
+
+### Plugin Sources
+
+| Source | Description | Registration |
+|--------|-------------|--------------|
+| `claude-plugins-official` | Official Anthropic plugins | Built-in, no registration needed |
+| `cc-marketplace` | Community marketplace | Available at [Claude Code Marketplace](https://marketplace.claude.ai) |
+
+### Enabled Plugins
+
+| Plugin | Source | Purpose |
+|--------|--------|---------|
+| `typescript-lsp` | `claude-plugins-official` | TypeScript language server integration |
+| `safety-net` | `cc-marketplace` | Backup and safety features |
+| `code-simplifier` | `claude-plugins-official` | Code complexity reduction suggestions |
+| `code-review` | `claude-plugins-official` | Automated code review capabilities |
+| `playwright` | `claude-plugins-official` | Playwright test integration |
+
+### Installing Plugins
+
+1. **Official plugins** are available by default in Claude Code
+2. **Marketplace plugins** can be installed via the Claude Code settings UI
+3. **Third-party plugins** require following their installation instructions
+
+### Plugin Availability
+
+Not all plugins may be available in all Claude Code installations:
+
+- Some plugins require specific Claude Code versions
+- Marketplace plugins require marketplace access
+- Enterprise installations may restrict available plugins
+
+If a plugin is not available, Claude Code will ignore it gracefully.
+
+## Local Settings Override
+
+Create `settings.local.json` to override settings for your local environment:
+
+```json
+{
+  "env": {
+    "CUSTOM_API_KEY": "your-key-here"
+  },
+  "hooks": {
+    "PostToolUse": []
+  },
+  "enabledPlugins": {
+    "playwright": false
+  }
+}
+```
+
+This file should be:
+- Added to `.gitignore`
+- Never committed to version control
+- Used for machine-specific settings
+
+## Agents
+
+Custom agent definitions in `agents/` provide specialized AI personas for different tasks:
+
+| Agent | Purpose |
+|-------|---------|
+| `agent-architect.md` | Agent file design and optimization |
+| `architecture-specialist.md` | Implementation design, dependency mapping, pattern evaluation |
+| `git-history-analyzer.md` | Git history analysis |
+| `hooks-expert.md` | Claude Code hooks expertise |
+| `implementer.md` | Code implementation with TDD enforcement |
+| `learner.md` | Post-implementation learning and skill creation |
+| `performance-specialist.md` | N+1 queries, algorithmic complexity, memory leaks |
+| `product-specialist.md` | User flows, acceptance criteria, UX validation |
+| `quality-specialist.md` | Code correctness, coding philosophy, test coverage review |
+| `security-specialist.md` | Threat modeling (STRIDE), OWASP Top 10, auth/secrets review |
+| `skill-evaluator.md` | Skill quality assessment |
+| `slash-command-architect.md` | Command design |
+| `test-specialist.md` | Test strategy, test writing, coverage analysis |
+| `web-search-researcher.md` | Web research tasks |
+
+## Skills
+
+Skills use colon-namespaced directories (e.g., `plan:create/`) and are invoked via `/skill-name` in Claude Code.
+
+### Plan Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `plan:create` | Create implementation plans from ticket URLs, file paths, or text descriptions |
+| `plan:implement` | Execute an existing plan with an Agent Team |
+| `plan:add-test-coverage` | Increase test coverage to a target threshold |
+| `plan:fix-linter-error` | Fix all violations of specific ESLint rules |
+| `plan:local-code-review` | Review local branch changes against main |
+| `plan:lower-code-complexity` | Reduce cognitive complexity threshold |
+| `plan:reduce-max-lines` | Reduce max file lines threshold |
+| `plan:reduce-max-lines-per-function` | Reduce max function lines threshold |
+
+### Git Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `git:commit` | Create conventional commits for current changes |
+| `git:commit-and-submit-pr` | Commit changes and create/update a pull request |
+| `git:submit-pr` | Push changes and create or update a pull request |
+| `git:prune` | Prune local branches deleted on remote |
+
+### Integration Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `jira:create` | Create JIRA epics, stories, and tasks |
+| `jira:verify` | Verify JIRA ticket meets organizational standards |
+| `jira:sync` | Sync plan progress to linked JIRA tickets |
+| `sonarqube:check` | Check SonarQube/SonarCloud quality gate failures |
+| `sonarqube:fix` | Fix SonarQube quality gate failures |
+| `pull-request:review` | Check and implement PR review comments |
+| `security:zap-scan` | Run OWASP ZAP baseline security scan |
+
+### Utility Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `tasks:load` | Load tasks from project directory into session |
+| `tasks:sync` | Export session tasks to project directory |
+| `skill-creator` | Guide for creating new skills |
+| `agent-design-best-practices` | Best practices for designing agent files |
+| `jsdoc-best-practices` | JSDoc documentation standards |
+
+See each skill's `SKILL.md` for detailed documentation.
+
+## Customization
+
+### Adding Custom Skills
+
+Skills contain implementation logic and use hyphen-separated naming:
+
+```bash
+mkdir -p .claude/skills/my-namespace-my-skill
+cat > .claude/skills/my-namespace-my-skill/SKILL.md << 'EOF'
+---
+name: my-namespace-my-skill
+description: "What this skill does"
+---
+
+# My Skill
+
+Instructions for the skill...
+EOF
+```
+
+### Adding Custom Commands
+
+Commands are user-facing pass-throughs to skills. Directory nesting creates colon-separated names in the UI (e.g., `my-namespace/my-skill.md` becomes `/my-namespace:my-skill`):
+
+```bash
+mkdir -p .claude/commands/my-namespace
+cat > .claude/commands/my-namespace/my-skill.md << 'EOF'
+---
+description: "What this command does"
+allowed-tools: ["Skill"]
+argument-hint: "<arguments>"
+---
+
+Use the /my-namespace-my-skill skill to do the thing. $ARGUMENTS
+EOF
+```
+
+### Adding Custom Agents
+
+```bash
+cat > .claude/agents/my-agent.md << 'EOF'
+# My Agent
+
+## Role
+Specialized for specific tasks...
+
+## Capabilities
+- Capability 1
+- Capability 2
+
+## Instructions
+How to behave...
+EOF
+```
+
+## Troubleshooting
+
+### Hooks Not Running
+
+1. Check file permissions: `chmod +x .claude/hooks/*.sh`
+2. Verify `$CLAUDE_PROJECT_DIR` is set correctly
+3. Check hook timeout settings
+
+### Plugins Not Loading
+
+1. Verify plugin is installed in your Claude Code installation
+2. Check marketplace access if using marketplace plugins
+3. Review Claude Code logs for plugin errors
+
+### Skills Not Found
+
+1. Ensure skill directory contains a `SKILL.md` file with correct frontmatter
+2. Restart Claude Code to reload skills
+3. Check for syntax errors in skill definition