---
phase: 01.7-refactor-artifacts-for-grep-synergy
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/gsd_lite/template/WORK.md
  - src/gsd_lite/template/STATE.md
  - src/gsd_lite/template/PROTOCOL.md
  - src/gsd_lite/template/workflows/housekeeping.md
autonomous: true

must_haves:
  truths:
    - "Fresh agent can grep WORK.md with ^## to discover all sections"
    - "Fresh agent can grep [LOG-NNN] to find specific log entries"
    - "Fresh agent can grep [DECISION] or [BLOCKER] to find all entries of a type"
    - "STATE.md no longer exists as separate file (merged into WORK.md)"
    - "WORK.md is perpetual with user-controlled housekeeping, not ephemeral"
    - "PROTOCOL.md explicitly teaches grep-first-then-read behavior"
    - "PROTOCOL.md documents read_to_next_pattern as primary method with manual calculation as fallback"
  artifacts:
    - path: "src/gsd_lite/template/WORK.md"
      provides: "3-part grep-friendly structure"
      contains: "## 1. Current Understanding"
    - path: "src/gsd_lite/template/workflows/housekeeping.md"
      provides: "Unified PR extraction and archiving workflow"
      contains: "housekeeping"
    - path: "src/gsd_lite/template/PROTOCOL.md"
      provides: "Updated router with new file structure and grep-first strategy"
      contains: "File Reading Strategy"
  key_links:
    - from: "PROTOCOL.md"
      to: "housekeeping.md"
      via: "workflow router table"
      pattern: "housekeeping.md"
    - from: "PROTOCOL.md"
      to: "grep patterns"
      via: "File Reading Strategy section"
      pattern: "grep.*\\^##"
    - from: "PROTOCOL.md"
      to: "fs-mcp enhancement"
      via: "File Reading Strategy section"
      pattern: "read_to_next_pattern"
    - from: "WORK.md"
      to: "[LOG-NNN]"
      via: "log entry format"
      pattern: "\\[LOG-[0-9]{3}\\]"
---

<objective>
Restructure WORK.md for grep-optimized retrieval and merge STATE.md tracking into WORK.md.

Purpose: Enable non-linear retrieval via single-line grep patterns. Fresh agents can grep headers/tags first, then surgical read of relevant sections. Eliminate STATE.md as separate file to reduce confusion for weak agents.

Output:
- WORK.md template with 3-part structure (Current Understanding, Key Events Index, Atomic Log)
- PROTOCOL.md updated to reflect merged structure and housekeeping workflow
- housekeeping.md workflow replacing promotion.md
- STATE.md marked as deprecated
</objective>

<execution_context>
@/Users/luutuankiet/.claude/get-shit-done/workflows/execute-plan.md
@/Users/luutuankiet/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01.7-refactor-artifacts-and-protocols-and-workflows-to-synergy-with-grep/01.7-CONTEXT.md
@.planning/phases/01.7-refactor-artifacts-and-protocols-and-workflows-to-synergy-with-grep/01.7-RESEARCH.md
@src/gsd_lite/template/WORK.md
@src/gsd_lite/template/STATE.md
@src/gsd_lite/template/PROTOCOL.md
@src/gsd_lite/template/workflows/promotion.md
@.planning/phases/01.7-refactor-artifacts-and-protocols-and-workflows-to-synergy-with-grep/references/FS-MCP-ENHANCEMENT-SPEC.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Redesign WORK.md with 3-part grep-friendly structure</name>
  <files>src/gsd_lite/template/WORK.md</files>
  <action>
Replace WORK.md template with new 3-part structure:

**Part 1: Current Understanding (Read First)**
- 30-second handoff section at top (from checkpoint workflow)
- Include: Active Task, Parked Tasks, Vision, Decisions, Blockers, Next Action
- Keep Current Mode tracking (formerly in STATE.md)

**Part 2: Key Events Index (Query Accelerator)**
- Table with columns: Log ID | Type | Task | Summary
- Example: `| LOG-015 | DECISION | MODEL-A | Use card-based layout over timeline |`
- One-line summaries only (10 words max)
- Updated for "major" entries (VISION, DECISION, BLOCKER, DISCOVERY with code)

