skill-cslib-vet

# CSLib Vet Skill Thin wrapper that validates CSLib task inputs, identifies changed Lean files via git history, prepares delegation context, and delegates vetting to `cslib-vet-agent` subagent. The agent reads changed files, runs the CI pipeline, checks against all four standards documents, and creates fix tasks interactively. ## Trigger Conditions This skill activates when: - `/vet` command is invoked with task numbers - CSLib tasks need to be vetted against contribution standards - Quality gate check before a PR submission ## Execution Flow ### Stage 1: Input Validation Validate that task numbers exist in state.json: ```bash cd /home/benjamin/Projects/cslib for task_num in $TASK_NUMBERS; do task_entry=$(jq --argjson num "$task_num" \ '.active_projects[] | select(.project_number == $num)' \ specs/state.json 2>/dev/null) if [ -z "$task_entry" ]; then echo "Error: Task $task_num not found in specs/state.json" # Return failed status fi task_name=$(echo "$task_entry" | jq -r '.project_name') task_type=$(echo "$task_entry" | jq -r '.task_type') task_status=$(echo "$task_entry" | jq -r '.status') echo "Task $task_num: $task_name (type=$task_type, status=$task_status)" done ``` ### Stage 2: Preflight Generate a session ID if not passed from the command: ```bash source .claude/scripts/lib/common.sh session_id="${session_id:-$(common_session_id)}" ``` **Note**: The vet skill does NOT change task status. Vetting is orthogonal to the task lifecycle (`not_started` -> `researching` -> `researched` -> `planned` -> `implementing` -> `pr_ready` -> `completed`). Vet operates on tasks in ANY status. ### Stage 2b: Identify Changed Files For each task number, identify Lean files changed by that task using git history: ```bash cd /home/benjamin/Projects/cslib CHANGED_FILES_MAP="{}" for task_num in $TASK_NUMBERS; do echo "Finding files changed by task $task_num..." # Primary: git history via commit messages matching "task N:" lean_files=$(git log --all --format="%H" --grep="task ${task_num}:" \ | xargs -I{} git show --name-only --format="" {} \ | grep "^Cslib/" \ | sort -u 2>/dev/null) # Fallback: uncommitted changes if no commits found if [ -z "$lean_files" ]; then echo " No commits found for task $task_num — checking uncommitted changes..." lean_files=$(git diff --name-only HEAD -- Cslib/ 2>/dev/null) if [ -z "$lean_files" ]; then lean_files=$(git diff --cached --name-only -- Cslib/ 2>/dev/null) fi if [ -z "$lean_files" ]; then lean_files=$(git status --porcelain -- Cslib/ 2>/dev/null | awk '{print $2}' | grep "^Cslib/") fi fi if [ -z "$lean_files" ]; then echo " Warning: No Lean files found for task $task_num (no commits matching 'task ${task_num}:' and no uncommitted changes)." else file_count=$(echo "$lean_files" | grep -c "." 2>/dev/null || echo 0) echo " Found $file_count Lean file(s) for task $task_num" echo "$lean_files" | while read -r f; do echo " - $f" done fi # Store as newline-separated list per task CHANGED_FILES_MAP="${CHANGED_FILES_MAP}|${task_num}:${lean_files}" done ``` ### Stage 3: Prepare Delegation Context Build the delegation context for `cslib-vet-agent`: ```json { "session_id": "{session_id}", "delegation_depth": 1, "delegation_path": ["orchestrator", "vet", "skill-cslib-vet"], "timeout": 3600, "task_context": { "task_numbers": [{task_numbers_array}], "task_names": [{task_names_array}], "task_types": [{task_types_array}] }, "changed_files": { "{task_num_1}": ["{file_1}", "{file_2}"], "{task_num_2}": ["{file_3}"] }, "focus_prompt": "{optional focus from user}", "cslib_dir": "/home/benjamin/Projects/cslib", "standards_paths": { "contributing": "CONTRIBUTING.md", "notation": "NOTATION.md", "organisation": "ORGANISATION.md", "code_of_conduct": "CODE_OF_CONDUCT.md" }, "metadata_file_path": "specs/270_create_vet_command_skill_agent/.return-meta.json" } ``` **Note on metadata_file_path**: Use the actual task directory for the vetted tasks. For the vet operation itself, the metadata path should be `specs/{NNN}_{SLUG}/.return-meta.json` where `NNN`/`SLUG` refer to the vet invocation context (if any). Since `/vet` is a standalone command (not tied to a specific task number), the agent writes metadata to the cslib-vet-agent's own working directory. The skill should set this to a temp path under `.claude/tmp/` or use the first task's directory: ```bash # Use the first task's directory as the metadata home for this vet run first_task_num=$(echo "$TASK_NUMBERS" | awk '{print $1}') task_name=$(jq -r --argjson num "$first_task_num" \ '.active_projects[] | select(.project_number == $num) | .project_name' \ /home/benjamin/Projects/cslib/specs/state.json) task_num_padded=$(printf '%03d' "$first_task_num") task_dir="/home/benjamin/Projects/cslib/specs/${task_num_padded}_${task_name}" mkdir -p "$task_dir" metadata_file_path="specs/${task_num_padded}_${task_name}/.vet-meta.json" ``` ### Stage 4: Invoke Subagent Use Agent tool with `subagent_type: "cslib-vet-agent"` and pass the delegation context as a JSON string in the prompt. The agent will: 1. Read all changed Lean files 2. Read the four standards documents 3. Run the CSLib CI pipeline 4. Analyze files against all standards 5. Present violations to the user interactively 6. Create fix tasks for user-selected violations 7. Write final metadata to the metadata_file_path ### Stage 4b: Self-Execution Fallback **CRITICAL**: If you performed the work above WITHOUT using the Agent tool (i.e., you read files, analyzed violations, or created tasks directly instead of spawning a subagent), you MUST write a `.return-meta.json` file now before proceeding to postflight. Use the appropriate status value. If you DID use the Agent tool, skip this stage — the subagent already wrote the metadata. ## Postflight (ALWAYS EXECUTE) The following stages MUST execute after work is complete, whether done by a subagent or inline. Do NOT skip these stages for any reason. ### Stage 5: Parse Subagent Return and Read Findings Read the metadata and findings files from the paths set in Stage 3: ```bash if [ -f "$task_dir/.vet-meta.json" ]; then return_status=$(jq -r '.status' "$task_dir/.vet-meta.json" 2>/dev/null) violations_found=$(jq -r '.violations_found // 0' "$task_dir/.vet-meta.json" 2>/dev/null) files_analyzed=$(jq -r '.files_analyzed // 0' "$task_dir/.vet-meta.json" 2>/dev/null) ci_passed=$(jq -r '.ci_passed // false' "$task_dir/.vet-meta.json" 2>/dev/null) summary=$(jq -r '.summary // "Vet completed"' "$task_dir/.vet-meta.json" 2>/dev/null) echo "Vet status: $return_status" echo "Violations found: $violations_found" else echo "Warning: Metadata file not found at $task_dir/.vet-meta.json" return_status="partial" fi ``` Read the findings file written by the agent: ```bash findings_file="$task_dir/.vet-findings.json" if [ -f "$findings_file" ]; then echo "Findings file found at $findings_file" # Read using the Read tool for structured access else echo "Warning: Findings file not found — agent may have been interrupted" # Skip interactive stages, go to Stage 9 fi ``` If no violations were found (`violations_found == 0`), display: ``` Vet complete: No violations found. CI pipeline PASSED. ``` Skip to Stage 9. ### Stage 6: Present Violations to User **Use AskUserQuestion** to present the categorized violations and let the user select which categories should become fix tasks. First, display a summary of findings: ``` Vet Results for Task(s) {task_numbers} ======================================= Files analyzed: {count} CI pipeline: {PASSED/FAILED} Violations Found: {total} total Critical: {N} High: {N} Medium: {N} Low: {N} ``` Then use `AskUserQuestion` with `multiSelect: true`. Build options dynamically from the `categories` array in `.vet-findings.json`. Only include categories that have at least one violation: ```json { "question": "Which violation categories should become fix tasks?", "header": "Fix", "multiSelect": true, "options": [ { "label": "{category_name} ({severity}) -- {N} issue(s)", "description": "{brief description of violations in this category}" } ] } ``` Always include a final option: ```json { "label": "No fix tasks needed", "description": "Accept current state without creating fix tasks" } ``` If the user selects "No fix tasks needed" or selects nothing: - Display: "Vet complete. No fix tasks created." - Skip to Stage 9. If the user selects one or more categories, **IMMEDIATELY CONTINUE** to Stage 7. ### Stage 7: Confirm Fix Task Creation Read the `suggested_fix_tasks` from `.vet-findings.json`. Filter to only those whose violations belong to user-selected categories. Present the proposed fix tasks: ``` Proposed Fix Tasks ================== {N} fix task(s) will be created: | # | Title | Type | Severity | Violations | |---|-------|------|----------|------------| | 1 | {task_1_title} | cslib | {severity} | {N} | ``` **Use AskUserQuestion** (single-select) for final confirmation: ```json { "question": "Create these {N} fix task(s) in state.json?", "header": "Confirm", "multiSelect": false, "options": [ { "label": "Yes, create tasks", "description": "Create {N} cslib fix task(s) and add to TODO.md" }, { "label": "Revise -- go back to selection", "description": "Return to Stage 6 to modify which categories to fix" }, { "label": "Cancel -- no tasks", "description": "Exit without creating any fix tasks" } ] } ``` - **Yes**: **IMMEDIATELY CONTINUE** to Stage 8 - **Revise**: Return to Stage 6 (re-present the multiSelect picker) - **Cancel**: Skip to Stage 9 ### Stage 8: Create Fix Tasks For each confirmed fix task from the filtered `suggested_fix_tasks`, create an entry in state.json: ```bash cd /home/benjamin/Projects/cslib now=$(date -u +%Y-%m-%dT%H:%M:%SZ) # For each fix task: next_num=$(jq '.next_project_number' specs/state.json) # One state-write.sh call: the next_project_number bump and the active_projects prepend # are applied under a single mutex acquisition, so concurrent creators cannot collide on # the same number. bash .claude/scripts/state-write.sh \ '.next_project_number = ($next_num + 1) | .active_projects = [{ project_number: $next_num, project_name: $slug, status: "not_started", task_type: $tt, title: $title, description: $desc, created: $now, last_updated: $now,