wtf-p 0.3.0 → 0.5.0

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

@@ -0,0 +1,246 @@
+---
+name: wtfp:verify-work
+description: Test a written section against its plan, one check at a time
+---
+
+<execution_context>
+@~/.opencode/write-the-f-paper/workflows/verify-work.md
+@~/.opencode/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 the question tool:
+- 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 the question tool:
+- 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/opencode/commands/wtfp/write-section.md

@@ -0,0 +1,228 @@
+---
+name: wtfp:write-section
+description: Execute a PLAN.md to write section content
+argument-hint: "[path-to-PLAN.md]"
+---
+
+<execution_context>
+@~/.opencode/write-the-f-paper/workflows/execute-section.md
+@~/.opencode/write-the-f-paper/references/git-integration.md
+</execution_context>
+
+<objective>
+Execute a PLAN.md file to write section 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.
+
+**Why subagents:** Writing burns context fast. Fresh agent gets peak prose quality. Verification in fresh context catches what writer missed.
+</objective>
+
+<context>
+Plan path: $ARGUMENTS (path to a PLAN.md file)
+</context>
+
+<process>
+
+## 1. Validate Environment and Resolve Model Profile
+
+```bash
+[ ! -f "$ARGUMENTS" ] && echo "ERROR: Plan not found at $ARGUMENTS" && exit 1
+ls .planning/ 2>/dev/null
+```
+
+**Resolve model profile:**
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| section-writer | opus | sonnet | sonnet |
+| argument-verifier | sonnet | sonnet | haiku |
+
+**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")
+
+# 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")
+```
+
+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."
+```
+
+## 2. Read Context Files
+
+```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)
+```
+
+## 3. Gate Check: Confirm Before Writing
+
+**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 the question tool and wait for confirmation before proceeding.
+
+**If GATE_CONFIRM_WRITE is "false" AND (SAFETY_DESTRUCTIVE is "false" OR no existing SUMMARY.md):**
+Skip confirmation and proceed directly to writing.
+
+## 4. Spawn wtfp-section-writer Agent
+
+```
+---
+ WTF-P > WRITING SECTION
+---
+```
+
+Fill prompt with inlined content and spawn:
+
+```
+Task(
+  prompt="First, read ~/.opencode/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}"
+)
+```
+
+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.
+
+## 5. Handle Writer Return
+
+**`## WRITING COMPLETE`:** Proceed to verification check.
+
+**`## CHECKPOINT REACHED`:** Present to user, get response.
+
+**`## WRITING BLOCKED`:** Show blocker, offer options.
+
+## 6. Goal-Backward Verification (if enabled)
+
+```bash
+WORKFLOW_VERIFIER=$(cat .planning/config.json 2>/dev/null | grep -o '"verifier"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
+
+**If verifier is true:**
+
+```bash
+WRITTEN_CONTENT=$(cat paper/*.md 2>/dev/null)
+```
+
+Spawn `wtfp-argument-verifier` with written content + PLAN goals + argument-map.
+
+**If VERIFIED:** Proceed to done.
+
+**If GAPS_FOUND:** Present gaps to user. Options: fix now, accept, plan revision.
+
+**If HUMAN_NEEDED:** Present what needs human review.
+
+## 6b. Commit with commit_docs Guard
+
+Before any git commit, check commit_docs setting:
+
+```bash
+COMMIT_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
+
+**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)"
+
+**If commit_docs = "true" (default):**
+- Include `.planning/` files in commits as normal
+
+## 7. Git Branch Merge (if section branch strategy)
+
+```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)
+```
+
+**If branching_strategy = "section" AND current branch matches `wtfp/section-*`:**
+
+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")
+   ```
+
+2. Read base branch stored during plan-section:
+   ```bash
+   BASE_BRANCH=$(cat .planning/.section_base_branch 2>/dev/null || echo "main")
+   ```
+
+3. Perform merge based on squash setting:
+
+   **If squash=true:**
+   ```bash
+   git checkout "$BASE_BRANCH"
+   git merge --squash "$CURRENT_BRANCH"
+   git commit -m "write(${SECTION}): complete ${SECTION_NAME}"
+   ```
+
+   **If squash=false:**
+   ```bash
+   git checkout "$BASE_BRANCH"
+   git merge "$CURRENT_BRANCH" --no-ff -m "merge: section ${SECTION} complete"
+   ```
+
+4. Delete section branch:
+   ```bash
+   git branch -d "$CURRENT_BRANCH"
+   rm -f .planning/.section_base_branch
+   ```
+
+5. Log: "Merged section branch: $CURRENT_BRANCH -> $BASE_BRANCH"
+
+**If branching_strategy = "none" or "submission":** No merge action.
+
+## 8. Present Final Status
+
+</process>
+
+<offer_next>
+
+---
+ WTF-P > SECTION WRITTEN
+---
+
+**{Section Name}** -- {W} words, mode: {mode}
+
+Verification: {Verified | Gaps found | Skipped}
+
+---
+
+## > Next Up
+
+**Review section** -- run verification
+
+`/wtfp:review-section {section}`
+
+<sub>`/clear` first -> fresh context window</sub>
+
+---
+
+</offer_next>
+
+<success_criteria>
+- [ ] Plan validated and loaded
+- [ ] Section-writer spawned with full context
+- [ ] Content written to paper/ directory
+- [ ] SUMMARY.md created
+- [ ] STATE.md updated
+- [ ] Argument-verifier spawned (if workflow.verifier enabled)
+- [ ] Verification result handled
+- [ ] User knows next steps
+</success_criteria>