Execution System MCP Server

# Complete Project - Requirements ## 1. Business Context When a project is finished, it must be moved from the active folder to the completed folder. However, before completing a project, we need to ensure all work items at the 0k horizon (next actions, waiting for, incubating, deferred) have been processed. This prevents accidentally completing a project that still has open work associated with it. The complete_project MCP tool will validate that no open 0k items are tagged with the project, then move the project file to the completed folder and update its YAML frontmatter with a completion date. ## 2. Requirements (EARS Notation) ### Validation Requirements **REQ-1:** WHERE the user requests to complete a project, the system SHALL verify the project exists in the active folder before proceeding. **REQ-2:** WHERE a project exists in a subdirectory of the active folder, the system SHALL determine the correct area subdirectory from the project's YAML frontmatter. **REQ-3:** WHERE the project file is found, the system SHALL parse the project filename to extract the kebab-case project identifier. **REQ-4:** WHERE the project identifier is known, the system SHALL search for open items tagged with +{project-kebab} in the @waiting.md file. **REQ-5:** WHERE the project identifier is known, the system SHALL search for open items tagged with +{project-kebab} in the @incubating.md file. **REQ-6:** WHERE the project identifier is known, the system SHALL search for open items tagged with +{project-kebab} in the @deferred.md file. **REQ-7:** WHERE the project identifier is known, the system SHALL search for open items tagged with +{project-kebab} in all context files within the contexts directory. **REQ-8:** WHERE any open 0k items are found with the project tag, the system SHALL return an error listing all blocking items and SHALL NOT complete the project. **REQ-9:** WHERE completed.md contains items tagged with +{project-kebab}, the system SHALL allow project completion (completed items do not block). ### Completion Requirements **REQ-10:** WHERE all validation passes, the system SHALL read the existing YAML frontmatter from the project file. **REQ-11:** WHERE the YAML frontmatter is read, the system SHALL preserve all existing fields including area, title, type, created, started, last_reviewed, and due. **REQ-12:** WHERE the YAML frontmatter is parsed, the system SHALL add a new field "completed" with today's date in ISO format (YYYY-MM-DD). **REQ-13:** WHERE the frontmatter is updated, the system SHALL preserve the field order: area, title, type, created, started, last_reviewed, due (if present), completed. **REQ-14:** WHERE the updated frontmatter is prepared, the system SHALL write the complete project file (frontmatter + body) to the completed folder in the same area subdirectory. **REQ-15:** WHERE the project is successfully written to the completed folder, the system SHALL delete the original file from the active folder. **REQ-16:** WHERE the project file is moved, the system SHALL create the completed/{area} subdirectory if it does not exist. ### Error Handling Requirements **REQ-17:** WHERE the project title does not match any file in the active folder, the system SHALL return an error message indicating the project was not found. **REQ-18:** WHERE the project exists in incubator, descoped, or completed folders instead of active, the system SHALL return an error indicating the project is not active. **REQ-19:** WHERE file system operations fail (read/write/delete), the system SHALL return an error without leaving partial state (no orphaned files). **REQ-20:** WHERE YAML frontmatter is malformed or missing required fields, the system SHALL return an error describing the issue. ## 3. Acceptance Criteria **AC-1:** Given a project with no open 0k items, when complete_project is called, then the project file is moved to completed/{area}/ with a completed date added to frontmatter. **AC-2:** Given a project with open next actions tagged +{project-kebab}, when complete_project is called, then an error is returned listing the blocking next actions. **AC-3:** Given a project with open waiting items tagged +{project-kebab}, when complete_project is called, then an error is returned listing the blocking waiting items. **AC-4:** Given a project with open incubating items tagged +{project-kebab}, when complete_project is called, then an error is returned listing the blocking items. **AC-5:** Given a project with open deferred items tagged +{project-kebab}, when complete_project is called, then an error is returned listing the blocking items. **AC-6:** Given a project with completed items in completed.md tagged +{project-kebab}, when complete_project is called, then the project completes successfully (completed items don't block). **AC-7:** Given a project that doesn't exist in active/, when complete_project is called, then an error is returned indicating the project was not found. **AC-8:** Given a project in the completed folder, when complete_project is called, then an error is returned indicating the project is already completed. **AC-9:** Given a successfully completed project, when inspecting the YAML frontmatter, then all original fields are preserved and a completed date is added. **AC-10:** Given the completed/{area} subdirectory doesn't exist, when completing a project, then the directory is created automatically.