wtf-p 0.3.0 → 0.5.0

package/core/write-the-f-paper/references/checkpoints.md

@@ -2,6 +2,8 @@
 Writing plans execute with Claude as partner. Checkpoints formalize interaction points where human verification or decisions are needed.
 
 **Core principle:** Claude assists with writing. Checkpoints are for verification and decisions about content direction.
+
+**Visual formatting:** See @ui-brand.md for checkpoint box rendering, status symbols, and stage banners.
 </overview>
 
 <checkpoint_types>
@@ -16,11 +18,32 @@ Writing plans execute with Claude as partner. Checkpoints formalize interaction
 ```xml
 <task type="checkpoint:human-verify" gate="blocking">
   <what-written>[What Claude drafted]</what-written>
-  <how-to-verify>[What to check - argument, tone, accuracy]</how-to-verify>
-  <resume-signal>[How to continue - "approved" or describe issues]</resume-signal>
+  <how-to-verify>
+    [Numbered list of what to check — argument, tone, accuracy]
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 ```
 
+**Rendered output:**
+```
+════════════════════════════════════════
+CHECKPOINT: human-verify
+════════════════════════════════════════
+Task {X} of {Y}: {Name}
+
+What was written:
+  {description of drafted content}
+
+How to verify:
+  1. {Check item 1}
+  2. {Check item 2}
+  3. {Check item 3}
+
+Type "approved" or describe what to change.
+════════════════════════════════════════
+```
+
 **Example:**
 ```xml
 <task type="auto" mode="co-author">
@@ -32,7 +55,6 @@ Writing plans execute with Claude as partner. Checkpoints formalize interaction
 <task type="checkpoint:human-verify" gate="blocking">
   <what-written>Introduction opening paragraph (~150 words)</what-written>
   <how-to-verify>
-    Review and confirm:
     1. Captures the problem accurately
     2. Tone matches your voice
     3. Hook is compelling
@@ -60,6 +82,24 @@ Writing plans execute with Claude as partner. Checkpoints formalize interaction
 </task>
 ```
 
+**Rendered output:**
+```
+════════════════════════════════════════
+CHECKPOINT: decision
+════════════════════════════════════════
+Task {X} of {Y}: {Name}
+
+Decision needed:
+  {What is being decided}
+
+Options:
+  [a] {Name} — {pros}; tradeoff: {cons}
+  [b] {Name} — {pros}; tradeoff: {cons}
+
+Select: a or b
+════════════════════════════════════════
+```
+
 **Example:**
 ```xml
 <task type="checkpoint:decision" gate="blocking">
@@ -81,6 +121,31 @@ Writing plans execute with Claude as partner. Checkpoints formalize interaction
 
 **Do NOT use for:** Writing tasks Claude can draft, formatting, citation formatting.
 
+**Structure:**
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>[What is needed from the human]</action>
+  <instructions>
+    [Specific description of what to provide]
+  </instructions>
+  <resume-signal>[Format of expected input]</resume-signal>
+</task>
+```
+
+**Rendered output:**
+```
+════════════════════════════════════════
+CHECKPOINT: human-action
+════════════════════════════════════════
+Task {X} of {Y}: {Name}
+
+What is needed:
+  {Description of what the author must provide}
+
+Provide: {expected format}
+════════════════════════════════════════
+```
+
 **Example:**
 ```xml
 <task type="checkpoint:human-action" gate="blocking">
@@ -95,23 +160,72 @@ Writing plans execute with Claude as partner. Checkpoints formalize interaction
 
 </checkpoint_types>
 
+<typed_checkpoint_xml>
+
+## Typed Checkpoint XML Format
+
+All checkpoints in plan files use this XML structure. The `type` attribute determines rendering and behavior. The `gate` attribute controls blocking behavior.
+
+### Attributes
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `type` | `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action` | Checkpoint category |
+| `gate` | `blocking` (default), `non-blocking` | Whether execution pauses. Non-blocking checkpoints log for later review. |
+
+### human-verify XML
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-written>[What Claude drafted]</what-written>
+  <how-to-verify>
+    [Numbered list of what to check]
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+
+### decision XML
+
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[What's being decided]</decision>
+  <context>[Why this matters]</context>
+  <options>
+    <option id="{id}"><name>[Name]</name><pros>[Benefits]</pros><cons>[Tradeoffs]</cons></option>
+  </options>
+  <resume-signal>Select: {option-ids}</resume-signal>
+</task>
+```
+
+### human-action XML
+
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>[What is needed]</action>
+  <instructions>[Specific details]</instructions>
+  <resume-signal>Provide: {expected format}</resume-signal>
+</task>
+```
+
+</typed_checkpoint_xml>
+
 <execution_protocol>
 
 When Claude encounters `type="checkpoint:*"`:
 
 1. **Stop immediately** - do not proceed to next task
-2. **Display checkpoint clearly:**
+2. **Display checkpoint** using the branded box format from @ui-brand.md:
 
 ```
 ════════════════════════════════════════
