wtf-p 0.4.0 → 0.5.0

package/vendors/claude/commands/wtfp/verify-work.md

@@ -0,0 +1,254 @@
+---
+name: wtfp:verify-work
+description: Test a written section against its plan, one check at a time
+argument-hint: "[section-number]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/write-the-f-paper/workflows/verify-work.md
+@~/.claude/write-the-f-paper/references/ui-brand.md
+</execution_context>
+
+<objective>
+Conversational verification of a written section. Presents one test at a time.
+Persists state in UAT.md that survives /clear.
+
+**Orchestrator role:** Load UAT.md (or create from PLAN.md + argument-map),
+present next pending test, record result, update UAT.md, route on completion.
+
+**Why no subagent:** Verification is a conversation loop, not a creative task.
+The orchestrator reads artifacts, extracts tests, and guides the user through
+each one. State persists via UAT.md file reads/writes.
+</objective>
+
+<context>
+Section: $ARGUMENTS (section number or name)
+</context>
+
+<process>
+
+## 1. Validate Environment
+
+```bash
+[ ! -f ".planning/PROJECT.md" ] && echo "ERROR: No project initialized. Run /wtfp:new-paper first." && exit 1
+```
+
+Resolve section from $ARGUMENTS:
+- If numeric (e.g., "3"): find `.planning/sections/03-*`
+- If name (e.g., "methods"): find `.planning/sections/*-methods*`
+
+```bash
+SECTION_DIR=$(ls -d .planning/sections/${SECTION}-* 2>/dev/null | head -1)
+[ -z "$SECTION_DIR" ] && echo "ERROR: Section '$ARGUMENTS' not found in .planning/sections/" && exit 1
+```
+
+Verify section was written (SUMMARY.md exists):
+
+```bash
+ls "$SECTION_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+If no SUMMARY.md:
+```
+Section has not been written yet. Cannot verify unwritten content.
+
+Write it first: /wtfp:write-section [plan-path]
+```
+
+## 2. Load or Resume UAT
+
+```bash
+UAT_PATH="$SECTION_DIR/UAT.md"
+```
+
+**If UAT.md exists (resuming):**
+
+Read UAT.md. Count tests by status:
+- Total tests
+- Passed (result: pass)
+- Skipped (result: skip)
+- Issues (result: issue)
+- Pending (result: pending)
+
+Report:
+```
+Resuming verification for Section [X]: [Name]
+[completed]/[total] tests evaluated ([pending] remaining)
+```
+
+Find the first test with `result: pending` and proceed to step 3.
+
+**If UAT.md does not exist (starting fresh):**
+
+Derive tests from two sources:
+
+**Source 1: PLAN.md success criteria**
+```bash
+cat "$SECTION_DIR"/*-PLAN.md
+```
+Extract each `- [ ]` item from `<success_criteria>`. Each becomes a test tagged `[plan]`.
+
+**Source 2: Argument-map claims**
+```bash
+cat .planning/structure/argument-map.md 2>/dev/null
+```
+Find claims assigned to this section. Each becomes a test tagged `[argument-map]`.
+
+Write UAT.md:
+
+```yaml
+---
+status: testing
+section: [section-dir-name]
+started: [ISO timestamp]
+last_test: 0
+---
+```
+
+Followed by `## Tests` with all derived tests (numbered, pending), `## Summary` with initial counts, empty `## Gaps`.
+
+Report:
+```
+Starting verification for Section [X]: [Name]
+[total] tests derived ([plan-count] from plan, [map-count] from argument-map)
+```
+
+## 3. Present Next Test
+
+Find the next test with `result: pending`.
+
+Display using branded checkpoint box:
+
+```
+════════════════════════════════════════
+VERIFICATION: Test {N} of {total}
+════════════════════════════════════════
+
+Source: {[plan] or [argument-map]}
+
+  {The criterion or claim being verified}
+
+Check: Does this section satisfy the above?
+════════════════════════════════════════
+```
+
+Use AskUserQuestion:
+- header: "Verification"
+- question: "[The criterion or claim text]"
+- options:
+  - "Pass - meets criteria"
+  - "Skip - not applicable"
+  - "Issue - describe the problem"
+
+## 4. Record and Continue
+
+Update UAT.md with the result:
+- Set `result:` to pass, skip, or issue
+- Set `reason:` to user explanation (empty for pass/skip unless user elaborated)
+- Update `last_test` in frontmatter
+
+**If "Issue" selected:**
+
+Ask for the problem description (user already selected "Issue" so get details):
+
+Then ask for severity:
+
+Use AskUserQuestion:
+- header: "Severity"
+- question: "How severe is this issue?"
+- options:
+  - "Major - undermines argument, must fix"
+  - "Minor - weakens but doesn't invalidate"
+  - "Cosmetic - polish issue, fix during final pass"
+
+Add to `## Gaps` section:
+```markdown
+- claim: "[criterion or claim text]"
+  status: issue
+  reason: "[user's description]"
+  severity: [major|minor|cosmetic]
+```
+
+**Write UAT.md to disk** after each result (persistence).
+
+**If more pending tests:** Return to step 3.
+
+**If all tests evaluated:** Proceed to step 5.
+
+## 5. Route on Completion
+
+Set `status: complete` in UAT.md frontmatter. Calculate final counts.
+
+**If no issues (all pass/skip):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► VERIFICATION PASSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Section [X]: [Name]
+Tests: [passed] passed, [skipped] skipped, 0 issues
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Check progress** — see overall paper status
+
+`/wtfp:progress`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────
+```
+
+**If issues found:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► VERIFICATION: ISSUES FOUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Section [X]: [Name]
+Tests: [passed] passed, [issues] issues, [skipped] skipped
+
+## Gap Summary
+
+| # | Claim/Criterion | Severity | Reason |
+|---|-----------------|----------|--------|
+| 1 | [text]          | major    | [reason] |
+| 2 | [text]          | minor    | [reason] |
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan revision** — create fix plan for identified issues
+
+`/wtfp:plan-revision [section]`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────
+```
+
+</process>
+
+<success_criteria>
+- [ ] Section resolved from arguments
+- [ ] SUMMARY.md validated (section was written)
+- [ ] Tests derived from PLAN.md success_criteria AND argument-map.md claims
+- [ ] UAT.md created or resumed
+- [ ] Each test presented one at a time
+- [ ] Results recorded with persistence (survives /clear)
+- [ ] Issues classified by severity
+- [ ] Routes to plan-revision when issues found
+- [ ] Routes to progress when verification passes
+</success_criteria>

package/vendors/claude/commands/wtfp/write-section.md

@@ -1,6 +1,6 @@
 ---
 name: wtfp:write-section
-description: Execute a PLAN.md to write section content
+description: Write a section by executing its plan
 argument-hint: "[path-to-PLAN.md]"
 allowed-tools:
   - Read
@@ -9,265 +9,229 @@ allowed-tools:
   - Edit
   - Glob
   - Grep
-  - AskUserQuestion
   - Task
+  - AskUserQuestion
 ---
 
+<execution_context>
+@~/.claude/write-the-f-paper/workflows/execute-section.md
+@~/.claude/write-the-f-paper/references/git-integration.md
+</execution_context>
+
 <objective>
 Execute a PLAN.md file to write section content.
 
-Takes the path to a PLAN.md file and executes its tasks sequentially, writing the actual paper content.
+**Orchestrator role:** Validate plan, resolve model profile, read context files, spawn section-writer agent, optionally run argument-verifier post-write, route based on verification, present results.
 
-Creates SUMMARY.md documenting what was written and updates STATE.md with progress.
+**Why subagents:** Writing burns context fast. Fresh agent gets peak prose quality. Verification in fresh context catches what writer missed.
 </objective>
 
-<execution_context>
-@~/.claude/write-the-f-paper/workflows/execute-section.md
-@~/.claude/write-the-f-paper/templates/summary.md
-@~/.claude/write-the-f-paper/references/git-integration.md
-</execution_context>
+<context>
+Plan path: $ARGUMENTS (path to a PLAN.md file)
+</context>
 
 <process>
 
-<step name="verify">
-**Verify plan exists:**
+## 1. Validate Environment and Resolve Model Profile
 
 ```bash
 [ ! -f "$ARGUMENTS" ] && echo "ERROR: Plan not found at $ARGUMENTS" && exit 1
+ls .planning/ 2>/dev/null
 ```
 
-Check plan hasn't already been executed (SUMMARY.md exists):
+**Resolve model profile:**
 ```bash
-SUMMARY_PATH="${ARGUMENTS/PLAN.md/SUMMARY.md}"
-[ -f "$SUMMARY_PATH" ] && echo "WARNING: This plan already has a SUMMARY.md. Re-executing will overwrite."
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
 ```
 
-</step>
+**Model lookup table:**
 
-<step name="load">
-**Load plan and all context:**
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| section-writer | opus | sonnet | sonnet |
+| argument-verifier | sonnet | sonnet | haiku |
 
-1. Read the PLAN.md file specified in $ARGUMENTS
-2. Parse the frontmatter (section, plan, mode, word_target)
-3. Load all @context files referenced in the plan
-4. Read PROJECT.md for core argument
-5. Read argument-map.md for relevant claims
-6. Read any prior section content for continuity
-</step>
-
-<step name="mode_setup">
-**Configure for writing mode:**
-
-Based on `mode` from plan frontmatter:
+**Resolve gate and safety flags:**
+```bash
+# Gate: confirm_write — skip confirmation if false
+GATE_CONFIRM_WRITE=$(cat .planning/config.json 2>/dev/null | grep -o '"confirm_write"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
 
-**Co-Author Mode:**
-- Claude writes draft prose
-- User refines afterward
-- Output: Full draft text
+# Safety: always_confirm_destructive — force confirmation for destructive ops
+SAFETY_DESTRUCTIVE=$(cat .planning/config.json 2>/dev/null | grep -o '"always_confirm_destructive"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
 
-**Scaffold Mode:**
-- Claude creates detailed outline with key points
-- User fills in actual prose
-- Output: Structured outline for each paragraph
+Check for existing SUMMARY.md:
+```bash
+SUMMARY_PATH="${ARGUMENTS/PLAN.md/SUMMARY.md}"
+[ -f "$SUMMARY_PATH" ] && echo "WARNING: SUMMARY.md exists. Re-executing will overwrite."
+```
 
-**Reviewer Mode:**
-- Prompt user to write section
-- Claude provides feedback after each chunk
-- Output: User's text + Claude's comments
+## 2. Read Context Files
 
-</step>
+```bash
+PLAN_CONTENT=$(cat "$ARGUMENTS")
+STATE_CONTENT=$(cat .planning/STATE.md)
+PROJECT_CONTENT=$(cat .planning/PROJECT.md)
+ARGMAP_CONTENT=$(cat .planning/structure/argument-map.md 2>/dev/null)
+
+# Derive section dir from plan path
+SECTION_DIR=$(dirname "$ARGUMENTS")
+CONTEXT_CONTENT=$(cat "${SECTION_DIR}"/*-CONTEXT.md 2>/dev/null)
+PRIOR_CONTENT=$(cat paper/*.md 2>/dev/null | head -500)
+```
 
-<step name="execute_tasks">
-**Execute each task in the plan:**
+## 3. Gate Check: Confirm Before Writing
 
-For each `<task>` in `<tasks>`:
+**If GATE_CONFIRM_WRITE is "true" (default) OR SAFETY_DESTRUCTIVE is "true" and SUMMARY.md exists (re-execution is destructive):**
+Present plan summary to user via AskUserQuestion and wait for confirmation before proceeding.
 
-1. Read the task requirements (action, target, verify)
-2. Based on mode:
-   - **Co-Author:** Write the draft content
-   - **Scaffold:** Create detailed outline
-   - **Reviewer:** Prompt user to write, then critique
-3. Verify the output meets task criteria
-4. Track word count
-5. Commit after each task (if substantive)
+**If GATE_CONFIRM_WRITE is "false" AND (SAFETY_DESTRUCTIVE is "false" OR no existing SUMMARY.md):**
+Skip confirmation and proceed directly to writing.
 
-**Per-task commit:**
-```bash
-git add paper/[section].md  # or wherever content lives
-git commit -m "$(cat <<'EOF'
-write(XX-YY): [task description]
+## 4. Spawn wtfp-section-writer Agent
 
-[Word count] words for [section]
-EOF
-)"
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► WRITING SECTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-</step>
+Fill prompt with inlined content and spawn:
 
-<step name="deviation_rules">
-**Handle deviations during writing:**
+```
+Task(
+  prompt="First, read ~/.claude/agents/wtfp/section-writer.md for your role and instructions.\n\n" + filled_writing_prompt,
+  subagent_type="general-purpose",
+  model="{writer_model}",
+  description="Write Section {X}"
+)
+```
 
-| Type | Action |
-|------|--------|
-| Citation needed but not in sources | Flag, continue, note in SUMMARY |
-| Argument weak | Note in SUMMARY for revision |
-| Word count significantly off | Note in SUMMARY, suggest adjustment |
-| Logical gap discovered | Note in SUMMARY, may need ISSUES.md |
-| Better structure found | Implement if minor, note if major |
+Writing prompt includes: `<plan>` with full PLAN.md content, `<project_context>` with PROJECT + STATE + argument-map, `<user_decisions>` with CONTEXT_CONTENT, `<prior_content>` with existing paper content for continuity.
 
-**Auto-fix:**
-- Minor prose improvements
-- Citation format fixes
-- Paragraph flow improvements
+## 5. Handle Writer Return
 
-**Log for later:**
-- Missing citations (add to sources/literature.md gap list)
-- Argument weaknesses (ISSUES.md)
-- Structure suggestions beyond plan scope
-</step>
+**`## WRITING COMPLETE`:** Proceed to verification check.
 
-<step name="output_content">
-**Write output content:**
+**`## CHECKPOINT REACHED`:** Present to user, get response.
 
-Content goes to `paper/` directory:
-- `paper/[section-name].md` - Markdown section content
-- Or appended to `paper/paper.md` if single-file format
+**`## WRITING BLOCKED`:** Show blocker, offer options.
 
-Include proper markdown structure:
-```markdown
-## [Section Title]
+## 6. Goal-Backward Verification (if enabled)
 
-[Content from tasks...]
+```bash
+WORKFLOW_VERIFIER=$(cat .planning/config.json 2>/dev/null | grep -o '"verifier"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
 
-### [Subsection if applicable]
+**If verifier is true:**
 
-[More content...]
+```bash
+WRITTEN_CONTENT=$(cat paper/*.md 2>/dev/null)
 ```
 
-Track all files created/modified for SUMMARY.
-</step>
+Spawn `wtfp-argument-verifier` with written content + PLAN goals + argument-map.
 
-<step name="summary">
-**Create SUMMARY.md:**
+**If VERIFIED:** Proceed to done.
 
-```markdown
----
-section: XX-name
-plan: YY
-mode: [co-author/scaffold/reviewer]
-word_count: [actual]
-word_target: [target]
----
+**If GAPS_FOUND:** Present gaps to user. Options: fix now, accept, plan revision.
 
-# Section [XX]-[YY] Summary
+**If HUMAN_NEEDED:** Present what needs human review.
 
-## What Was Written
-- [Task 1]: [what was accomplished]
-- [Task 2]: [what was accomplished]
-- [...]
+## 6b. Commit with commit_docs Guard
 
-## Word Count
-- Target: [X] words
-- Actual: [Y] words
-- Variance: [+/- Z]%
+Before any git commit, check commit_docs setting:
 
-## Files Created/Modified
-- paper/[section].md: [description]
+```bash
+COMMIT_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
 
-## Key Points Made
-- [Argument 1]
-- [Argument 2]
-- [...]
+**If commit_docs = "false":**
+- Skip `git add` for any `.planning/` paths
+- Only commit paper content files (e.g., `paper/*.md`)
+- Log: "Skipping planning docs commit (commit_docs: false)"
 
-## Citations Used
-- [citation-key]: [where used]
-- [...]
+**If commit_docs = "true" (default):**
+- Include `.planning/` files in commits as normal
 
-## Decisions Made
-| Decision | Rationale |
-|----------|-----------|
-| [choice] | [why] |
+## 7. Git Branch Merge (if section branch strategy)
 
-## Issues Noted
-- [Any problems discovered during writing]
-- [Gaps that need addressing]
+```bash
+BRANCH_STRATEGY=$(cat .planning/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "none")
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null)
+```
 
-## Next Steps
-- [What should happen next]
+**If branching_strategy = "section" AND current branch matches `wtfp/section-*`:**
 
----
-*Written: [timestamp]*
-```
+1. Read squash_on_merge setting:
+   ```bash
+   SQUASH=$(cat .planning/config.json 2>/dev/null | grep -o '"squash_on_merge"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "false")
+   ```
 
-</step>
+2. Read base branch stored during plan-section:
+   ```bash
+   BASE_BRANCH=$(cat .planning/.section_base_branch 2>/dev/null || echo "main")
+   ```
 
-<step name="update_state">
-**Update STATE.md:**
+3. Perform merge based on squash setting:
 
-- Update current position
-- Add word count to progress
-- Note any decisions made
-- Log any issues discovered
-- Update argument strength assessment
-</step>
+   **If squash=true:**
+   ```bash
+   git checkout "$BASE_BRANCH"
+   git merge --squash "$CURRENT_BRANCH"
+   git commit -m "write(${SECTION}): complete ${SECTION_NAME}"
+   ```
 
-<step name="final_commit">
-**Final commit:**
+   **If squash=false:**
+   ```bash
+   git checkout "$BASE_BRANCH"
+   git merge "$CURRENT_BRANCH" --no-ff -m "merge: section ${SECTION} complete"
+   ```
 
-```bash
-git add .planning/sections/XX-name/XX-YY-SUMMARY.md .planning/STATE.md paper/
-git commit -m "$(cat <<'EOF'
-docs(XX-YY): complete [section name] writing
-
-[Word count] words written
-Mode: [mode]
-EOF
-)"
-```
+4. Delete section branch:
+   ```bash
+   git branch -d "$CURRENT_BRANCH"
+   rm -f .planning/.section_base_branch
+   ```
 
-</step>
+5. Log: "Merged section branch: $CURRENT_BRANCH -> $BASE_BRANCH"
 
-<step name="done">
-**Present completion:**
+**If branching_strategy = "none" or "submission":** No merge action.
 
-```
-Section written:
+## 8. Present Final Status
 
-- Content: paper/[section].md ([Y] words)
-- Summary: .planning/sections/XX-name/XX-YY-SUMMARY.md
-- Progress: [current]/[total] words ([%]%)
+</process>
 
-## Written
+<offer_next>
 
-[Brief summary of what was written]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► SECTION WRITTEN ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-## Issues Noted
+**{Section Name}** — {W} words, mode: {mode}
 
-[Any issues discovered, or "None"]
+Verification: {Verified | Gaps found | Skipped}
 
----
+───────────────────────────────────────────
 
 ## ▶ Next Up
 
-[Based on STATE.md - next plan, next section, or review]
+**Review section** — run verification
 
-`/wtfp:[appropriate-command]`
+`/wtfp:review-section {section}`
 
 <sub>`/clear` first → fresh context window</sub>
 
----
-```
+───────────────────────────────────────────
 
-</step>
-
-</process>
+</offer_next>
 
 <success_criteria>
-- [ ] All tasks in PLAN.md executed
+- [ ] Plan validated and loaded
+- [ ] Section-writer spawned with full context
 - [ ] Content written to paper/ directory
-- [ ] Word count tracked and within tolerance
-- [ ] SUMMARY.md created with full documentation
-- [ ] STATE.md updated with progress
-- [ ] All changes committed to git
-- [ ] Next action clearly identified
+- [ ] SUMMARY.md created
+- [ ] STATE.md updated
+- [ ] Argument-verifier spawned (if workflow.verifier enabled)
+- [ ] Verification result handled
+- [ ] User knows next steps
 </success_criteria>