**Part 3: Atomic Session Log (Chronological)**
- Format: `[LOG-NNN] - [YYYY-MM-DD HH:MM] - [TYPE] - Task: TASK-ID`
- Types: VISION, DECISION, DISCOVERY, PLAN, BLOCKER, EXEC
- Each entry includes: Summary line + Details with code snippets
- Code snippets ALWAYS included for EXEC and DISCOVERY entries

**CRITICAL changes:**
- Remove "ephemeral" language - WORK.md is now perpetual
- Remove "deleted after promotion" - replaced with housekeeping workflow
- Add multi-task support with Task: TAG in every log entry
- Keep examples but update to show [LOG-NNN] format with 6 types
- Include grep pattern hints in comments (^## for headers, [LOG-NNN] for ID lookup)
  </action>
  <verify>
Run grep patterns against new template:
- `grep "^## " WORK.md` finds 3 section headers
- Template contains [LOG-NNN] format examples
- No references to "ephemeral" or "deleted after promotion"
  </verify>
  <done>
WORK.md template has 3-part structure optimized for grep discovery, perpetual lifecycle, and multi-task support.
  </done>
</task>

<task type="auto">
  <name>Task 2: Create housekeeping.md workflow replacing promotion.md</name>
  <files>src/gsd_lite/template/workflows/housekeeping.md</files>
  <action>
Create new housekeeping.md workflow that unifies PR extraction AND archiving:

**Entry Conditions:**
- User requests "write PR" or "clean up WORK.md" or "archive old entries"
- Natural language triggers, not mode-based

**Housekeeping Operations:**

1. **PR Extraction** (user: "write PR for MODEL-A")
   - Filter WORK.md logs by Task: TAG
   - Extract DECISION, DISCOVERY (with code), EXEC entries
   - Generate PR description with evidence from logs
   - Keep entries in WORK.md (not deleted)

2. **Archive to HISTORY.md** (user: "archive MODEL-A" or "clean up WORK.md")
   - Move completed task entries to HISTORY.md
   - Keep HISTORY.md minimal (one-liner per task/phase)
   - Full logs optionally saved to dated files if user wants

3. **Index Maintenance**
   - After archiving, remove corresponding rows from Key Events Index
   - Update Current Understanding to reflect active tasks only

**Key Differences from promotion.md:**
- NOT triggered by mode/state - user initiates with natural language
- Does NOT delete WORK.md - only archives specific entries
- Can be run multiple times (not once per phase)
- WORK.md is perpetual - housekeeping maintains it, doesn't destroy it

Include Coaching Philosophy section (pair programming framing) and Sticky Note Protocol.
  </action>
  <verify>
- housekeeping.md exists with PR extraction and archive operations
- No references to "delete WORK.md" or "trim WORK.md"
- Natural language trigger examples included
  </verify>
  <done>
housekeeping.md workflow created, replacing promotion workflow with perpetual WORK.md management.
  </done>
</task>

<task type="auto">
  <name>Task 3: Update PROTOCOL.md for merged structure, new router, and grep-first behavior</name>
  <files>src/gsd_lite/template/PROTOCOL.md, src/gsd_lite/template/STATE.md</files>
  <action>
Update PROTOCOL.md:

1. **File Guide section:**
   - Remove STATE.md from file list (merged into WORK.md)
   - Update WORK.md description to "Session state + execution log"
   - Add note: "STATE.md deprecated - state tracking now in WORK.md Current Understanding"

2. **Workflow Router:**
   - Replace `promotion.md` with `housekeeping.md` in primary routing
   - Change promotion trigger to `housekeeping` mode
   - Add secondary routing for "write PR" and "clean up" triggers

3. **Fresh Agent Resume Protocol:**
   - Update to read WORK.md only (not STATE.md)
   - Reference "Current Understanding section in WORK.md" instead of STATE.md
   - Update sequence: Read PROTOCOL.md → Grep WORK.md headers → Surgical read Current Understanding → Load workflow
   - **ADD brief grep-first instruction:** "Use grep to discover WORK.md structure (`grep '^## '`), then read only the Current Understanding section (lines 1 to first log entry)."

4. **NEW: File Reading Strategy section (ADD AFTER Fresh Agent Resume Protocol):**
   Create a new section with this content:
   ```markdown
   ## File Reading Strategy (Grep-First)

   Always grep before reading large artifacts. Two-step pattern:

   1. **Discover:** `grep "^## " WORK.md` → returns section headers with line numbers
   2. **Surgical read:** Read from start_line with boundary pattern

   **Recommended: Section-Aware Reading (with `read_to_next_pattern`)**

   If your MCP server supports `read_to_next_pattern`, use it to avoid manual line calculation:

   ```python
   # Step 1: Find what you want
   grep_content(pattern=r"\[DECISION\]", search_path="WORK.md")
   # Returns: Line 120

   # Step 2: Read with automatic boundary detection
   read_files([{
       "path": "WORK.md",
       "start_line": 120,
       "read_to_next_pattern": r"^\[LOG-"
   }])
   # Server finds next [LOG- and stops there — no calculation needed
   ```

   **Common boundary patterns:**
   - Log entries: `^\[LOG-` — read one log entry
   - Level 2 headers: `^## ` — read one section
   - Any header: `^#+ ` — read until next header at any level

   **Grep patterns for discovery:**
   - Headers: `grep "^## "` — discover all sections
   - Log by ID: `grep "[LOG-015]"` — find specific entry
   - Log by type: `grep "[DECISION]"` — find all of type
   - Log by task: `grep "Task: MODEL-A"` — filter by task

   **Fallback: Manual Line Calculation (legacy servers)**

   If `read_to_next_pattern` is not available:
   1. Grep ALL boundaries: `grep "^\[LOG-" WORK.md`
   2. Calculate: Section ends at (next match line - 1) or EOF
   3. Read with explicit end_line

   Example: grep returns lines 100, 120, 145. To read entry at 120: `end_line = 144`

   **Fallback: No grep tool at all**

   Read first 50 lines of WORK.md — Current Understanding is always at top.
   ```

   **Reference:** See `references/FS-MCP-ENHANCEMENT-SPEC.md` for full server-side implementation details.

5. **Update STATE.md file:**
   - Replace content with deprecation notice using this wording:
     ```
     # STATE.md (DEPRECATED)

     This file is deprecated. State tracking now in WORK.md Current Understanding section.

     See WORK.md template for details.
     ```
   - Keep file for backward compatibility but mark obsolete

6. **Remove ephemeral references:**
   - Remove any mention of "WORK.md is ephemeral"
   - Update context lifecycle section to reflect perpetual WORK.md
  </action>
  <verify>
- PROTOCOL.md router includes housekeeping.md, not promotion.md
- Fresh Agent Resume Protocol references WORK.md only AND includes grep-first instruction
- PROTOCOL.md contains "File Reading Strategy" section with grep patterns
- PROTOCOL.md File Reading Strategy mentions `read_to_next_pattern` as recommended approach
- PROTOCOL.md File Reading Strategy includes fallback for legacy servers (manual calculation)
- STATE.md contains deprecation notice
- No references to ephemeral WORK.md
  </verify>
  <done>
PROTOCOL.md updated with merged file structure, new router, grep-first behavior prompting (synergized with fs-mcp enhancement), and perpetual WORK.md lifecycle.
  </done>
</task>

</tasks>

<verification>
After all tasks complete:

1. Grep pattern tests:
   - `grep "^## " src/gsd_lite/template/WORK.md` returns 3+ headers
   - `grep "LOG-" src/gsd_lite/template/WORK.md` returns example entries
   - `grep "ephemeral" src/gsd_lite/template/*.md` returns 0 results
   - `grep "promotion.md" src/gsd_lite/template/PROTOCOL.md` returns 0 results

2. File structure:
   - WORK.md has 3-part structure
   - housekeeping.md exists
   - STATE.md contains deprecation notice
   - PROTOCOL.md router updated
</verification>

<success_criteria>
- WORK.md template redesigned with grep-friendly 3-part structure
- STATE.md merged into WORK.md (deprecated as separate file)
- housekeeping.md workflow created replacing promotion.md
- PROTOCOL.md updated to reflect new structure
- No "ephemeral" language remains in artifacts
- All grep patterns from RESEARCH.md work against new templates
</success_criteria>

<output>
After completion, create `.planning/phases/01.7-refactor-artifacts-and-protocols-and-workflows-to-synergy-with-grep/01.7-01-SUMMARY.md`
</output>
