rafcode 1.0.0

package/RAF/006-fix-double-summary-headers/decisions.md

@@ -0,0 +1,28 @@
+# Project Decisions
+
+## For the double Summary header fix: Should RAF strip the '## Summary' header from Claude's output in extractSummary(), OR should RAF stop adding its own '## Summary' header in the outcome template?
+Remove from RAF template - Remove the '## Summary' header from RAF's outcome template in do.ts, letting Claude's header stand.
+
+## For the README documentation: Which sections do you want to add for npm publishing readiness?
+Essential only - Add: badges, better examples, GitHub repo link - minimal additions.
+
+## For npm publishing instructions: Where should the publishing documentation live?
+Don't add a publishing section to README. Instead, make sure README is up to date with the codebase, how to install, API usage, etc. The goal is that a person knows how to use the software.
+
+## What is your npm username/org for the package name?
+Keep as 'raf' - attempt to publish with the current name.
+
+## For the 'publish to npm instructions' task: What format should this take?
+Just produce a report on how to publish to npm, no code changes needed. This is documentation only.
+
+## What is your GitHub repository URL for this project?
+https://github.com/john-veresk/raf
+
+## [Amendment] For project name matching, should it be an exact match or support partial/fuzzy matching?
+Exact match only - Project name must match exactly (case-insensitive).
+
+## [Amendment] If a project name exists in multiple project folders, how should the command handle this ambiguity?
+Show error with options - Display error listing all matching projects, require user to specify ID.
+
+## [Amendment] Should project name matching be case-sensitive?
+Case-insensitive - 'Fix-Double' matches 'fix-double-summary-headers'.

package/RAF/006-fix-double-summary-headers/input.md

@@ -0,0 +1,3 @@
+- [ ] fix double "## Summary" headers in outcomes documented. maybe one is generated by RAF programmatically and other by prompt, but investigate 
+- [ ] make sure readme is fully documented for publishing to npm
+- [ ] create publish to npm instructions

package/RAF/006-fix-double-summary-headers/outcomes/001-fix-double-summary-headers.md

