Append a timestamped note to a story file. Use to record progress, decisions made, or blockers encountered. Notes are appended under a '## Notes' section with an ISO 8601 timestamp. Returns {story_id, appended_at, path}.

Mark a single acceptance criterion as checked (- [ ] → - [x]) in a story file. Identify the target by criterion_index (0-based) or criterion_text (case-insensitive exact match). Exactly one must be provided. Returns {story_id, criterion, checked, path}. Errors if the story is not found, the criterion is not found, or it is already checked.

Mark a story done and append a mandatory completion summary note in one atomic call. Validates acceptance criteria before completing: if the AC section has not been set (contains only the placeholder), completion is blocked — call set_acceptance_criteria first. IMPORTANT: if a criterion is actually done, mark it [x] in the story file via set_acceptance_criteria BEFORE calling this tool — do not leave it unchecked. If criteria remain unchecked (genuinely not done), incomplete_items is required with one explanation per unchecked item explaining WHY it was not completed (e.g. deferred, out of scope). incomplete_items is for unfinished work only — never use it to confirm completed work. On success, removes the story from backlog.md and returns {story_id, completed_at, backlog_removed}.

Create a new epic. Assigns the next EPIC-NNN ID, creates the epic directory and epic.md file, and registers it in requirements-index.md with status draft. Returns {epic_id, path}.

Create a new story under an existing epic. Assigns the next STORY-NNN ID, writes the story file, and registers it in requirements-index.md and backlog.md with status draft. The story is appended to the end of the backlog. Returns {story_id, path}.

Get a high-level summary of all epics and their story counts broken down by status. Useful for situational awareness at the start of a session, without reading every file. Returns an array of {epic_id, title, status, counts: {status: n}, stories: [{story_id, status}]}.

Get the full markdown content and metadata for a single story. Returns {story_id, title, status, epic_id, path, content} where content is the raw markdown of the story file.

Reconcile the ## Stories section in an epic.md file with the story files on disk and the requirements index. Adds missing entries, removes entries for story files that no longer exist, and refreshes titles and done/undone markers. Returns {epic_id, added, removed, updated, unchanged}.

List stories from the project index, optionally filtered by epic, status, or type. Returns an array of {story_id, title, status, epic_id, story_type} objects. With no filters, returns all stories across all epics.

Replace the acceptance criteria section of a story file. Each string in the criteria array becomes a - [ ] ... checklist line. Idempotent: calling again replaces the previous AC entirely. Acceptance criteria must be set before a story can be completed with complete_story. Returns {story_id, criteria_count, path}.

Update the lifecycle status of an epic. Use this tool to manage the epic's own status — not the status of individual stories within it (use set_story_status for that). Typical progression: draft → in-progress (when the first story starts) → done (when all stories are complete) or deferred (if the epic is postponed). Status meanings: 'draft' = epic created but no work started; 'in-progress' = actively being worked on; 'done' = all stories complete and the epic is closed; 'blocked' = progress prevented by an external dependency; 'deferred' = postponed indefinitely. Returns {epic_id, old_status, new_status}.

Update the status of a story to draft, in-progress, blocked, or deferred. To mark a story done, use complete_story instead — it enforces acceptance criteria, appends a summary note, and removes the story from the backlog. Returns {story_id, old_status, new_status, backlog_updated}.