-CHECKPOINT: [Type]
+CHECKPOINT: {type}
 ════════════════════════════════════════
+Task {X} of {Y}: {Name}
 
-Task [X] of [Y]: [Name]
-
-[Checkpoint-specific content]
+{Checkpoint-specific content}
 
-[Resume signal instruction]
+{Resume signal instruction}
 ════════════════════════════════════════
 ```
 
@@ -211,3 +325,40 @@ Why bad: "Good" is meaningless. Specify: accuracy, completeness, tone.
 - When Claude can verify programmatically (word count, structure)
 
 </summary>
+
+<gate_integration>
+
+## Gate Integration
+
+Checkpoints respect gate settings from `.planning/config.json`. This allows authors to control how much confirmation they want during execution.
+
+### Gate Behavior
+
+| Gate Key | Affects | When `false` |
+|----------|---------|-------------|
+| `gates.confirm_write` | `checkpoint:human-verify` during writing | Auto-approved — execution continues without pausing |
+| `gates.confirm_review` | `checkpoint:human-verify` during review | Auto-approved |
+| `gates.confirm_plan` | `checkpoint:human-verify` during planning | Auto-approved |
+| `gates.confirm_outline` | `checkpoint:human-verify` during outlining | Auto-approved |
+
+### Mode Override
+
+When `mode: "yolo"`, all non-safety gates are treated as `false`. Checkpoints are auto-approved and execution proceeds without pausing.
+
+### Always-Confirm Checkpoints
+
+Some checkpoints are never skipped regardless of gate settings or mode:
+
+- **`checkpoint:decision`** — Always pauses. Decisions require human input by definition.
+- **`checkpoint:human-action`** — Always pauses. Agent cannot fabricate human input.
+- **Safety-gated checkpoints** — When `safety.always_confirm_destructive` is `true`, any checkpoint before a destructive operation (deleting content, resetting progress) always pauses.
+
+### Resolution Order
+
+1. Is this a `checkpoint:decision` or `checkpoint:human-action`? → Always pause.
+2. Is `safety.always_confirm_destructive` relevant? → Always pause.
+3. Is `mode: "yolo"`? → Auto-approve.
+4. Is the relevant gate `false`? → Auto-approve.
+5. Otherwise → Pause and wait for user.
+
+</gate_integration>

package/core/write-the-f-paper/references/context-fidelity.md

@@ -0,0 +1,153 @@
+# Context Fidelity
+
+CONTEXT.md is the user decision authority. It captures the user's vision for a section from `/wtfp:discuss-section` and flows through the entire pipeline — planning, writing, and verification.
+
+## CONTEXT.md Structure
+
+Created by `/wtfp:discuss-section`, stored at `.planning/sections/XX-name/XX-CONTEXT.md`:
+
+```markdown
+## Vision
+[What the user wants readers to take away]
+
+## Essential
+[Core content that must be present]
+
+## Boundaries
+[What's explicitly out of scope]
+
+## Concerns
+[What they're worried about]
+
+## Decisions
+[Explicit choices the user made during discussion]
+
+## Deferred Ideas
+[Good ideas the user chose to defer]
+
+## Claude's Discretion
+[Areas where Claude can use judgment]
+```
+
+## Three Decision Categories
+
+### Locked Decisions (from `## Decisions`)
+
+User made an explicit choice. MUST be implemented exactly.
+
+Examples:
+- "Use chronological structure, not thematic"
+- "Lead with the quantitative results, qualitative second"
+- "Frame as contribution to X, not Y"
+
+**Rule**: Every locked decision must map to a task in PLAN.md and appear in written prose.
+
+### Deferred Ideas (from `## Deferred Ideas`)
+
+User acknowledged the idea but chose not to include it now. MUST NOT appear.
+
+Examples:
+- "Extended comparison with method Z — save for revision"
+- "Additional case study — if reviewers ask"
+
+**Rule**: No task, paragraph, or sentence should implement a deferred idea. If a deferred idea is relevant, note it in SUMMARY.md for future consideration.
+
+### Discretion Areas (from `## Claude's Discretion`)
+
+User gave Claude freedom to decide. Use judgment.
+
+Examples:
+- "Order of subsections within methods"
+- "How much background to provide on technique X"
+- "Citation density in the introduction"
+
+**Rule**: Make reasonable choices. Document the choice in SUMMARY.md.
+
+## Loading Pattern
+
+All orchestrators load CONTEXT.md early and pass it to every agent:
+
+```bash
+SECTION_DIR=$(ls -d .planning/sections/${SECTION}-* 2>/dev/null | head -1)
+CONTEXT_CONTENT=$(cat "${SECTION_DIR}"/*-CONTEXT.md 2>/dev/null)
+```
+
+Injected into agent prompts as `<user_decisions>` tags:
+
+```
+<user_decisions>
+[CONTEXT_CONTENT inlined here]
+</user_decisions>
+```
+
+**Critical timing**: Store CONTEXT_CONTENT before spawning any agent. Pass to ALL downstream agents in the pipeline.
+
+## Agent Responsibilities
+
+### section-planner
+
+Before creating any task:
+1. Parse locked decisions → create tasks implementing each one
+2. Parse deferred ideas → verify no task touches them
+3. Parse discretion areas → handle reasonably
+
+Self-check before returning:
+- [ ] Every locked decision has a task implementing it
+- [ ] No task implements a deferred idea
+- [ ] Discretion areas handled reasonably
+
+### plan-checker (Dimension 5: CONTEXT.md Fidelity)
+
+Verification:
+- Parse CONTEXT.md decisions
+- For each locked decision, verify a task implements it
+- Scan all tasks for deferred idea references
+- Check discretion areas are handled
+
+### section-writer
+
+During execution:
+- Implement locked decisions in actual prose
+- Skip deferred content even if it would improve the section
+- Exercise judgment on discretion areas
+- Track which decisions were implemented for SUMMARY.md
+
+### argument-verifier
+
+Post-write check:
+- Were locked decisions implemented in actual prose?
+- Did deferred content accidentally creep in?
+- Were discretion choices reasonable?
+
+## When CONTEXT.md is Missing
+
+Not all sections have CONTEXT.md. If missing:
+
+- `/wtfp:discuss-section` was skipped (user chose to plan directly)
+- Agents operate without user decision constraints
+- Orchestrator may suggest running discuss-section first but does not require it
+
+## Propagation Map
+
+```
+/wtfp:discuss-section
+  → Creates CONTEXT.md
+
+/wtfp:plan-section (orchestrator)
+  → Loads CONTEXT.md as CONTEXT_CONTENT
+  → Passes to section-planner as <user_decisions>
+  → Passes to plan-checker for fidelity check (Dimension 5)
+
+/wtfp:write-section (orchestrator)
+  → Loads CONTEXT.md as CONTEXT_CONTENT
+  → Passes to section-writer as <user_decisions>
+  → Passes to argument-verifier for fidelity check
+
+/wtfp:review-section (orchestrator)
+  → Loads CONTEXT.md as CONTEXT_CONTENT
+  → Passes to section-reviewer for review against user intent
+
+/wtfp:polish-prose (orchestrator)
+  → Loads CONTEXT.md as CONTEXT_CONTENT
+  → Passes to prose-polisher to preserve user decisions during polish
+```

package/core/write-the-f-paper/references/deviation-rules.md

@@ -0,0 +1,150 @@
+# Deviation Rules for Writing Agents
+
+Rules governing what writing agents can change without asking versus what requires human confirmation. These apply during plan execution when an agent encounters content that needs adjustment beyond the explicit task instructions.
+
+Deviations are tracked in SUMMARY.md under "Deviations from Plan".
+
+## Rule 1: Auto-fix (No Confirmation)
+
+**Trigger:** Agent encounters a mechanical error that is objectively wrong.
+
+**Scope:** Typos, citation formatting errors, markdown formatting issues, reference numbering, broken links, inconsistent heading levels, malformed lists.
+
+**Action:** Fix immediately. Do not pause. Do not ask.
+
+**Logging:** Add entry to SUMMARY.md deviations list:
+```
+[Rule 1 - Auto-fix] Fixed {description} in {file}
+```
+
+**Example:**
+Agent is writing the methods section and notices the introduction references "[Smith et al., 2023]" but the citation list has it as "[Smith et al. 2023]" (missing comma). Agent fixes the citation format to match the configured `citation_style` and logs:
+```
+[Rule 1 - Auto-fix] Fixed missing comma in Smith et al. citation (introduction.md)
+```
+
+**Rationale:** These are errors, not choices. No reasonable author would want to keep them.
+
+## Rule 2: Auto-add (No Confirmation)
+
+**Trigger:** Agent identifies a gap in prose flow that can be bridged with a small addition.
+
+**Scope:** Transition sentences between paragraphs, topic sentences for paragraphs that lack them, brief connecting phrases between arguments, missing paragraph breaks in wall-of-text blocks.
+
+**Action:** Add the missing element. Continue execution.
+
+**Logging:** Add entry to SUMMARY.md deviations list:
+```
+[Rule 2 - Auto-add] Added {description} in {file}
+```
+
+**Example:**
+Agent is drafting the results section and the plan says "Task 3: Write secondary findings". The previous paragraph (Task 2 output) ends abruptly. Agent adds a transition sentence ("Beyond the primary effects, several secondary patterns emerged.") before writing the Task 3 content, and logs:
+```
+[Rule 2 - Auto-add] Added transition sentence between primary and secondary findings (results.md)
+```
+
+**Rationale:** Prose flow is expected. These additions are small (1-2 sentences), non-argumentative, and improve readability without changing meaning.
+
+## Rule 3: Ask-first (Requires Confirmation)
+
+**Trigger:** Agent believes content would benefit from a structural or substantive change.
+
+**Scope:** Reordering paragraphs, splitting sections, merging sections, argument reframing, removing content (even redundant content), changing established terminology, altering emphasis or tone, adding new subsections.
+
+**Action:** Stop execution. Present the proposed change as a checkpoint. Wait for confirmation before proceeding.
+
+**Logging:** If approved and applied, add entry to SUMMARY.md deviations list:
+```
+[Rule 3 - Ask-first] {description} — approved by author
+```
+If rejected:
+```
+[Rule 3 - Ask-first] Proposed {description} — rejected, continued as planned
+```
+
+**Checkpoint format:**
+```
+════════════════════════════════════════
+CHECKPOINT: decision
+════════════════════════════════════════
+Task {X} of {Y}: {Name}
+
+Proposed deviation (Rule 3 — structural change):
+  {Description of what agent wants to change}
+
+Reason:
+  {Why this would improve the paper}
+
+Impact:
+  {What changes if applied}
+
+Options:
+  [a] Apply the change
+  [b] Continue as planned
+
+Select: a or b
+════════════════════════════════════════
+```
+
+**Example:**
+Agent is writing the discussion section and realizes the "limitations" paragraph would read better before "implications" (plan has them in reverse order). Agent pauses:
+```
+Proposed deviation (Rule 3 — structural change):
+  Move limitations paragraph before implications paragraph
+
+Reason:
+  Addressing limitations first makes the implications argument stronger —
+  reader knows the caveats before seeing the claims.
+
+Impact:
+  Paragraphs 3 and 4 swap order. No content changes.
+```
+
+**Rationale:** Structure and argument framing are authorial choices. The agent may have good reasons, but the author decides.
+
+## Rule 4: Never (Agent Cannot Do)
+
+**Trigger:** Agent is tempted to strengthen the paper by adding unsupported content.
+
+**Scope:** Adding claims not supported by cited evidence, fabricating citations (inventing author names, titles, DOIs), changing the author's stated position or thesis, inserting data or results not provided by the author, adding acknowledgments or author contributions the author did not specify.
+
+**Action:** Do not do it. If the agent identifies a gap where such content is needed, flag it as a TODO for the author.
+
+**Logging:** If agent identifies a gap, add a TODO:
+```
+[Rule 4 - Gap identified] {description} — needs author input
+```
+
+**TODO format in content:**
+```markdown
+<!-- TODO: [Rule 4] Citation needed for claim about X. Author to provide. -->
+```
+
+**Example:**
+Agent is writing the discussion and the argument would be stronger with a citation supporting the claim "distributed systems show 40% improvement". Agent does not invent a citation. Instead:
+```markdown
+Distributed systems show significant improvement in throughput
+<!-- TODO: [Rule 4] Citation needed for throughput improvement claim. Author to provide specific reference and percentage. -->
+```
+And logs:
+```
+[Rule 4 - Gap identified] Missing citation for throughput improvement claim (discussion.md) — needs author input
+```
+
+**Rationale:** Academic integrity is non-negotiable. Fabricated citations are research misconduct. The author's thesis is their intellectual contribution — agents assist, they do not override.
+
+## Rule Priority
+
+When multiple rules could apply:
+
+1. **Rule 4 always wins.** If the fix would require fabricating evidence, it is Rule 4 regardless of how "small" it seems.
+2. **Rule 3 over Rule 2.** If an addition changes argument structure (not just flow), it is Rule 3.
+3. **Rule 1 over Rule 2.** If the issue is an error (not a gap), fix it as Rule 1.
+
+**Edge cases:**
+- Fixing a citation that exists but is formatted wrong: Rule 1 (formatting error)
+- Adding a citation that does not exist in the bibliography: Rule 4 (fabrication)
+- Adding a topic sentence: Rule 2 (prose flow)
+- Rewriting a topic sentence to change its claim: Rule 3 (substantive change)
+- Fixing a factual error in author-provided content: Rule 3 (the author wrote it intentionally — ask first)

package/core/write-the-f-paper/references/git-integration.md

@@ -239,3 +239,83 @@ Each plan produces 3-5 commits (tasks + metadata). Clear, granular, recoverable.
 - Writing evolution is clear
 
 </commit_strategy_rationale>
+
+<branching_strategies>
+
+## Branching Strategies
+
+Controlled by `git.branching_strategy` in `.planning/config.json`. Three strategies available.
+
+### Strategy: "none" (default)
+
+**When to use:** Solo writing, simple papers, no parallel section work.
+
+**Behavior:** All commits go to the current branch. No branch creation, no merging.
+
+**Branch lifecycle:** None. Work happens wherever `git branch` points.
+
+**Merge behavior:** N/A.
+
+This is the simplest option. Good for most academic writing workflows where one person writes sequentially.
+
+### Strategy: "section"
+
+**When to use:** Papers with independent sections that benefit from parallel work, or when you want clean per-section history.
+
+**Behavior:** Each section gets its own branch created from the current branch when `plan-section` starts.
+
+**Branch name:** From `git.section_branch_template` (default: `wtfp/section-{section}-{slug}`).
+- `{section}` = section number (e.g., `01`, `02`)
+- `{slug}` = slugified section name (e.g., `introduction`, `related-work`)
+- Example: `wtfp/section-02-related-work`
+
+**Branch lifecycle:**
+1. `plan-section` creates branch: `git checkout -b wtfp/section-{section}-{slug}`
+2. All writing tasks for that section commit to the section branch
+3. `review-section` runs on the section branch
+4. After review passes, branch is merged back to the base branch
+5. Branch is deleted after successful merge
+
+**Merge behavior:**
+- If `git.squash_on_merge` is `false`: merge commit preserves per-task history
+- If `git.squash_on_merge` is `true`: squash merge collapses all section commits into one
+
+**Parallel work:** Multiple section branches can exist simultaneously. Different sections can be planned and written in parallel (when `parallelization.enabled` is `true`).
+
+### Strategy: "submission"
+
+**When to use:** Papers with clear submission deadlines (conference deadlines, journal revisions), or when you want milestone-based history.
+
+**Behavior:** Milestone branches created by `submit-milestone` for each submission target.
+
+**Branch name:** From `git.submission_branch_template` (default: `wtfp/{milestone}-{slug}`).
+- `{milestone}` = milestone name (e.g., `draft-1`, `camera-ready`, `revision-2`)
+- `{slug}` = slugified paper title (e.g., `distributed-consensus`)
+- Example: `wtfp/camera-ready-distributed-consensus`
+
+**Branch lifecycle:**
+1. `submit-milestone` creates branch from current state
+2. Final polishing and formatting commits go to the milestone branch
+3. Submission checklist verification runs on the branch
+4. Branch is tagged on completion: `wtfp/submitted/{milestone}-{date}`
+5. Branch is merged back to the base branch
+
+**Merge behavior:**
+- If `git.squash_on_merge` is `false`: merge commit preserves milestone history
+- If `git.squash_on_merge` is `true`: squash merge collapses milestone into one commit
+
+**Tags:** Each completed milestone is tagged for easy reference:
+```
+wtfp/submitted/draft-1-2024-03-15
+wtfp/submitted/camera-ready-2024-06-01
+```
+
+### Squash on Merge
+
+Controlled by `git.squash_on_merge` (default: `false`).
+
+**When `false` (default):** Per-task commit history is preserved on merge. The full writing evolution is visible in `git log`. Recommended for most workflows — granular history aids future Claude sessions and revision tracking.
+
+**When `true`:** All commits from a section/milestone branch are squashed into a single commit on merge. Produces a cleaner `git log` but loses per-task granularity. Use when the final state matters more than the writing process.
+
+</branching_strategies>