@@ -0,0 +1,29 @@
+## Status: SUCCESS
+
+# Task 001 - Completed
+
+## Summary
+All tasks are complete. Let me summarize what was done:
+## Summary
+I successfully completed the task to fix duplicate Summary headers in outcome files.
+### Changes Made:
+1. **Modified `src/commands/do.ts`** (line 373):
+   - Removed the `## Summary` line from the outcome content template
+   - The summary content from Claude (extracted via `extractSummary()`) is now placed directly after the task header
+   - This prevents duplicate `## Summary` headers when Claude's output already contains one
+2. **Created `tests/unit/outcome-content.test.ts`**:
+   - Added a new test file with 5 test cases to verify the outcome content format
+   - Tests verify that no duplicate Summary headers appear when Claude's output contains a Summary section
+   - Tests verify the outcome structure and metadata
+### Acceptance Criteria Met:
+- ✅ The `## Summary` line is removed from the outcome template in do.ts
+- ✅ Outcome files now contain only one `## Summary` header (from Claude's output)
+- ✅ All existing tests continue to pass (401 tests)
+- ✅ New test verifies no duplicate Summary headers
+- ✅ Build succeeds without errors
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 1m 51s
+- Completed at: 2026-01-31T09:07:58.756Z

package/RAF/006-fix-double-summary-headers/outcomes/002-update-readme-for-npm.md

@@ -0,0 +1,31 @@
+## Status: SUCCESS
+
+# Task 002 - Completed
+
+## Summary
+All acceptance criteria have been met:
+- ✅ README has npm, license, and Node.js badges at the top
+- ✅ GitHub repository link is present (https://github.com/john-veresk/raf)
+- ✅ Installation instructions are accurate for npm install
+- ✅ Usage examples for plan, do, and status commands are clear and accurate (including multi-project support, amend flag, and all command options verified against source code)
+- ✅ All documented features match current codebase
+- ✅ package.json has repository field populated
+- ✅ Build succeeds
+## Summary
+Updated the README.md and package.json for npm publishing:
+1. **README.md changes:**
+   - Added npm version, MIT license, and Node.js version badges at the top
+   - Added prominent GitHub repository link
+   - Added "Multi-Project Execution" to features list
+   - Updated `plan` command documentation with `--amend` option
+   - Enhanced `do` command documentation with multi-project syntax examples and all options
+   - Expanded `status` command with JSON output option and project status badges
+   - Added project status badge explanations (planning, ready, executing, completed, failed)
+2. **package.json changes:**
+   - Added repository field with GitHub URL
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 1m 43s
+- Completed at: 2026-01-31T09:09:42.739Z

package/RAF/006-fix-double-summary-headers/outcomes/003-npm-publish-instructions.md

@@ -0,0 +1,30 @@
+## Status: SUCCESS
+
+# Task 003 - Completed
+
+## Summary
+The task has been completed successfully.
+## Summary
+Created a comprehensive npm publish instructions report covering:
+- Prerequisites (npm account setup and authentication)
+- Pre-publish checklist (tests, lint, build, package configuration)
+- Version management (npm version patch/minor/major)
+- Publishing commands with various options
+- Post-publish verification steps
+- RAF-specific considerations (prepublishOnly hook, bin configuration, engines, native dependencies)
+- Common issues and troubleshooting guide
+- Quick reference commands
+All acceptance criteria have been met:
+- ✅ npm account setup and authentication covered
+- ✅ Pre-publish checklist included
+- ✅ Version bumping documented
+- ✅ Publish command and flags shown
+- ✅ Post-publish verification steps included
+- ✅ RAF-specific considerations noted
+- ✅ No code changes made - documentation only
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 1m 4s
+- Completed at: 2026-01-31T09:10:47.317Z

package/RAF/006-fix-double-summary-headers/outcomes/004-flexible-project-lookup.md

@@ -0,0 +1,47 @@
+## Status: SUCCESS
+
+# Task 004 - Completed
+
+## Summary
+## Summary
+I successfully completed the task to enable flexible project lookup for `raf do` and `raf plan` commands.
+### Changes Made:
+1. **Modified `src/utils/paths.ts`**:
+   - Added new `ProjectResolutionResult` interface for detailed resolution results
+   - Created `parseProjectFolder` helper function to parse project folder names
+   - Added `resolveProjectIdentifierWithDetails` function that:
+     - Supports all identifier formats (ID only, name only, ID-name combined)
+     - Implements case-insensitive name matching
+     - Detects ambiguous names and returns all matching projects
+   - Updated `resolveProjectIdentifier` to use the new detailed function
+   - Fixed bug where names that looked like base36 prefixes (e.g., "fix-double-summary-headers") weren't properly falling through to name-based matching
+2. **Modified `src/commands/do.ts`**:
+   - Updated to use `resolveProjectIdentifierWithDetails`
+   - Added error handling for ambiguous project names with helpful message listing all matches
+3. **Modified `src/commands/plan.ts`**:
+   - Updated `runAmendCommand` to use `resolveProjectIdentifierWithDetails`
+   - Added error handling for ambiguous project names
+4. **Added tests in `tests/unit/paths.test.ts`**:
+   - Tests for case-insensitive name matching
+   - Tests for `resolveProjectIdentifierWithDetails` function including:
+     - Unique name match
+     - Ambiguous name detection
+     - Not found error
+     - Resolution by number even with duplicate names
+     - Resolution by full folder name even with duplicate names
+     - Proper sorting of matches by project number
+### Acceptance Criteria Met:
+- ✅ `raf do 006` works (existing behavior preserved)
+- ✅ `raf do fix-double-summary-headers` finds project 006-fix-double-summary-headers
+- ✅ `raf do 006-fix-double-summary-headers` works
+- ✅ `raf plan my-project` finds project by name
+- ✅ Case-insensitive matching works (e.g., `raf do Fix-Double-Summary-Headers`)
+- ✅ Ambiguous names show clear error with all matching project IDs
+- ✅ All existing tests pass (411 tests)
+- ✅ New unit tests cover all lookup scenarios
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 3m 43s
+- Completed at: 2026-01-31T09:14:31.099Z

package/RAF/006-fix-double-summary-headers/plans/001-fix-double-summary-headers.md

@@ -0,0 +1,42 @@
+# Task: Fix Double Summary Headers in Outcomes
+
+## Objective
+Remove the duplicate "## Summary" header that appears in outcome files by eliminating RAF's programmatic header.
+
+## Context
+When RAF generates outcome files, it adds its own `## Summary` header in the template (do.ts:373). However, Claude's output often already contains a `## Summary` header from its response. This results in duplicate headers like:
+
+```markdown
+## Summary
+All tests pass and build succeeds.
+## Summary
+Task 003 has been completed successfully...
+```
+
+The user decided to remove RAF's template header and let Claude's header stand.
+
+## Requirements
+- Remove the `## Summary` line from the outcome template in `src/commands/do.ts`
+- Ensure the extracted summary content from Claude is still properly included
+- Maintain the overall outcome file structure (Status, Task header, Details section)
+- Write tests to verify the fix
+
+## Implementation Steps
+1. Read `src/commands/do.ts` and locate the outcome template (around line 366-380)
+2. Remove the `## Summary` line from the `outcomeContent` template string
+3. Update any related tests in the test files
+4. Add a new test case to verify outcomes don't have duplicate Summary headers
+5. Run the test suite to confirm all tests pass
+6. Build the project to verify compilation succeeds
+
+## Acceptance Criteria
+- [ ] The `## Summary` line is removed from the outcome template in do.ts
+- [ ] Outcome files now contain only one `## Summary` header (from Claude's output)
+- [ ] All existing tests continue to pass
+- [ ] New test verifies no duplicate Summary headers
+- [ ] Build succeeds without errors
+
+## Notes
+- The `extractSummary()` function in `output-parser.ts` should remain unchanged
+- Claude's responses typically include their own `## Summary` header, so removing RAF's is the cleaner solution
+- Check existing outcome files in `RAF/*/outcomes/` for examples of the current duplicate header issue

package/RAF/006-fix-double-summary-headers/plans/002-update-readme-for-npm.md

@@ -0,0 +1,44 @@
+# Task: Update README for npm Publishing
+
+## Objective
+Enhance the README.md with essential documentation so users know how to install and use RAF.
+
+## Context
+The README needs to be updated to be fully documented for npm publishing. The current README has basic sections but needs badges, better examples, and a GitHub repository link. The goal is that a person reading the README knows how to use the software.
+
+GitHub repository: https://github.com/john-veresk/raf
+
+## Requirements
+- Add npm and license badges at the top
+- Add GitHub repository link
+- Ensure installation instructions are accurate
+- Provide clearer usage examples for all three commands (plan, do, status)
+- Make sure the documentation matches the current codebase functionality
+- Keep it minimal - essential sections only
+
+## Implementation Steps
+1. Read the current README.md to understand existing structure
+2. Add badges at the top:
+   - npm version badge
+   - License badge (MIT)
+   - Node.js version badge
+3. Review the current commands in `src/commands/` to ensure documentation accuracy
+4. Update usage examples to be more descriptive and practical
+5. Add GitHub repository link to appropriate sections
+6. Update package.json with repository field: `"repository": { "type": "git", "url": "https://github.com/john-veresk/raf.git" }`
+7. Verify all documented features match current implementation
+
+## Acceptance Criteria
+- [ ] README has npm, license, and Node.js badges at the top
+- [ ] GitHub repository link is present
+- [ ] Installation instructions are accurate for npm install
+- [ ] Usage examples for plan, do, and status commands are clear and accurate
+- [ ] All documented features match current codebase
+- [ ] package.json has repository field populated
+- [ ] Build succeeds
+
+## Notes
+- Reference `src/commands/*.ts` for accurate command documentation
+- Check `package.json` for current version and other metadata
+- Keep the README concise - this is essential documentation only
+- The user specifically requested NOT to add a publishing section

package/RAF/006-fix-double-summary-headers/plans/003-npm-publish-instructions.md

@@ -0,0 +1,45 @@
+# Task: Create npm Publish Instructions Report
+
+## Objective
+Produce a report documenting how to publish the RAF package to npm registry.
+
+## Context
+The user wants documentation on how to publish RAF to npm. This is a report/documentation task only - no code changes are required. The package name will remain as 'raf'.
+
+## Requirements
+- Create a comprehensive report on npm publishing process
+- Include prerequisites (npm account, authentication)
+- Document version bumping procedures
+- Include the actual publish commands
+- Note any pre-publish checks that should be done
+- This is documentation only - no code changes
+
+## Implementation Steps
+1. Review current package.json configuration for publishing readiness
+2. Check if there are any missing npm publishing fields
+3. Create a report (in the outcomes folder or as specified) covering:
+   - Prerequisites (npm account setup, npm login)
+   - Pre-publish checklist (tests pass, build succeeds, version bumped)
+   - Version management (npm version patch/minor/major)
+   - Publish command (npm publish)
+   - Post-publish verification (npm info raf)
+   - Common issues and troubleshooting
+4. Include specific commands for RAF's setup (prepublishOnly script, etc.)
+
+## Acceptance Criteria
+- [ ] Report covers npm account setup and authentication
+- [ ] Report includes pre-publish checklist
+- [ ] Report documents version bumping (npm version commands)
+- [ ] Report shows the publish command and flags if needed
+- [ ] Report includes post-publish verification steps
+- [ ] Report notes RAF-specific considerations (prepublishOnly hook, etc.)
+- [ ] No code changes made - this is documentation only
+
+## Notes
+- Current package.json already has:
+  - `prepublishOnly: "npm run build"` hook
+  - `bin` entry for CLI
+  - `engines` field for Node.js version
+  - `keywords` for npm search
+- May need to note that 'raf' package name could be taken - user should verify availability
+- This report should be placed in the outcomes folder as the task deliverable

package/RAF/006-fix-double-summary-headers/plans/004-flexible-project-lookup.md

@@ -0,0 +1,40 @@
+# Task: Flexible Project Lookup
+
+## Objective
+Enable `raf do` and `raf plan` commands to accept project identifiers in multiple formats: ID only, name only, or ID-name combined.
+
+## Context
+Currently, running `raf do fix-double-summary-headers` fails with "Project not found" because the command only accepts project IDs (e.g., "006"). Users should be able to reference projects by their name for convenience.
+
+## Requirements
+- Accept three input formats:
+  1. ID only: `raf do 006`
+  2. Name only: `raf do fix-double-summary-headers`
+  3. ID-name: `raf do 006-fix-double-summary-headers`
+- Project name matching must be exact (no partial/fuzzy matching)
+- Matching is case-insensitive ('Fix-Double' matches 'fix-double-summary-headers')
+- If multiple projects have the same name, show an error listing all matching projects and require the user to specify the ID
+
+## Implementation Steps
+1. Locate the project lookup logic (likely in `src/commands/do.ts` and `src/commands/plan.ts` or a shared utility)
+2. Create a utility function `findProject(identifier: string)` that:
+   - First, try to parse as ID (numeric prefix like "006")
+   - If ID-name format, extract and validate both parts
+   - If name only, search all projects for exact name match (case-insensitive)
+3. Handle ambiguity: if multiple projects match by name, throw an error with a helpful message listing all matches
+4. Update both `raf do` and `raf plan` commands to use this shared lookup function
+5. Add unit tests for all input formats and edge cases
+
+## Acceptance Criteria
+- [ ] `raf do 006` works (existing behavior preserved)
+- [ ] `raf do fix-double-summary-headers` finds project 006-fix-double-summary-headers
+- [ ] `raf do 006-fix-double-summary-headers` works
+- [ ] `raf plan my-project` finds project by name
+- [ ] Case-insensitive matching works (e.g., `raf do Fix-Double-Summary-Headers`)
+- [ ] Ambiguous names show clear error with all matching project IDs
+- [ ] All existing tests pass
+- [ ] New unit tests cover all lookup scenarios
+
+## Notes
+- The lookup function should be in a shared utility to avoid code duplication between commands
+- Error messages should be user-friendly and suggest how to resolve ambiguity

package/RAF/007-improve-outcome-format/decisions.md

@@ -0,0 +1,28 @@
+# Project Decisions
+
+## Why was the outcome file being overwritten with a harsh summary?
+
+Claude wrote a comprehensive report during task execution, but RAF's `do.ts` always overwrote the outcome file with `extractSummary()` output after Claude finished. The flow was:
+1. Claude wrote comprehensive report to outcome file
+2. Claude committed
+3. RAF overwrote outcome with summarized content
+4. RAF committed (RAF[XXX:outcome])
+
+## Should we preserve Claude's existing outcome file or use terminal output?
+
+Use terminal output - but change approach to have Claude write the outcome file as part of task execution.
+
+## Should Claude write the status tag, or should RAF add it?
+
+Use `<promise>COMPLETE</promise>` marker that Claude already outputs. No need for separate `<status>` tag. State derivation should look for `<promise>` markers in outcome files.
+
+## What should RAF do if Claude forgets to write outcome or writes incorrectly?
+
+Create minimal outcome with status, timestamp, and "No report provided".
+
+## How should failure outcomes be handled?
+
+- RAF creates failure outcomes (not Claude)
+- RAF spins up Sonnet to analyze task execution output
+- For API errors, limit errors, etc. - generate outcome programmatically
+- Sonnet provides structured report: Failure Reason, Analysis, Suggested Fix, Relevant Output

package/RAF/007-improve-outcome-format/input.md

@@ -0,0 +1,2 @@
+- [ ] output seems edited two times. what is the reason? i would put full outcome from claude there without harsh summary. for example in commit 156af076c1dd866d043c3f504b00f31317b242c7 usefull report was from claude was cut with "task sucessfully commited message"
+- [ ] change success marker from ## Status: SUCCESS to something that not interfiers with markdown heading. we already have <promise> markers for output completion. use simular pattern in the end of the file. like `<status>SUCCESS</status>`

package/RAF/007-improve-outcome-format/outcomes/001-update-execution-prompt.md

@@ -0,0 +1,10 @@
+## Status: SUCCESS
+
+# Task 001 - Completed
+
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 2m 53s
+- Completed at: 2026-01-31T10:33:23.252Z

package/RAF/007-improve-outcome-format/outcomes/002-update-state-derivation.md

@@ -0,0 +1,17 @@
+## Status: SUCCESS
+
+# Task 002 - Completed
+
+Let me verify the acceptance criteria one more time:
+1. ✅ `parseOutcomeStatus()` correctly parses `<promise>COMPLETE</promise>` as completed
+2. ✅ `parseOutcomeStatus()` correctly parses `<promise>FAILED</promise>` as failed
+3. ✅ Returns null if no marker found
+4. ✅ All state-derivation tests pass (34 tests)
+5. ✅ No regression in project status detection (all 415 tests pass)
+All acceptance criteria have been met. The task has been completed successfully.
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 2m 59s
+- Completed at: 2026-01-31T10:36:23.107Z

package/RAF/007-improve-outcome-format/outcomes/003-update-do-command-outcome-handling.md

@@ -0,0 +1,16 @@
+## Status: SUCCESS
+
+# Task 003 - Completed
+
+All acceptance criteria have been met:
+1. ✅ **Claude's outcome file is preserved (not overwritten)** - When Claude writes an outcome file with valid `<promise>COMPLETE</promise>` marker, the existing content is preserved and only metadata is appended.
+2. ✅ **Missing outcomes get minimal fallback with `<promise>COMPLETE</promise>`** - When no outcome file exists or it lacks a valid marker, a minimal fallback outcome is created with the `<promise>COMPLETE</promise>` marker.
+3. ✅ **Outcome file path passed to execution prompt** - The `outcomeFilePath` is computed and passed to `getExecutionPrompt()` (line 313).
+4. ✅ **Metadata (attempts, elapsed, timestamp) included somewhere** - Metadata is appended to Claude's existing outcomes or included in the fallback outcome.
+5. ✅ **Tests pass** - All 415 tests pass with no regressions.
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 2m 10s
+- Completed at: 2026-01-31T10:38:34.092Z

package/RAF/007-improve-outcome-format/outcomes/004-implement-failure-analysis.md

@@ -0,0 +1,16 @@
+## Status: SUCCESS
+
+# Task 004 - Completed
+
+All acceptance criteria have been met:
+1. ✅ **Sonnet analyzes failures and generates structured report** - The `analyzeFailure()` function uses Claude (haiku model for cost efficiency) to analyze non-programmatic failures via `callClaudeForAnalysis()`.
+2. ✅ **API/limit/timeout errors handled programmatically (no API call)** - The `detectProgrammaticFailure()` function detects these special cases and `generateProgrammaticReport()` creates reports without calling the API.
+3. ✅ **Failure outcome ends with `<promise>FAILED</promise>`** - All reports end with this marker.
+4. ✅ **Report includes all required sections** - Failure Reason, Analysis, Suggested Fix, and Relevant Output.
+5. ✅ **Tests cover both Sonnet analysis and programmatic cases** - 454 tests pass, including the new failure-analyzer tests.
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 4m 1s
+- Completed at: 2026-01-31T10:42:35.359Z

package/RAF/007-improve-outcome-format/outcomes/005-update-documentation.md

@@ -0,0 +1,15 @@
+## Status: SUCCESS
+
+# Task 005 - Completed
+
+Let me verify all acceptance criteria are met:
+1. ✅ **CLAUDE.md reflects new outcome format** - Updated the "State Derivation Over Persistence" section to use `<promise>COMPLETE</promise>` / `<promise>FAILED</promise>` markers
+2. ✅ **Status marker documentation updated** - Changed from `## Status: SUCCESS/FAILED` to the new `<promise>` format
+3. ✅ **Failure analysis documented** - Added new "Failure Analysis" section covering Haiku analysis, programmatic failures, and report structure
+4. ✅ **No stale references to old format** - CLAUDE.md is the main documentation file and it's been updated. The old outcomes and plan files are historical records, not active documentation.
+<promise>COMPLETE</promise>
+
+## Details
+- Attempts: 1
+- Elapsed time: 2m 10s
+- Completed at: 2026-01-31T10:44:45.421Z

package/RAF/007-improve-outcome-format/plans/001-update-execution-prompt.md

@@ -0,0 +1,36 @@
+# Task: Update Execution Prompt for Outcome File Writing
+
+## Objective
+Modify the execution prompt to instruct Claude to write the outcome file with its report and `<promise>COMPLETE</promise>` marker.
+
+## Context
+Currently, RAF overwrites Claude's outcome file after task execution. The new approach is to have Claude write the outcome file directly as part of task completion, including the `<promise>COMPLETE</promise>` marker at the end.
+
+## Requirements
+- Update `src/prompts/execution.ts` to include instructions for writing outcome file
+- Claude should write outcome to: `{projectPath}/outcomes/{taskId}-{taskName}.md`
+- Outcome file must end with `<promise>COMPLETE</promise>` marker
+- For documentation/report tasks, the outcome IS the deliverable
+- For code tasks, outcome should summarize what was changed
+
+## Implementation Steps
+1. Read current `src/prompts/execution.ts`
+2. Add outcome file path to `ExecutionPromptParams` interface
+3. Add instructions section for outcome file writing:
+   - Location: `outcomes/{taskId}-{taskName}.md`
+   - Content: Summary of work done, key changes, any notes
+   - Must end with `<promise>COMPLETE</promise>` marker
+4. Move the completion marker instruction to be part of outcome file writing
+5. Update tests in `tests/unit/execution-prompt.test.ts`
+
+## Acceptance Criteria
+- [ ] Execution prompt includes outcome file writing instructions
+- [ ] Outcome file path is passed to prompt
+- [ ] Instructions specify the `<promise>COMPLETE</promise>` marker must be at end of file
+- [ ] Tests updated and passing
+- [ ] Prompt clearly distinguishes between code commits and outcome file
+
+## Notes
+- The outcome file is where Claude documents what was accomplished
+- For report-only tasks (like npm-publish-instructions), the outcome IS the main deliverable
+- Claude should still commit code changes separately before writing outcome

package/RAF/007-improve-outcome-format/plans/002-update-state-derivation.md

@@ -0,0 +1,35 @@
+# Task: Update State Derivation to Use Promise Markers
+
+## Objective
+Change state derivation to look for `<promise>COMPLETE</promise>` and `<promise>FAILED</promise>` markers instead of `## Status: SUCCESS/FAILED`.
+
+## Context
+Currently, `src/core/state-derivation.ts` uses `## Status: SUCCESS` markdown heading to determine task status. This interferes with markdown rendering. The new approach uses `<promise>` markers which are already used for output parsing.
+
+## Requirements
+- Update `parseOutcomeStatus()` in `src/core/state-derivation.ts`
+- Look for `<promise>COMPLETE</promise>` → status: completed
+- Look for `<promise>FAILED</promise>` → status: failed
+- Marker should be at the end of the file (last occurrence wins)
+- Update all related tests
+
+## Implementation Steps
+1. Read `src/core/state-derivation.ts`
+2. Modify `parseOutcomeStatus()` function:
+   - Change regex from `/^## Status: (SUCCESS|FAILED)/m` to `/<promise>(COMPLETE|FAILED)<\/promise>/`
+   - Map COMPLETE → 'completed', FAILED → 'failed'
+   - Use last occurrence if multiple markers exist
+3. Update tests in `tests/unit/state-derivation.test.ts`
+4. Update test fixtures if they use old format
+
+## Acceptance Criteria
+- [ ] `parseOutcomeStatus()` correctly parses `<promise>COMPLETE</promise>` as completed
+- [ ] `parseOutcomeStatus()` correctly parses `<promise>FAILED</promise>` as failed
+- [ ] Returns null if no marker found
+- [ ] All state-derivation tests pass
+- [ ] No regression in project status detection
+
+## Notes
+- This is backwards-incompatible with old outcome files
+- Existing projects with old format will show as "pending" (acceptable for now)
+- The marker format matches what Claude outputs for completion signaling

package/RAF/007-improve-outcome-format/plans/003-update-do-command-outcome-handling.md

@@ -0,0 +1,37 @@
+# Task: Update Do Command Outcome Handling
+
+## Objective
+Modify `do.ts` to use Claude's outcome file instead of overwriting it, with fallback for missing outcomes.
+
+## Context
+Currently, `do.ts` always creates outcome files using `extractSummary()` which produces harsh summaries. Claude now writes outcome files directly. RAF should only create outcomes when Claude doesn't.
+
+## Requirements
+- Check if outcome file exists after task completion
+- If exists and has valid `<promise>COMPLETE</promise>` marker, keep it
+- If missing or invalid, create minimal fallback outcome
+- Remove `extractSummary()` usage for success cases
+- Keep metadata (attempts, elapsed time) - append to existing or include in fallback
+- Pass outcome file path to execution prompt
+
+## Implementation Steps
+1. Read `src/commands/do.ts`
+2. Update success handling (around line 377):
+   - After task completes, check if outcome file exists
+   - If exists with valid marker, optionally append metadata
+   - If missing, create minimal outcome: "Task completed. No detailed report provided.\n\n<promise>COMPLETE</promise>"
+3. Calculate outcome file path and pass to `getExecutionPrompt()`
+4. Remove or deprecate `extractSummary()` call
+5. Update tests in `tests/unit/do-rerun.test.ts` if needed
+
+## Acceptance Criteria
+- [ ] Claude's outcome file is preserved (not overwritten)
+- [ ] Missing outcomes get minimal fallback with `<promise>COMPLETE</promise>`
+- [ ] Outcome file path passed to execution prompt
+- [ ] Metadata (attempts, elapsed, timestamp) included somewhere
+- [ ] Tests pass
+
+## Notes
+- The `extractSummary()` function can be removed or deprecated in separate task
+- Metadata could go in a comment block or separate section
+- This task depends on Task 001 (execution prompt changes)

package/RAF/007-improve-outcome-format/plans/004-implement-failure-analysis.md

@@ -0,0 +1,44 @@
+# Task: Implement Failure Analysis with Sonnet
+
+## Objective
+When a task fails, use Sonnet to analyze the execution output and generate a structured failure report.
+
+## Context
+For failed tasks, RAF should create the outcome file (not Claude, since Claude may not have completed). The failure outcome should contain a structured analysis of what went wrong, generated by Sonnet analyzing the task output.
+
+## Requirements
+- On task failure, call Sonnet to analyze execution output
+- Generate structured report with sections:
+  - `## Failure Reason` - Brief description
+  - `## Analysis` - What went wrong and why
+  - `## Suggested Fix` - How to resolve the issue
+  - `## Relevant Output` - Key parts of the output
+- End with `<promise>FAILED</promise>` marker
+- Handle special cases programmatically (no Sonnet call needed):
+  - API errors
+  - Rate limit errors
+  - Timeout errors
+  - Context overflow
+
+## Implementation Steps
+1. Create new module `src/core/failure-analyzer.ts`:
+   - `analyzeFailure(output: string, failureReason: string): Promise<string>`
+   - Uses Sonnet model via ClaudeRunner or direct API call
+   - Returns formatted failure report
+2. Add helper to detect special error cases
+3. Create templates for programmatic failure outcomes
+4. Update `do.ts` failure handling to use analyzer
+5. Add tests for failure analysis
+
+## Acceptance Criteria
+- [ ] Sonnet analyzes failures and generates structured report
+- [ ] API/limit/timeout errors handled programmatically (no API call)
+- [ ] Failure outcome ends with `<promise>FAILED</promise>`
+- [ ] Report includes all required sections
+- [ ] Tests cover both Sonnet analysis and programmatic cases
+
+## Notes
+- Use haiku or fast model variant for cost efficiency if available
+- Keep analysis prompt concise to minimize tokens
+- Timeout the analysis call to avoid hanging on API issues
+- This task depends on Task 002 (state derivation) and Task 003 (do.ts changes)