All servers / Memory / Handoff MCP server
Handoff MCP server
MCP server that gives AI coding agents persistent memory across sessions
Tested by ConnectATDScore 86 out of 100. Tested 2026-11-19 on package version 0.49.0. Package: handoff-mcp-server · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 20 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 8 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (3.3 seconds including download)
- Tools offered: 107
- Last published: 2026-11-18
- Weekly downloads (npm): 855
- License: MIT · Direct dependencies: 0
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
handoff_init4 of 4 parameters describedInitialize handoff tracking for a new project. Creates .handoff/ directory structure. Pass preset='beginner' to start with the settings for one person building a first application: trace.profile=minimal, trace.done_guard=warn, session_loop.profile=standard, and the [onboarding] guidance and checks switched on (preflight=run, next_step, smoke_check, release_guard=warn, security_min_nfr). Without preset the config is the plain default. An unknown preset is an error and creates nothing.
handoff_load_context6 of 6 parameters describedLoad handoff context for the current project. Call at session start to resume work. Can also resume a paused session by ID. The returned task_tree is compact by default (only the tasks that belong to this session, with scope_reason; task_tree_meta counts the rest); pass task_tree:'full' for every task.
handoff_save_context22 of 22 parameters describedSave current session state for the next session. Call at session end.
handoff_list_tasks13 of 13 parameters describedList all tasks for the current project with optional filters.
handoff_get_task4 of 4 parameters describedGet full task details (notes, done_criteria, labels, links) by task ID. Use when list_tasks summary is not enough. Response includes trace: {layers, blockers} when the task has at least one requirement-type task_links entry — layers is [{layer, role, count}] and blockers tallies not_run/failing/blocked/reverify/suspect among the linked items' direct verifiers (implements role) or the linked item's own result (executes role); null when the task has no requirement link. Read-only (E6): never writes runs/_latest.json or any document. With include_orphan=true the response also carries orphan: true|false — whether the task is an orphan by the rule of the task_orphan lint rule (no requirement link, not `no-trace`, not skipped, not a parent traced through its children; never in a project with no layer document). The session-closer uses it to decide between done and review; the key is absent unless asked for.
handoff_check_criterion4 of 4 parameters describedToggle a single done_criteria item by index. No need to resend the entire criteria list.
handoff_update_task5 of 5 parameters describedAdd, update, or move a task. Manages the tasks/ directory structure. Include task.schedule.estimate_hours (raw human-effort hours, > 0) when moving a leaf task to in_progress/review/done; it is rejected without one unless the task is a parent, todo, blocked, or skipped. Done guard ([trace] done_guard in config.toml, default "warn"; either done_guard = "block" or a [trace.done_guard] table with mode plus check_suspects/check_profile_layers/check_code_drift, each default true): when task.status is set to "review" or "done" and this task has at least one requirement-type task_links entry with a blocker (not_run/failing/blocked/reverify verifier, a stale task-link suspect [check_suspects], a linked item missing a layer its profile requires [check_profile_layers, missing_profile_layer lint], or a linked item whose impl_refs/test_refs file changed since its content_hash [check_code_drift]), "warn" lists them in the response's warnings (the transition still applies), "block" rejects the whole call unless force=true, and "off" does nothing. A task with no requirement links is never affected by the done guard. Orphan guard ([trace] orphan_guard in config.toml: "off" | "warn" (default) | "block"; independent of done_guard): when task.status is set to "review" or "done" (an existing task changing status, or a task created directly in that status) and the task would have no requirement-type task_links entry after this call, "warn" applies the change and appends a `Warning [ORPHAN_TASK]: ...` line saying how to link the task, "block" rejects the whole call with nothing changed unless force=true, and "off" answers exactly as without the guard. Never affected: a task labelled `no-trace` (also when the label is set in this call), a task whose requirement_ids in this call resolve to a link, a parent task whose leaf tasks are all linked/no-trace/skipped, an update that leaves the status unchanged, and every task of a project with no layer document. The verdict is the one the task_orphan rule of handoff_trace_lint gives. Requirement-link guidance: when this call CREATES a task that names no requirement_ids, the response ends with two information lines, `Info [REQUIREMENT_LINK_MISSING]: ...` (link the task to an existing requirement or add the missing one) and `Info [TRACE_PROPOSE]: ...` (handoff_trace_propose(task_id) lists candidates); the task is created all the same. No such lines when an existing task is updated, when the new task carries requirement_ids or the `no-trace` label or is created as skipped, or in a project with no layer document. Schedule signal (REQ-PLA-005): when an update to an existing task actually changes status, dependencies, or schedule.start_date/due_date/estimate_hours, the response ends with a `schedule_stale: true` line recommending handoff_auto_schedule; no such line means the schedule is not stale (or the project set `[settings] schedule_stale_notice = false`, which never adds the line). When the update moves a task to `done` and the task is linked to items of a `plan` document, the response ends with a `plan_update_needed: [{doc_id, stable_id, current_dev_stage, suggested_dev_stage}]` line (suggested_dev_stage is `implemented`); the line is absent when there is nothing to update or the status did not change.
handoff_get_config1 of 1 parameter describedRead the project's handoff configuration.
handoff_update_config4 of 4 parameters describedUpdate the project's handoff configuration. Pass either `updates` (individual keys) or `preset` (a named set of values), not both. `updates` replies with plain text. `preset` replies with JSON {preset, applied, changes:[{key, old, new}], overwrites:[key], message}: keys that had no value are set at once; when the preset would replace a value the project already set (overwrites is not empty) nothing is written and applied=false unless confirm=true - show `changes` to the user and call again with confirm=true. `[commands]` values must be strings; `[onboarding]` values are validated (preflight: off/check/run, release_guard: off/warn/block, the switches are booleans, command_timeout_sec and smoke_timeout_sec are seconds >= 1).
handoff_doctor3 of 3 parameters describedDiagnose whether the project is ready for agent-driven work: handoff initialized, MCP server registered, CLAUDE.md sections present and filled in (no `TODO(handoff)` left), `[commands]` defined, whether the project's commands succeed, whether Git tracks a file that usually holds secrets (`secrets_untracked`: `.env`, `*.pem`, `*.key`, ... matched by file name against the Git index; file contents are not scanned; skip outside a Git repository) and whether the dependency audit passes (`dependencies_audited`: the result of `[commands] audit`, handed out and judged like the other commands). Works on a project that is not initialized yet. Read-only. This tool never runs a command and never starts a process: it returns the commands in `commands_to_run` [{id, command, timeout_sec}]; run each one yourself from the project root through the shell, stopping it after timeout_sec, then call again with `results` and the tool judges them. Returns JSON {ready, checks: [{id, status, detail, next_step?, command?, exit_code?, duration_ms?, source?}], commands_to_run, warnings}. status is pass / fail / skip / manual; skip means the check was not carried out (no result given, or nothing defined) and is never a pass. Every fail carries next_step. ready is true when nothing failed (a skip does not lower it), except that once results are reported a project without `[commands] test` is not ready. A result whose `command` differs from the current `[commands]` value is not used and fails the check. The same diagnosis is available in a terminal as `handoff-mcp setup --check` (add `--run` to let the CLI run the commands, `--json` for this JSON).
handoff_release_check4 of 4 parameters describedPre-release check of a milestone: is everything it promised done, verified and safe to ship? Returns JSON {milestone, ok, items: [{id, status, detail, refs?, source?, checked_at?}], commands_to_run: [{id, command, timeout_sec}]}. Items, in order: tasks_done (every leaf task of the milestone is done or skipped; refs = the unfinished task ids; a subtask without a milestone of its own belongs to its parent's), no_open_bugs (no open task labelled `bug`), requirements_verified (every requirement-layer item planned for the milestone is `passing`; refs = the others; skip when the milestone has none), tests_pass / smoke_pass / dependencies_audited (the results of `[commands] test` / `smoke` / `audit`), secrets_untracked (Git tracks no file whose name matches `[onboarding] secret_file_patterns`; file contents are not scanned; skip outside a Git repository) and one manual:<name> per entry of `[release] manual_checks`. status is pass / fail / skip / manual. ok is true only when every item is pass: a skip (not carried out) or a manual (waiting for a person) keeps it false. This tool never runs a command and never starts a process: run each entry of commands_to_run yourself from the project root through the shell, stopping it after timeout_sec, then call again with `results`. A call without `results` reports the command items as skip and never falls back on an earlier result. A result whose `command` differs from the current `[commands]` value is not used and fails the item. Pass `confirm: ["manual:<name>"]` once a person has confirmed a manual item; it stays confirmed for that milestone. Results and confirmations passed in are recorded in .handoff/release/<milestone>.json (per command: status, exit code, source, time); a call with neither writes nothing. An unknown milestone is an error. The same check is available in a terminal as `handoff-mcp release-check <milestone>` (add `--run` to let the CLI run the commands).
handoff_next_step1 of 1 parameter describedTell which state the project is in and the one operation to do next. Returns JSON {state, action: {title, command, reason}, facts}. The states are checked in this order and the first that applies is returned: not_initialized (no .handoff/ -> handoff_init), not_ready (handoff_doctor without results is not ready -> what its first failed check says to do), review_pending (a task is in review -> confirm it), in_progress (a task is in progress, or a session is active -> resume it), no_brainstorm (no finalized brainstorm report and no requirement item -> /brainstorm-loop), no_requirements (the requirement layer has no item -> /requirement-loop), ready_tasks (a todo task whose dependencies are all done or skipped -> /session-loop), release_ready (no unfinished task and a milestone that is neither released nor cancelled -> handoff_release_check), all_done (none of the above -> plan what comes next, or, when unfinished tasks remain that cannot start, clear what blocks them). action.command is a slash command, a tool call or a sentence to act on. facts holds the counts the decision looked at (doctor: {ready, failed}, tasks: {total, by_status, unfinished, ready}, active_sessions, brainstorm_reports, requirement_items, milestones: {total, unreleased}); a group the decision did not need is left out. Read-only: it writes nothing, runs no command and starts no process, and it works on a project that is not initialized yet. With `[onboarding] next_step = true`, handoff_load_context carries the same answer as its `next_step` key. This is not handoff_trace_next, which recommends the next verification item of the trace graph. The same answer is available in a terminal as `handoff-mcp next-step`.
handoff_dashboard4 of 4 parameters describedShow handoff status across all projects in configured scan directories. A project that defines [milestones.<name>] entries also carries a `milestones` array (omitted when none are defined), ordered by `order`: {name, version, status, due, tasks:{done,total}, requirement_coverage:{total,covered,coverage_percent}} - tasks are those whose schedule.milestone is the milestone; requirement coverage counts requirement items whose effective milestone it is, covered = dev_stage implemented or beyond (coverage_percent is null when there are none).
handoff_import_context6 of 6 parameters describedImport existing handoff documents into .handoff/ management. AI reads the source material, structures it, and submits everything in one call. Supports nested task hierarchies via children field. Imported tasks carry no requirement link: in a project with at least one layer document the response ends with one `Info [REQUIREMENT_LINK_MISSING]: N imported task(s) have no requirement link: <ids> ...` line naming the imported tasks that are orphans (not labelled `no-trace`, not skipped, not a parent whose leaf tasks are all accounted for); link them afterwards with handoff_update_task(requirement_ids). The line is absent when there is none, and in a project with no layer document. The [trace] orphan_guard is not applied to an import.
handoff_refer9 of 9 parameters describedSend a cross-project referral (improvement request, bug report, work request) to another project's .handoff/. The target project sees it on load_context.
handoff_list_referrals2 of 2 parameters describedList incoming referrals from other projects with optional status filter.
handoff_get_referral2 of 2 parameters describedGet the full details of a single incoming referral by ID (summary, details, tasks with done_criteria, priority, context, status). Use this instead of reading .handoff/referrals/*.json directly.
handoff_update_referral3 of 3 parameters describedUpdate the status of an incoming referral (open -> acknowledged -> resolved).
handoff_update_session9 of 9 parameters describedIncrementally update the active session. Toggle checklist items, add decisions, notes, or context pointers without resending everything. Use during work for progressive updates.
handoff_log_time4 of 4 parameters describedLog hours worked on a task. Adds to actual_hours and deducts from remaining_hours atomically, and appends an entry to .handoff/time_log.jsonl.
handoff_get_metrics3 of 3 parameters describedGet project metrics: completion %, effort tracking, overdue tasks, budget status, and milestone breakdown. Each milestone carries requirement_coverage {total, not_started, in_progress, implemented, tested, verified, coverage_percent} aggregated from the requirement-type task_links of its tasks (all zeros when the tasks link no requirements or when the derived docs/_requirements_summary.json has not been written yet). Pass plan_id to scope everything to the tasks of one plan document (and their subtasks).
handoff_snapshot_metrics1 of 1 parameter describedSave today's project-wide metrics snapshot to .handoff/metrics_snapshots/<YYYY-MM-DD>.json (UTC date; overwrites an earlier snapshot of the same day) and return it. handoff_save_context already takes this snapshot automatically; use this tool for an on-demand capture.
handoff_get_metrics_snapshot2 of 2 parameters describedRestore the task state (id, title, status, assignee, priority per task) as of the end of a past UTC day (REQ-RPT-004). Read-only. The nearest schema_version 2 snapshot dated that day or earlier is the base and its later task.status_changed events from events.jsonl (up to the end of the day) are replayed (source=snapshot_plus_events); a snapshot of exactly that day that no later event touched is returned as is (source=snapshot, exact=true); with no usable snapshot the state is estimated backwards from the current task tree using the `from` status of the first status change after the date (source=events_estimate). Replayed and estimated states are not exact (exact=false): tasks deleted after the date cannot be restored by the events estimate, tasks created after the base snapshot that never changed status, and title/assignee/priority edits made since, cannot be recovered; detectable gaps are listed in `warnings`. Schema v1 snapshots carry no task list and are skipped.
handoff_list_sessions5 of 5 parameters describedList all sessions (open, active, paused, closed) with summary info. Use handoff_get_session for full detail.
handoff_list_assignees1 of 1 parameter describedList all team members/assignees from config.toml with their task counts and effort stats.
handoff_bulk_update_tasks3 of 3 parameters describedUpdate multiple tasks in one call. Useful for applying auto-schedule results or bulk status/assignee changes. Enforces the same estimate rule as handoff_update_task: a leaf task in status in_progress/review/done must carry schedule.estimate_hours (> 0). Offending updates are rejected individually and reported in errors[]; the rest still apply. Moving a task into review/done also runs the [trace] done_guard check (warn/block/off) and the [trace] orphan_guard check (a task with no requirement link: warn/block/off) like handoff_update_task. Fields not listed in the updates schema (e.g. dependencies, labels, done_criteria, requirement_ids, scope_paths) are rejected per update into errors[] rather than silently ignored; use handoff_update_task for them.
handoff_get_session2 of 2 parameters describedGet full detail of a specific session by ID. Returns decisions, checklist, handoff notes, context pointers, etc.
handoff_get_capacity4 of 4 parameters describedGet work capacity for a date range. Shows available hours per day based on calendar config, and allocated hours from scheduled tasks.
handoff_auto_schedule4 of 4 parameters describedRun auto-scheduler to compute optimal task dates based on dependencies, estimates, and calendar capacity. Returns change diff; applies changes unless dry_run=true. Also reports agent_capacity (registered agents' claimed task count vs. max_concurrent_wts) and ready_tasks (dependency-resolved todo tasks sorted by priority) to support next-task auto-assignment. The response carries `schedule_stale: false` (the schedule was just recomputed; doc_save/update_task re-flag it on the next relevant change). A task with no `order` of its own and no dependencies takes the smallest `order` of the plan-document items it is linked to (a task's own order and dependency order always win). If plan documents cannot be fully read, the schedule is still computed and the response carries `warnings`. Milestone deadlines (REQ-MS-SCHED-001): a scheduled task whose `schedule.milestone` has a `date` in config.toml and whose computed due date falls after it adds a `warnings` entry (`Milestone '<name>' (deadline <date>): task <id> scheduled to <due> exceeds deadline by <n> days`); the response always carries `milestone_summary` (per milestone: milestone, date, task_count, total_estimate_hours, latest_due, overdue) for the tasks scheduled in this run. Milestones without a date, and tasks without a milestone, are unconstrained. Schedule uses raw estimate_hours directly (ai_estimate_multiplier is NOT applied; it affects only metrics/capacity reports). A task with no estimate_hours is scheduled with settings.default_estimate_hours from config.toml (default 8.0; set it with handoff_update_config key `settings.default_estimate_hours`, a number > 0), and the response `warnings` then carries one entry stating how many tasks used the default and its value.
handoff_add_assignee11 of 11 parameters describedAdd a team member to config.toml [assignees.<key>]. Fails if the key already exists.
handoff_update_assignee11 of 11 parameters describedUpdate an existing [assignees.<key>] entry. Only provided fields change; pass null to clear a field.
handoff_remove_assignee2 of 2 parameters describedRemove a team member from config.toml and unassign them from every task.
handoff_list_milestones2 of 2 parameters describedList all milestones defined in config.toml [milestones.*], ordered by `order` (milestones without one last, then by name). Each entry carries date, color, description, version, status (planning when unset), order and depends_on. Pass status_filter to show only milestones in one status.
handoff_add_milestone10 of 10 parameters describedAdd a milestone to config.toml [milestones.<name>]. Fails if it already exists. Optional version, status (default planning), order and depends_on; a depends_on entry naming an undefined milestone is saved with a warning.
handoff_update_milestone10 of 10 parameters describedUpdate an existing [milestones.<name>] entry. Pass null to clear a field. A status change must move forward along planning -> active -> frozen -> released (cancelled is allowed from any status); a backward move, or leaving cancelled, is rejected unless force is true. Release guard: when `[onboarding] release_guard` is `warn` or `block`, moving a milestone to `released` consults its pre-release check (the items of handoff_release_check) without running any command: tasks_done, no_open_bugs, requirements_verified, secrets_untracked and manual:* are judged on the spot, while tests_pass, smoke_pass and dependencies_audited are read from the last result recorded by handoff_release_check (no record, or a record for a command that has since changed, counts as not verified). `warn` releases the milestone and appends one `Warning: release check: <id> [<status>] <detail>` line per item that did not pass; `block` rejects the call with the same list and changes nothing, unless force is true. Both say when each recorded command result was judged, since a record may be out of date: run handoff_release_check and report fresh results first. With release_guard `off` (the default) nothing is checked and the reply is unchanged.
handoff_remove_milestone2 of 2 parameters describedRemove a milestone from config.toml.
handoff_update_calendar10 of 12 parameters describedPatch the project [calendar] section (work hours, work_start_hour/work_end_hour, max_parallel_tasks, closed days, day_hours, schedule_mode). Only provided fields change.
handoff_update_labels2 of 2 parameters describedSet the project-level label vocabulary (top-level labels array in config.toml).
handoff_start_project3 of 3 parameters describedSet the project started_at date and optionally shift all task dates so the earliest start aligns to it.
handoff_memory_save9 of 9 parameters describedSave a long-lived project memory (lesson/rule/convention/gotcha) that future sessions should respect. Detects exact and near-duplicate memories: an exact match is reported (not rewritten), a near-duplicate is returned as a 'conflict' with both bodies for you to merge (call again with merge_into=<id> and absorb_ids=[…]) or save separately with force=true. Returns a JSON string.
handoff_memory_query7 of 7 parameters describedReturn the project memories most relevant to the given text/file (BM25 + scope-path boosting). Intended for automatic injection via hooks, but callable directly. Returns a JSON string {"memories":[{id,text,kind,score}],"injected_count"}.
handoff_memory_delete2 of 2 parameters describedDelete a project memory by id (full id or unique prefix). Use for AI-driven cleanup of stale memories. Returns a JSON string {"status":"deleted","id"}.
handoff_memory_cleanup3 of 3 parameters describedHousekeep the project memory store (safe to run at SessionStart: by default it deletes and rewrites no memory). Returns review candidates: near-duplicate clusters (merge with memory_save merge_into=…) and old memories whose updated_at is past stale_days (an age signal only — an old memory is not necessarily obsolete, and nothing here proposes deleting it). With apply_exact_merges=true it also merges exact duplicates losslessly (oldest kept, others deleted and recorded in superseded_ids; one memory.merged event per group). Garbage-collects old per-session injection sidecars (settings.memory_injected_gc_days; 0 = never). Returns a JSON string {"auto_merged_exact":n,"cleanup_recommendations":{"similar_clusters":[…],"stale":[…]},"injected_sidecars_removed":k}.
handoff_memory_strip_usage_stats2 of 2 parameters describedOpt-in migration for projects upgraded from v0.47.2 or earlier: remove the obsolete hit_count / last_referenced_at keys from existing memory files (they are no longer written or read). Dry-run unless apply=true. Only those two keys are removed; updated_at and every other field are left unchanged, and files without the keys are not rewritten. Unparseable files are skipped and counted. Returns counts only: {"mode":"dry_run"|"apply","scanned":n,"with_usage_stats":n,"stripped":n,"skipped_unparseable":n}. CLI: handoff-mcp memory strip-usage-stats [--apply].
handoff_fork_session7 of 7 parameters describedFork a new session from an existing one. Inherits decisions, context_pointers, references, and handoff_notes by default. The forked session becomes active with parent_session_id set.
handoff_merge_sessions6 of 6 parameters describedMerge multiple sessions into one. Combines decisions, notes, references, and context_pointers. Detects duplicate decisions as conflicts. Source sessions (except the target) are closed by default.
handoff_timer_start2 of 2 parameters describedStart a timer for a task. If VSCode extension is running (authority alive), delegates to the extension via a request file. Otherwise starts an MCP fallback timer.
handoff_timer_stop2 of 2 parameters describedStop the timer for a task. If VSCode extension is the authority, delegates the stop command. If MCP is the authority (fallback), stops the internal timer and adds elapsed time to the task's actual_hours (with optimistic locking).
handoff_timer_get_time2 of 2 parameters describedGet the current timer state for a task. Returns elapsed time, timer state (tracking/paused/stopped), authority info, and projected total hours. Reads from .handoff/timer/state.json.
handoff_brainstorm_start6 of 6 parameters describedStart a brainstorming session. Creates the session state (.handoff/brainstorm/<brainstorm_id>.json), a deliberation-log document and a brainstorm-report document (both plain handoff-docs, no layer), and initializes the coverage tracker. Required topics: vision, motivation, target-users, core-value, scope; optional topics (tech-constraints, business-constraints, revenue-model, hardware, security, regulatory, or any custom tag) join the tracker when first discussed. Returns {brainstorm_id, log_doc_id, report_doc_id, coverage} plus project_type, target_milestones and recommended_topics when given/applicable.
handoff_brainstorm_turn10 of 10 parameters describedRecord one dialogue turn: appends 'Turn N' (timestamp, [topic_tag], summary, decisions, open questions) to the deliberation log, mirrors decisions into the matching report section, and updates the coverage tracker (a turn on a topic moves it not_started -> in_progress; a turn carrying decisions moves it to covered). Returns {turn_number, coverage, uncovered_topics, required_covered, phase}. required_covered is true once every required topic is covered (the cue to propose the research phase). Fails once the session is finalized.
handoff_brainstorm_status2 of 2 parameters describedRead the current state of a brainstorming session from .handoff/brainstorm/<brainstorm_id>.json (survives process restarts): {brainstorm_id, topic, phase (dialogue/research/convergence/finalized), turn_count, attachments_count, coverage, uncovered_topics, required_covered, decisions, open_questions, topics:[{topic, required, status, turns, decisions}], log_doc_id, report_doc_id}.
handoff_brainstorm_finalize13 of 13 parameters describedFinish a brainstorming session: rewrites the report document into its final form (executive summary, scope in/out/undecided, priorities, research topics and requirement hints; research results already written under '## 6. 調査結果' are preserved), appends a completion mark to the deliberation log, and sets the session status to finalized. In-scope, priority and requirement-hint entries are rendered as traceable items (BS-SCOPE-NNN, BS-PRIORITY-NNN, BS-HINT-NNN) and, when config.toml declares a 'brainstorm' [[trace.layer]], the report is filed under layer 'brainstorm' so requirement docs can `refines` them. Returns {report_doc_id, log_doc_id, status:'finalized', layer ('brainstorm' or null), item_ids, warnings} (a warning explains how to declare the layer when it is missing). For a gui-* project_type the report also gets '## 8. GUI 設計概要' (screen table, screen flow and UX policy from screens / screen_flow / ux_policy) and the priorities and hand-off sections are numbered 9 and 10. Fails if the session is already finalized.
handoff_doc_save18 of 18 parameters describedSave a complete document. The body MUST be a whole, human-readable Markdown document starting with a level-1 heading (e.g. `# Authentication Spec`) — group related content into ONE document (for example, all ADRs belong in a single `# Architecture Decision Records` document with each ADR as an `## ADR-001: ...` section, NOT as separate documents). MCP handles section-level indexing internally, so do not pre-split content yourself. To append a new section to an existing document (e.g. adding ADR-003) without rewriting the whole body, pass `append_body` with just the new section instead of `body` — `body` and `append_body` are mutually exclusive, and `append_body` requires an existing `doc_id` (there is nothing to append to when creating a new document). To update only metadata (e.g. `task_ids`, `tags`, `auto_inject`) on an existing document without touching its content, pass `doc_id` and omit both `body` and `append_body` — the existing body is kept verbatim (sections/content_hash are recomputed from it, but nothing is rewritten to disk). New documents (no `doc_id`) always require `body`. The body (or, for append_body, the resulting combined body) is stored verbatim at _doc.<slug>.md and split in-memory into a `sections` byte-offset index (no per-section files), syncing the bidirectional task<->doc link when task_ids is given. Omit doc_id to create a new document (slug is then required and must be unique); pass an existing doc_id to update it (slug is taken from the existing document — it cannot be renamed via doc_save). Returns a JSON string {doc_id,slug,title,doc_type,section_count,content_hash,warnings:[…]} — warnings lists any task_ids that could not be resolved, and includes a soft notice when the saved body does not start with a level-1 heading (the save is never rejected for this). Response also carries `scaffold_suggestions` ([{stable_id, title}] of requirement items in a doc_type=plan document that no task links to yet; empty for other doc types; suggestion only, nothing is created) and `schedule_stale` (true when this save changed the document's task_ids, i.e. handoff_auto_schedule should be re-run; always false when `[settings] schedule_stale_notice = false`). A `spec`/`design` document saved without a layer adds a structured `DIAG-D001` warning unless `[settings] layer_missing_notice = false`. When the save removes requirement item(s) that no document owns anymore (a requirement merely moved to another document keeps its links), the task-side requirement links to them are removed automatically and tasks left with no requirement link at all are returned as `orphaned_tasks` ([{task_id, title}], present only when non-empty); task status is never changed. Layer documents: a `- parent:` attribute (requirement tree; several comma-separated parents make a DAG) that newly names a nonexistent, other-layer or self parent, or closes a parent cycle, rejects the save before anything is written — the error message ends with `errors: [{code: self_parent|parent_dangling|parent_cross_layer|tree_cycle, item, message, path?}]`; a dotted heading id (`### DSP-1.2.3`, which the ID grammar splits into `DSP-1` plus a title) is saved with a `dotted_id` warning. SPEC-TREE-013: when the write removed items that other items declared as their `parent`, the response includes orphaned_children:[stable_id] — the decomposition children left with no surviving parent (a DAG child that still has another existing parent is not orphaned); the key is absent when there are none.
handoff_doc_update_section5 of 5 parameters describedReplace a single section of a document by its seq number, without re-sending the whole document body. new_content is the replacement Markdown (including the section's own heading line); an empty string deletes the section. Sections are computed on-demand from the current body (same as doc_get/doc_save), so seq must match the document's current section numbering. expected_hash is an optional optimistic lock: when given, it must match the section's current content_hash or the call errors with the actual current hash (for retry) and makes no change. Updates the document's updated_at and content_hash, and — if a verification matrix item exists at this fragment_seq — surfaces a warning that it is now stale (its content_hash_at_verify no longer matches). Returns a JSON string {doc_id,seq,heading,content_hash,updated_at,section_count,warnings?:[…]}. On a layer document the same `- parent:` validation as handoff_doc_save applies to the resulting body (rejected before anything is written). SPEC-TREE-013: when the write removed items that other items declared as their `parent`, the response includes orphaned_children:[stable_id] — the decomposition children left with no surviving parent (a DAG child that still has another existing parent is not orphaned); the key is absent when there are none.
handoff_doc_get4 of 4 parameters describedRead a document by doc_id or slug. format='full' returns the original Markdown body (read directly from _doc.<slug>.md) plus metadata; 'meta' returns metadata only (no body, cheap for graph traversal); 'section' returns one section's body (byte-sliced from the document body, requires seq). Returns a JSON string.
handoff_doc_export18 of 18 parameters describedExport documents as PDF (REQ-PDF-006, bundle: REQ-PDF-020). Pass doc_id (one document, by id or slug) or doc_ids (several; one PDF each, in request order, duplicates exported once) or scope (REQ-PDF-021: documents selected by layer/doc_type/milestone/tags/task_id, AND-combined, usable with bundle=true for a merged PDF of the matches; no match is an error) — exactly one of the three, or doc_tree (REQ-PDF-026: see below) instead of all of them. The Markdown body is converted to Typst (headings, lists, tables, code, links, images, ```typst passthrough blocks; ```mermaid blocks are rendered to SVG when mmdc is installed), wrapped in a template and compiled with Typst. Builds with the bundled Typst compiler need nothing installed (HANDOFF_TYPST_BIN is deprecated and ignored there); otherwise the Typst CLI (>= 0.12) must be on PATH or HANDOFF_TYPST_BIN, and when it is missing the call fails with install instructions. mmdc/Chrome are optional: without them Mermaid blocks stay code blocks and a warning is returned. Output: .handoff/exports/<doc_slug>.pdf (the intermediate .handoff/exports/<doc_slug>.typ is regenerated on every export — edit the Markdown or the template, never the .typ); with output_dir the PDF is placed there instead. Templates live in .handoff/templates/ (default.typ, report.typ, spec.typ are generated on first use and never overwritten, so they can be customised per project). Returns a JSON string {format, exported, failed, pdf_path (doc_id form only), pdf_paths, documents:[{doc_id,slug,title,pdf_path,typ_path,warnings} | {doc_id,error}], warnings:[{doc_id,code,message,detail?}]}. Non-fatal problems (missing image, unrenderable Mermaid block, missing Japanese font, raw HTML) are warnings and never abort the export; a Typst compile error fails the document with Typst's own diagnostics and leaves no PDF. In a doc_ids batch a failing document is reported in documents[] and the others still export; the call only errors when none could be exported. Bundle mode (REQ-PDF-020): with bundle=true the doc_ids are merged into ONE PDF instead of one each — a cover with the bundle_title and the numbered list of documents, a single table of contents covering every document's sections, and (page_break_style, REQ-PDF-024: break | section | none; default break) each document starting on a new page under its own title as a level-1 heading (its own headings sit below it, the shallowest on level 2; a leading '# <title>' that repeats it is dropped). Needs doc_ids (not doc_id) — or scope / doc_tree. Output: .handoff/exports/bundle[-<title>].pdf; the response is {format, bundle:true, bundle_title, exported (documents merged), failed, pdf_path, typ_path, pdf_paths:[pdf_path], documents:[{doc_id,slug,title} | {doc_id,error}], warnings} — warnings of a bundle come from one shared run and carry no doc_id; a document that cannot be read is listed with its error and the rest are still bundled. A template whose conf predates the bundle cover (no 'documents' parameter) still exports, with a template_outdated warning and no document list on the cover. Cover page (REQ-PDF-025): the document id is shown automatically; cover_version, cover_status and cover_organization (optional, applied to every PDF of the call incl. the bundle cover) supply the version, status and organization, which documents do not store themselves. Requirement meta blocks (REQ-PDF-030): with enrich=true (the default) every heading that starts with the stable id of a requirement/spec item (e.g. '## REQ-001 Title') gets a visual meta block directly under it instead of losing its attribute lines — priority and dev_stage badges, horizontal and vertical coverage bars, the titled refines/verifies targets, the implementing tasks (id, title, status) and the acceptance criteria, each marked ✓ (checked: a '[x]' mark in the bullet, or a passing verification item covers it) or ○ (not yet). The data is the trace graph's (the same as handoff_doc_req_list / handoff_trace_report, read-only); the…
handoff_doc_list10 of 10 parameters describedList/search documents. Filters (doc_type, tags [AND — every tag must be present], task_id) are applied first; an optional query BM25-ranks the survivors by title + tags + body text. include_body includes each matching document's full body, read from _doc.<slug>.md (default false — metadata only). unreadable lists any _doc.<slug>.md whose frontmatter failed to parse (FR-804: reported instead of silently dropped) as {slug,error,line?} — use handoff_doc_repair_frontmatter to fix known non-standard shapes. warnings carries the same list as human-readable strings (one per unreadable document) for callers that just want to surface/log them without parsing the structured array. Returns a JSON string {documents:[…],unreadable:[…],warnings:[…]}.
handoff_doc_delete2 of 2 parameters describedDelete a document (by doc_id or slug) and its body file. Unlinks the document from any linked tasks' task_links, removes it from its parent's children list, and clears parent_id on any of its own children (orphaning them — delete does not cascade to descendants). Returns a JSON string {deleted,doc_id,section_count,warnings:[…]}.
handoff_doc_reassemble3 of 3 parameters describedRead a document's (by doc_id or slug) original Markdown body directly from _doc.<slug>.md, restoring BOM/frontmatter, and detect drift (the body's current content hash no longer matches its recorded content_hash — e.g. edited directly outside doc_save). Optionally writes the body to output_path. Returns a JSON string {doc_id,body,drifted,output_path?}.
handoff_doc_tree4 of 4 parameters describedTraverse a document's family tree (parent/children) starting from doc_id (id or slug), up to depth levels of descendants, plus the immediate parent (if any). include_related additionally attaches the document's related (semantic) links. Returns a JSON string tree {id,title,doc_type,parent,children:[…],related:[…]}.
handoff_doc_verify16 of 16 parameters describedOperate on a document's verification matrix: generate (create a matrix from the document's current sections, error if one already exists), check (mark fragment_seq — or its sub_item_id/sub_item_index — verified, recording verified_at/reviewer/notes/content_hash_at_verify — fragment_seq may be a single section seq or an array of seqs to verify in one call), check_all (verify every section and sub_item in the matrix in one call, error if no matrix exists yet), skip (mark fragment_seq — or its sub_item_id/sub_item_index — skipped), sync (re-sync the matrix with the document's current sections — adds new sections as pending, removes deleted ones, preserves existing item status), set_refs (update impl_refs/test_refs for fragment_seq, or — with sub_item_id/sub_item_index given — for that SubItem instead of the parent item; requirements-traceability P0 §3.3), set_dev_stage (requirements-traceability P0 §2.4/§3.3: set a SubItem's dev_stage — sub_item_id or sub_item_index required, since dev_stage is a SubItem-only field; value must be one of not_started/in_progress/implemented/tested/verified), set_priority (P0 §3.3: set a SubItem's priority — sub_item_id or sub_item_index required; value must be one of P0/P1/P2/P3), add_item (v2, spec §7.2: with fragment_seq given, append a SubItem — description required — to that section's sub_items; with fragment_seq omitted, append a new freeform top-level item not tied to any section — label required), backfill_stable_ids (requirements-traceability integration-reform §3.3: one-shot bulk backfill — scans every SubItem across the whole matrix and mints a stable_id, via the same derivation `add_item` uses, for every one that doesn't have one yet; SubItems that already have a stable_id are left untouched; collisions against already-assigned or already-backfilled ids are disambiguated with a numeric suffix, same as add_item; doc_id is the only input), or suggest_refs (t124.6: read-only — scans the document's scope_paths for source/test files whose fn/struct/impl/mod definitions or test functions fuzzy-match each verification item's heading, and returns candidate impl_refs/test_refs per item for the caller to review and apply via set_refs; errors if no matrix exists yet). To link a task to a requirement SubItem, use handoff_update_task(task.requirement_ids=[...]) instead (handoff_doc_verify(action="link_task") was removed). For every SubItem-addressing action (check, skip, set_refs, set_dev_stage, set_priority), sub_item_id (the stable, immutable SubItem.stable_id) takes precedence over sub_item_index (positional, back-compat fallback) when both are given; a mismatch between them is reported as a non-fatal warning in the response, not an error. fragment_seq is optional when sub_item_id is given (FR-806): the SubItem is then located by stable_id across every VerificationItem in the matrix, including freeform ones (fragment_seq: None, e.g. from add_item with no fragment_seq, or from handoff_doc_req_import). fragment_seq is still required when addressing by sub_item_index (which is only unique within one VerificationItem's sub_items) or when the action targets a section item directly (no sub_item_id/sub_item_index given at all). Overall verification_status is recomputed after every mutation: 'pending' if all items pending, 'verified' if all verified/skipped, else 'in_review'. `_requirements_summary.json` (the VSCode-extension-facing aggregate cache) is refreshed after every mutating action, including add_item and backfill_stable_ids. Layer document write guard: on a document with layer set, add_item, set_priority, backfill_stable_ids, and set_refs (only when the call includes test_refs — impl_refs-only is still allowed) are refused with an error telling the caller to edit the body instead, since those fields (description/layer/refines/verifies/method/priority/test_refs) are defined by the Markdown body and would just be overwritten or orphaned by the next sync; set_dev_stage, check, check_all, skip, sync …
handoff_doc_verify_status4 of 4 parameters describedGet a document's verification matrix status: overall verification_status, progress counts (checked/skipped/pending/total/stale/percentage — v2: counts leaf items, i.e. sub_items and freeform items, spec §7.4), and (when include_items=true) every item with a computed stale flag (its content_hash_at_verify no longer matches the section's current content_hash — spec §3.5). Errors if the document has no verification matrix yet (use handoff_doc_verify(action='generate') first). Returns a JSON string {doc_id,title,verification_status,progress:{…},items?:[…]} by default, or (format='checklist') a Markdown checklist rendering (spec §7.3) instead.
handoff_doc_repair_task_ids1 of 1 parameter describedExplicit repair: forces a full, all-tasks-scanning rebuild of every requirement SubItem's task_ids from TaskData.task_links (the source of truth) across the whole document corpus, correcting any drift (manual edits, imported data, bugs). Also repairs each document's own task_ids from TaskLink{link_type:'doc'} entries, but append-only: an id already in a document's task_ids with no matching TaskLink{doc} is left in place rather than removed (handoff_trace_lint's task_ids_drift rule reports it instead) — only an explicit handoff_doc_save(task_ids=...) call ever removes one. Every live link-change path (handoff_update_task requirement_ids, handoff_doc_verify link_task, handoff_doc_save task_ids) and layer sync already keep task_ids in sync differentially as they run — this tool is only for when state has drifted anyway. Unlike handoff_trace_report's own self-repair pass (which is gated on the tasks_* input fingerprint, and skips the rescan as a cheap no-op when nothing has changed since the last full-corpus sync), this tool always runs its rescan unconditionally with no gate — a caller reaching for it has already decided a repair is needed. Returns a JSON string {ran,sub_items_changed,docs_changed,doc_task_ids_appended} (ran is always true here).
handoff_doc_repair_frontmatter3 of 3 parameters describedReports and (optionally) fixes documents whose frontmatter fails to parse (FR-804, E11) — the same set handoff_doc_list's unreadable field reports. Only recognizes specific known non-standard shapes (a bare 'key:' line followed by its flow-style value, e.g. `[]`, on its own line; tab indentation) — an unrecognized malformation is reported in unrepaired rather than guessed at. dry_run (default true) reports what would change without writing anything; dry_run=false rewrites the document through the same canonical writer every doc_save-style mutation uses, so it re-enters handoff_doc_list's normal results afterward. slug narrows the scan to one document. Returns a JSON string {dry_run,repaired:[{slug,applied,fixes:[…]}],unrepaired:[{slug,error}]}.
handoff_doc_graph3 of 3 parameters describedBuild a graph of every document in the project: nodes (one per document, with id/slug/title/doc_type/tags/task_ids/section_count/updated_at, plus verification_progress {total,verified} when include_verification=true and a matrix exists), edges (explicit parent_id -> type='parent_child'/direction='down', explicit related[] -> type=<rel>/direction='forward', and — when include_implicit=true — implicit shared_task edges for documents sharing task_ids and shared_scope edges for documents sharing scope_paths), and layers (doc ids grouped by doc_type). Intended for graph-visualization UIs. Returns a JSON string {nodes:[…],edges:[…],layers:{…}}.
handoff_doc_trace3 of 3 parameters describedTrace a document's family-tree lineage from doc_id (id or slug): direction='up' walks the child->parent chain to the root; 'down' walks parent->children (DFS); 'both' (default) merges the up chain, the target doc, and the down chain into one ordered chain (root to leaf). related (implements/references/etc.) documents encountered along the chain are appended as detour entries. Multi-child forks encountered in the down direction are additionally reported in branches[] (one entry per fork, {fork_from,docs:[…]}). Cycle-safe: a visited set skips any document already seen in the traversal. Returns a JSON string {chain:[{id,title,doc_type,rel}…],branches:[{fork_from,docs:[…]}…]}.
handoff_doc_query9 of 9 parameters describedInject document sections relevant to the current prompt/file/task (hook-driven context injection, mirrors memory_query at section granularity). Ranks by BM25 relevance + scope_paths match + task_id affinity, then stages each result as 'full' (whole section body, when its token estimate is within the inline threshold) or 'outline' (heading + sibling table of contents only, for larger sections — fetch the body via doc_get(format='section')). With session_id, already-injected sections (same content_hash) are skipped this session; mark_injected (default true) records survivors. suppress_doc_ids excludes given documents from this call's results; combined with suppress_until_changed=true (requires session_id), the suppression is recorded in the session's injected sidecar and persists across future calls until that document's content_hash changes. Returns a JSON string {documents:[…],injected_count}.
handoff_doc_analyze4 of 4 parameters describedRead-only scan of a Markdown file or directory (never writes). Auto-detects doc_type (keyword scan), tags (frontmatter + heading tokens), scope_paths (code/inline file paths), and a suggested_slug (derived from title) per file; extracts and classifies Markdown links (internal/external/broken); proposes a parent/children tree from directory structure (skip with flatten=true). Returns a JSON conditioning report {files_scanned,auto_resolved:[…],needs_review:[…],proposed_tree:{…}} for AI review before handoff_doc_import.
handoff_doc_import4 of 4 parameters describedBulk-import pre-existing Markdown files. Each file becomes ONE document in .handoff/docs/ — the file's content is stored as-is, including its h1 heading. Do NOT split a single source file into multiple documents; MCP indexes sections internally. Writes an analyzed payload (from handoff_doc_analyze, with the AI's overrides applied) as new documents. Each analyzed.auto_resolved entry must carry its file's full Markdown 'body' (doc_import writes from the payload, it does not re-read the filesystem). Each document's slug is taken from its override's 'slug' if given, else its suggested_slug, disambiguated with a numeric suffix on collision. Persists every file as a document, applies proposed_tree parent/children relationships, links task_ids to every imported document (bidirectionally), and invalidates the doc corpus cache. Returns a JSON string {imported_count,documents:[{doc_id,slug,title,section_count}],warnings:[…]}.
handoff_doc_req_list11 of 11 parameters describedList individual items (every SubItem with a stable_id, of any layer — V-model layer items and implicit acceptance-verification items included, not only requirement-layer ones) across every document's verification matrix, with filtering, sorting, and pagination (requirements-traceability P1 §4.2; task_id filter added by the integration-reform §3.1). SubItems without a stable_id yet are excluded (counted in a DIAG-R002 info warning). Filters: priority (SubItem.priority exact match), dev_stage (SubItem.dev_stage exact match; a SubItem with no dev_stage set counts as 'not_started'), category (the stable_id's text before its first '-', matched exactly and case-sensitively: 'C07' for 'C07-1.2', 'REQ' for 'REQ-004', 'CART' for 'CART-001-003'), has_tests (whether test_refs is non-empty), task_id (only SubItems whose task_ids contains this task id — set via handoff_update_task's requirement_ids field; answers 'which requirements does task X implement?'), milestone_filter (only SubItems whose effective milestone matches: the item's own '- milestone: <name>' attribute line, else the document-level milestone set via doc_save's milestone argument; each returned item carries that effective value as 'milestone' when set; GUI attributes parsed from '- mock:' / '- golden:' / '- viewport:' / '- capture_method:' item lines are returned as 'mock' / 'golden' / 'viewport' / 'capture_method' when set, with capture_method falling back to config.toml [gui] default_capture_method). sort selects the ordering key ('stable_id' default — natural order, so FR-101 precedes FR-1001; 'priority', 'category', 'dev_stage' — plain string order, an unset priority sorts as empty i.e. first ascending, an unset dev_stage as 'not_started'; ties always break on stable_id's natural order); order is 'asc' (default) or 'desc'. limit (default 100) and offset (default 0) paginate after filtering/sorting; total reflects the full filtered count before pagination. verification_status is the SubItem's own stored status field, not the V-model state (use handoff_trace_report for that). Each returned item's primary key is stable_id — sub_item_index is included only for back-compat with positional handoff_doc_verify addressing; prefer stable_id (as sub_item_id) for any follow-up handoff_doc_verify call. Returns a JSON string {items:[{stable_id,title,priority,dev_stage,verification_status,impl_refs,test_refs,doc_id,doc_slug,fragment_seq,sub_item_index,task_ids,milestone?,mock?,golden?,viewport?,capture_method?}],total,offset,limit,warnings:[…]} (the warnings key is absent when there is nothing to warn about). warnings carries a DIAG-R002 note for skipped no-stable_id SubItems and a diagnostic when documents exist with no 'layer' set and no verification matrix yet (their requirements cannot appear in items until doc_save(layer=...) generates one, or — if you already imported req_* SubItems into these documents and want them under V-model tracking — see the handoff-trace skill's references/migration.md (write a new layer document rather than setting a layer on this one), since the two representations are not combined on one document) — if items is unexpectedly empty, check warnings before assuming no requirements exist.
handoff_doc_req_status4 of 4 parameters describedCross-document requirements progress summary — aggregates every SubItem with a stable_id across every document's verification matrix into by_status (SubItem.dev_stage counts; a SubItem with no dev_stage set counts as 'not_started'), by_priority (per-priority {total,implemented,tested,verified}; a SubItem with no priority set is bucketed under 'unset'), by_category (per-'C{n}'-prefix {total,implemented,coverage_pct}, derived from stable_id), and coverage ({impl_pct,test_pct,verified_pct} across every counted SubItem) (requirements-traceability P1 §4.1). Filters, applied before aggregation: tags (only documents whose DocMetadata.tags contains at least one of the given tags), priority (only SubItems whose priority exactly matches), category (only SubItems whose stable_id's 'C{n}' prefix matches). Every call also refreshes .handoff/docs/_requirements_summary.json — a cache file the VSCode extension reads directly instead of calling MCP tools — with the FULL, unfiltered aggregate across every document, regardless of this call's filters. Returns a JSON string {total,by_status:{…},by_priority:{…},by_category:{…},coverage:{impl_pct,test_pct,verified_pct}}.
handoff_doc_req_import7 of 7 parameters describedBulk-generates SubItems (with stable_id, and optionally priority and dev_stage) from a document's Markdown requirement-tree heading hierarchy, merging against its existing verification matrix (requirements-traceability P1 §4.3-4.4, plus the aelm-referral robustness additions below). Locates the section whose heading contains heading_pattern (default '要件ツリー'); when several headings match (or the shallowest match turns out to have no children at all — e.g. an unrelated appendix heading that only incidentally contains the pattern substring), the shallowest non-empty match wins. If no heading's text contains heading_pattern anywhere in the document, falls back (FR-802) to scanning for the first heading whose text starts with '2.' (the requirement-tree is conventionally section 2) and treats it plus its siblings as the section — this covers documents whose requirement-tree subsections are numbered but have no enclosing '## 2. 要件ツリー' wrapper heading; when this fallback fires it is reported as an informational parse_errors entry, not silently. Every deepest-level heading within the located section becomes one requirement candidate (its own heading text is the description; stable_id is derived the same way handoff_doc_verify's generate action derives one). When priority_source='gap_table' (default), also locates the section whose heading contains gap_table_pattern (default 'ギャップ分析') and parses every pipe-delimited Markdown table within it — not just the first — that has both >= 3 columns and a recognizable priority column (FR-802: a 2-column priority/status legend table, e.g. '優先度 | 定義', is skipped even though its header cell is also literally named '優先度'; a gap-analysis section split into several numbered subsections, each with its own per-item table, has every one of those tables' rows merged together). Each table's header cells are matched, per field, against column_map first when given (an explicit override — see column_map below — for a header wording no built-in synonym covers, e.g. '重要度'/'Pri.' for priority or '項目' for name), then against known synonyms (FR-802): the ID column (要件ID / ID / REQ ID), the name/description column (要件名 / 要件 / 機能, falling back to the first column that is neither the ID nor the priority column when no synonym matches), the priority column (優先度 / Priority), and — separately — an implementation-status column (実装状態 / 現状 / ステータス / status). A column_map field only applies to a table when it actually resolves against that table's own header (an index in range, or a header string matching one of its cells) — otherwise that field falls through to synonym auto-detection for that table, so one column_map still works across a document whose several gap tables aren't all shaped alike. Each candidate is matched against a table row by exact-ID-token comparison first (an ID-shaped token — digits plus '.'/'-'/'_' — extracted from the row's ID column, or from its name column when the table has no dedicated ID column, compared against the same kind of token extracted from the candidate's own heading text), falling back to fuzzy substring-containment matching against the row's name column only when no row's ID token matches; a matched row's priority cell yields P0/P1/P2/P3 (no match, or no recognized token, => priority left unset, with a warning on that preview entry) and, independently (FR-805), a dev_stage: from the dedicated status column when the table has one, or else from whatever text remains in the priority cell after stripping its matched P0-P3 token (covers merged cells like 'P0=出荷済'); status/remainder text is mapped to not_started/in_progress/implemented/verified via a fixed vocabulary (実装済・出荷済 => implemented, 部分実装 => in_progress, 検証済・verified => verified, 未実装・未定義・対象外・不要 => not_started), text this table doesn't recognize leaves dev_stage unset rather than guessing. Merge rules against the existing verification matrix: stable_id already present verbatim => action='update' (priority/description are updated from…
handoff_doc_req_scan4 of 4 parameters describedScans source files under scope_paths for discoverable links to SubItem.stable_ids, returned as ranked suggestions only — never writes impl_refs/test_refs itself (requirements-traceability P2 §5.1, `.handoff/docs/_doc.req-traceability-mcp-plan.md`; follow up a confirmed suggestion with handoff_doc_verify's set_refs action). doc_id given => only that document's SubItems are scan targets, and its own scope_paths become the default scan paths when scope_paths is omitted; doc_id omitted => every document's SubItems are targets. A scope_paths entry that does not exist on disk contributes no files rather than erroring. patterns (default: all three) — 'test_name': matches a Rust `fn test_xxx(...)` name against every target stable_id converted to its expected lowercase/underscore-joined prefix (e.g. stable_id 'C01-2.1.1.1' -> prefix 'test_c01_2_1_1_1'), confidence 0.9. 'comment': matches an `Implements:`/`Requirement:`/`Req:` comment annotation (e.g. '// Implements: C07-2.3.1.1') directly against a target stable_id, confidence 0.95. 'symbol': fuzzy-matches a scanned file's stem against a target SubItem's description (substring containment after case normalization), confidence 0.6 — deliberately below the auto_linkable threshold. ref_type on each suggestion is 'test' when the file lives under a tests/test/ path segment or has a test-shaped stem, else 'impl'. auto_linkable counts suggestions with confidence > 0.8. Returns a JSON string {suggestions:[{stable_id,match_type,match,file,line,confidence,ref_type}],total,auto_linkable}.
handoff_doc_req_impact3 of 3 parameters describedReverse-trace impact analysis: given a file path (or every file changed per `git diff HEAD --name-only` when git_diff=true), finds every requirement (a SubItem with a stable_id, across every document's verification matrix) affected by a change to that file (requirements-traceability P2 §5.2, `.handoff/docs/_doc.req-traceability-mcp-plan.md`). A SubItem is affected when the target file matches one of its impl_refs (match_type='impl_ref'), one of its test_refs (match_type='test_ref'), or — when neither ref matches — its owning document's scope_paths as a path prefix (match_type='scope_path', an indirect match). Path comparison is normalized (backslashes converted to '/', a leading './' and a trailing '/' stripped) so refs recorded with slightly different spelling still match. Exactly one of file/git_diff must effectively be used; when both are given, file takes priority. Omitting both is an error. Returns a JSON string {affected_requirements:[{stable_id,title,priority,dev_stage,match_type,doc_slug}],total}, sorted by stable_id.
handoff_trace_record7 of 7 parameters describedRecords one execution batch (a set of {item,result} pairs — e.g. one CI run or one manual verification pass) as a single new file under .handoff/runs/, and refreshes the derived runs/_latest.json cache (each item's most recent result, so trace lookups never need to rescan every run file). result must be one of pass/fail/blocked/not_run/skipped. Each result's body_hash is filled in automatically from the matching SubItem's current body_hash (never supplied by the caller) — an item stable_id that does not resolve to any SubItem is still recorded, with a warning returned rather than an error. commit defaults to `git rev-parse --short HEAD` in project_dir (empty string on failure); task_id is optional free-form linkage. test_run_id (FR-304) optionally attributes this batch to a test run created via handoff_trace_test_run(action="create") — folded additively into runs/_latest.json's by_test_run map (the existing items map is unaffected), queryable via handoff_trace_test_run(action="progress"); no existence check against the test run's own definition file. Does NOT rebuild .handoff/docs/_trace_report.json itself (t360.13: measured ~271ms at L scale when tried, vs. this op's own ~100ms budget) — call handoff_trace_report (or CLI `trace report`) afterward to refresh it; a stale _trace_report.json is detectable via its inputs fingerprint. For `cargo test --format json` JSONL output, prefer `handoff_trace_ingest(format="cargo_json")`, which parses that output and calls this tool internally per matched test. Returns a JSON string {run_id,recorded,warnings}.
handoff_trace_report5 of 5 parameters describedV-model trace derivation report: builds one derivation graph from every layer document, task<->requirement links, and the runs/_latest.json cache. Before aggregating, re-syncs any layer document whose body was edited directly since its last sync (raw-byte hash mismatch, not the lexsim content_hash) and self-repairs SubItem.task_ids drift (a no-op unless task links changed since the last full rebuild). Also (re)writes .handoff/docs/_trace_report.json (t360.13; schema_version 3 as of the requirement tree, SPEC-TREE-007 — v3 is purely additive over v2) from the same graph — schema_version, an inputs freshness fingerprint (docs_max_mtime_ns/docs_count/tasks_max_mtime_ns/tasks_count/runs_count/runs_max_id/config_fnv), plus trace_layers/layer_defs/profile/coverage/gaps/gap_counts/suspect_counts/items/tasks (always as if include_items=true and with no gap_kinds/limit filtering, independent of this call's own arguments) — unformatted JSON, only actually rewritten when its content differs from what's on disk. Each items[] entry there (and in this call's own include_items=true response) additionally carries def_hash, coverage:{horizontal,vertical}, suspect:[{kind,upstream?,task?,link_type,baseline_hash,current_hash}], reverify, approval (draft|approved), acceptance:[{id,label,kind}], implicit_of?, derived?, waivers:[{axis,reason}], from?. Schema v3 additionally carries, per item, parents[] (validated direct parents, [] for a root), parent_declared (the `- parent:` declaration verbatim, null when none), children[] (sibling order), kind (leaf|composite|decision|select), conditions? ({<parent_id>: label} — branch-edge condition labels, only for labelled edges to a decision/select parent, key omitted when empty; sibling order is already applied per parent in each parent's children[], so consumers must read children[]), order (own `- order:` or null) and subtree:{depth,parents,children,leaves,state,dev_stage,approval,excluded,suspect,progress,tasks,all_tasks} (every key always present; a node shared by several parents is included in each parent's subtree); and, top-level, tree:{roots:{<layer>:[id]},max_depth,composite_count,decision_count,select_count,leaf_count,dag_shared_count} and totals:{nodes,leaves,composites,decisions,selects,max_depth,dag_shared,state,progress} (de-duplicated across shared nodes). Tree-structure findings (parent_dangling, parent_cross_layer, tree_cycle, self_parent, empty_group, kind_conflict, plus the branch-label findings condition_missing, condition_duplicate, condition_on_non_branch, attr_unknown_parent, decision_arity, empty_branch) appear in gaps[]/gap_counts alongside the V-model kinds and are valid gap_kinds filters; they never change layer_statuses. This call's own response also carries tree and totals (and the per-item tree fields when include_items=true). The JSON Schema contract is tests/fixtures/trace_report_v3.schema.json. This write, the resync, and the self-repair are the only side effects this tool has; CLI `trace report` calls this same handler. layers restricts the 'in use' layer set for this call's own response only (overrides [trace] layers config; omit/empty falls back to config, then the project default [trace] profile's own layers if one is set, then auto-detection from which layers actually have items) — a call with a non-empty layers override does not write _trace_report.json at all, since that file always reflects the configured/profile/auto-detected layer set. gap_kinds restricts the gaps[] list to the given kinds (gap_counts always reports every kind's total, independent of this filter). limit (default 50) truncates gaps[] after kind-filtering; a truncation is noted in warnings. include_items (default false) adds an items[] array (id, layer, side, title, state, refines, verifies, tasks:[{id,role}], doc, seq, sub_item_index, priority, dev_stage, category, impl_refs, test_refs, last_run?, profile — the named profile(s) governing the item's tree, [] when none) to this call's own response, sa…
handoff_trace_slice7 of 7 parameters describedProgressive-disclosure neighborhood view of the V-model trace graph around one task or item (FR-701 — saves AI context vs. a full handoff_trace_report). Exactly one of task_id/item is required; task_id's starting set is every stable_id that task has a requirement link to (any role). An unknown task_id or item is an error (not an empty {items:[],truncated:false} result — every real item always includes at least itself, so an empty result would otherwise be misread as "this item has no links"); an existing task with no requirement links returns an empty items[] (not an error). direction (default "both"): "up" follows refines toward upper left-side items plus verifies toward the left-side item being verified; "down" follows refines toward refining children plus the verifiers that verify this item; "both" is the union of the up-only and down-only walks from the same starting set (not a single traversal that can turn around partway and pull in unrelated siblings). depth (default unlimited) caps each one-way walk; a graph cycle always stops it via its own visited set regardless of depth. expand is a list of stable_ids for which the response also includes statement (re-extracted from the item's current layer-document body — every other item gets id/layer/side/title/state/refines/verifies/tasks/profile/coverage/suspect/reverify/approval only). max_items (default 30) caps the returned items[]; when the full reachable set is larger, items[] is truncated (farthest-reached items dropped first) and truncated is true. Only ids that resolve to a real item count toward max_items — a dangling id (e.g. a task's requirement link whose owning document was deleted) is never returned and never consumes a slot. Before traversing, re-syncs any directly-edited layer document (same side effect as handoff_trace_report); that resync's warnings (e.g. removed: [ids]) are returned in warnings[]. Returns a JSON string {items:[{id,layer,side,title,state,refines,verifies,tasks:[{id,role}],profile,coverage:{horizontal,vertical},suspect:[{kind,upstream?,task?,link_type,baseline_hash,current_hash}],reverify,approval,statement?}],truncated,warnings} (coverage/suspect/reverify/approval). Requirement tree (SPEC-TREE-014): the same-layer decomposition edge `parent` is walked too — up follows an item's declared parents, down follows its children (depth and max_items apply as for every other edge). Every returned item additionally carries parents[] and children[] (its direct decomposition neighbours, both directions) and via (the edge kind it was first reached by: start | refines | verifies | parent).
handoff_trace_history3 of 3 parameters describedExecution history for one V-model trace item (VSCode FR-903's execution-history display; CLI `trace history`). Every recorded result for item across .handoff/runs/ (month subdirectories included), newest first by (executed_at, run_id). Pure read — never writes _trace_report.json or any other derived file. limit (default 20) caps the returned items[]. Returns a JSON string {items:[{run_id,executed_at,executor:{kind,id?},result,note,evidence,commit}]}.
handoff_trace_baseline10 of 10 parameters describedBaseline snapshots, their coverage-trend index, and diffs between them (FR-405 in full). action="create" (default, write): tag? (defaults to `git tag --points-at HEAD` in project_dir — the first tag when HEAD carries several, null when none; an explicit value is stored verbatim with no check against git), label?, commit?, executor_kind? ("ai" default | "human"), executor_id?. Internally regenerates .handoff/docs/_trace_report.json via the same write path handoff_trace_report uses (layer-doc resync + task_ids self-repair included — a no-op write when nothing changed since the last report, so this call is cheap when the report is already fresh and pays the same cost handoff_trace_report would when it isn't), then extracts a lightweight snapshot of each item ({id,layer,def_hash,refines,verifies,last_run,coverage,approval,suspect} — title/tasks/doc/profile and the rest are dropped) into a new .handoff/trace/baselines/<baseline_id>.json file alongside coverage_summary (per-layer horizontal/vertical CoverageCounts, same shape handoff_trace_report's own coverage field uses), gap_counts, and state_summary ({passing,failing,blocked,not_run,uncovered} tallied from the snapshot items' own state). Appends one entry to the derived .handoff/trace/baselines/_index.json cache (tmpfile->rename atomicity; rebuilt from baselines/*.json, deduped by baseline_id, whenever that cache is missing or corrupt) — handoff-vscode's t143 coverage-trend chart reads this file. Returns a JSON string {baseline_id,tag,items_count,coverage_summary,warnings}. action="list" (read-only): limit? (default 20) — the most recent entries from _index.json, newest first. Returns a JSON string {baselines:[{baseline_id,created_at,tag,label,total_items,coverage_summary}],truncated}. action="diff" (read-only): from and to (each required — a baseline_id, or the literal "current" for the on-disk _trace_report.json read as-is, never regenerated). Compares the two snapshots' items[] by id: added (only in to), removed (only in from), changed ([{id,old_hash,new_hash}] — def_hash differs on both sides), regression ([{layer,axis,old_pct,new_pct}] — a layer/axis whose coverage rate covered/(total-na-waived) — the same formula handoff_trace_report documents, so waiving or n/a-ing an item is never a regression — dropped from from to to, E20: an increase in partial at covered's expense also counts, an axis with zero items on the to side is never reported), state_changes ({<state>: delta} — only states whose count actually moved). An unresolvable from/to (unknown baseline_id, or "current" with no _trace_report.json yet) does not error — it is reported in warnings and the comparison is skipped (all fields empty). Returns a JSON string {added,removed,changed,regression,state_changes,warnings}.
handoff_trace_delta13 of 13 parameters describedChange-proposal (delta) lifecycle: create a pending bundle of ops for later human review, list/apply/reject it (FR-407). Only upsert_item/link/unlink/set ops may be proposed — record (a result) and clear_suspect (a suspect dismissal) are already-happened facts, never pending approval, and are rejected before anything is validated. action="create" (write): ops (required, non-empty array, same op shapes as handoff_trace_update), task_id? (default task for a link/unlink op that omits its own 'task' — it is copied into each such op before the delta is saved, so the stored delta applies without a call-level task_id), description?, executor_kind? ("ai" default | "human"), executor_id?. Internally runs handoff_trace_update's own dry_run=true phase-1 validation + unified-diff preview generation over these ops (nothing is written to any document) and, only if that validation succeeds, persists the ops plus their previews and each target item's current def_hash (baseline_hashes, for later staleness detection) to a new .handoff/trace/deltas/<delta_id>.json file (create_new, NFR-007). A validation failure leaves no delta file behind. Returns {delta_id,ops_count,previews:[{op_index,diff}],warnings} — warnings are the validation-time warnings of that dry run (e.g. waiver_added, unknown attrs keys, acceptance_dropped). action="list" (read-only, default): status? ("pending" default | "applied" | "rejected" | "all"), limit? (default 20). Returns the most recent matching deltas, newest first, each annotated with stale (true when any of its baseline_hashes no longer matches that item's current def_hash — computed fresh on every call, not cached). Returns {deltas:[{delta_id,created_at,status,description,ops_count,stale}],truncated}. action="apply" (write): delta_id (required, must be status="pending"), op_indices? (0-based positions within this delta's own ops array — omitted applies all of them), force? (default false — apply a stale delta anyway, with a warning, instead of erroring), executor_kind?, executor_id?. Staleness is checked first (same definition as list's stale flag, but when op_indices selects only some ops only the items those ops target are considered) and blocks the apply unless force=true. The selected ops are then applied through handoff_trace_update's own real write path (dry_run=false) — same phase-1 validation, same fixed category order, same all-or-nothing-per-category failure contract. On success this delta's status becomes "applied" unconditionally; when op_indices named only some of the ops, the rest are moved into a brand-new pending delta with their own ops/previews/baseline_hashes renumbered from 0 (remainder_delta_id) — the original delta never goes back to pending once any of its ops have been applied. Returns {applied:[{op_index,op,result}],remainder_delta_id,warnings}. action="reject" (write): delta_id (required, must be status="pending"), reason?, executor_kind?, executor_id?. Sets status to "rejected" (terminal — a rejected delta can never be applied). Returns {delta_id,status:"rejected",warnings}. See also handoff_trace_update's own propose argument, which runs this same create path from inside a single trace_update call.
handoff_trace_ingest10 of 10 parameters describedIngests a cargo or JUnit XML test run and records matched results against V-model trace items (FR-306): one aggregated runs/<run_id>.json entry per layer item (any fail wins, all-skipped wins next, else pass across every test matched to that item), one test_refs label update per matched test for layer-less items (the legacy convention). format="cargo_json" expects libtest's JSON-per-line output; getting that output requires an unstable flag: `cargo +nightly test -- -Z unstable-options --format json`, or on stable `RUSTC_BOOTSTRAP=1 cargo test -- -Z unstable-options --format json` (there is no stable `cargo test --format json`). format="junit_xml" is recommended instead: `cargo nextest run` with a `[profile.<name>.junit]` section writes a JUnit XML report with no unstable flags needed. Matching (3 stages, tried in priority order): (1) exact match against one of an item's declared `- test: <value>` lines, (2) a `::`-boundary suffix match against one (e.g. an item's `test: lock::lock_after_5` matches output test `tests::e2e::lock::lock_after_5`), (3) the stable_id->test-name-prefix convention (stable_id lowercased, runs of non-alphanumerics -> `_`, prefixed `test_`: REQ-001 -> `test_req_001`; compared against the last `::` segment of the test name, and the prefix must end at a word boundary — the name ends there or continues with a non-alphanumeric character — so REQ-1 matches `test_req_1` and `test_req_1_x` but not `test_req_10`). Stage 3 is used ONLY for an item with no declared `test` value (every layer-less item, and a layer item with no `test` attribute); an item with at least one declared `test` value is matched by stages 1-2 alone, never by the prefix convention. An item with at least one declared `test` value is only recorded when this ingestion's output covers *every* one of its declared values — a value with zero matches is reported in missing_refs instead, and that item is not recorded at all this call (a partial run must never look like a fuller not_run/pass/fail overwrite). Exactly one of output/output_file is required (output takes priority when both given). dry_run (default false) parses and matches without writing anything. commit defaults to `git rev-parse --short HEAD`; task_id is optional free-form linkage; executor_kind defaults to "ai". test_run_id (FR-304) optionally attributes this ingestion's run to a test run created via handoff_trace_test_run(action="create") — same additive runs/_latest.json by_test_run wiring handoff_trace_record's own test_run_id argument has. Returns a JSON string {run_id?,recorded,matched:[{item,result,tests:[string]}],missing_refs:[{item,test}],unmatched_tests_count,warnings,dry_run}.
handoff_trace_scaffold6 of 6 parameters describedGenerates one verification-layer item per acceptance-criteria bullet of a source (left-side) item (FR-305). Exactly one of items ([stable_id, ...]) or doc (a document slug/id — every item in it with an acceptance-criteria block) selects the source items; target_doc (required, a layer document's slug or id) is where generated items are appended. Each acceptance-criteria bullet becomes one new item: id = "<target layer's default id prefix>-<source id>-<AC number>" (e.g. "AT-REQ-003-1" from REQ-003's AC1, verifying an `acceptance` target_doc), body attrs `verifies: <source id>`, `priority` (inherited from the source), `from: <source id>#<AC label>`, `method` (rule-based: `auto` when the source item has linked test_refs, else `manual`), `environment: (TBD)`. The body follows an ISO 29119 test-specification template: 検証目的 / 前提条件 (TBD) / 手順 / 期待結果 plus result fields (実結果 / 判定: pending / エビデンス). A `gwt`-kind AC (Given...When...Then) splits into 手順 (steps, the Given/When clauses) and 期待結果 (expected result, the Then clause, also the heading title); an `ears`/`text`-kind AC has no distinguishable steps (手順: `1. (TBD)`, a fill-in placeholder), uses its full text as 期待結果, and its first 40 characters as the heading title. Idempotent: an AC that already has a scaffolded item anywhere in the project (a `from` value equal to `<source id>#<AC label>`) is skipped (reported in skipped, not regenerated) and does not count against limit. An id collision with any existing stable_id in the project is avoided by appending a single lowercase-letter suffix (`AT-REQ-003-1a`, `...1b`, ...; a warning is returned if all 26 are already taken). mode="preview" (default) computes generated/skipped without writing; mode="apply" appends the rendered Markdown to target_doc's body in one `doc_save(append_body=...)` call (which runs the real parser + layer sync), skipping the write entirely when there is nothing to generate. limit (default 20) caps how many new items are generated per call (skipped ACs don't count). If a source AC already has an implicit acceptance-verification item (a minimal-profile document's auto-materialized `<source id>#<AC label>` SubItem) with a recorded run, a warning notes that the run is not carried over to the newly scaffolded item. Returns a JSON string {target_doc,mode,applied,generated:[{id,from,title}],skipped:[{ac,existing}],warnings}. Requirement tree (SPEC-TREE-014): sources are leaves and composites/decisions with their own integrated acceptance criteria; a composite without any gets a warning pointing at its leaves.
handoff_trace_suspect14 of 14 parameters describedDerives and manages the 4 suspect kinds a V-model link/task/result/code can fall into when its upstream definition changed since it was baselined (a `code` suspect: a file named by the item's impl_refs/test_refs changed since its content_hash was recorded — it has no baseline to clear, re-set the refs via handoff_trace_update `set` to re-record the hash, and a passing verifier carrying one is listed in reverify). action="list" (default, read-only): {suspects:[{kind:"link"|"task"|"result",item,upstream?,task?,link_type?,baseline_hash,current_hash}],counts:{link,task,result},unbaselined:{links,tasks},reverify:[stable_id,...],truncated}. `link` = a child's refines/verifies reference whose baseline no longer matches the upstream's current def_hash (or ac_hash for an `X#ACn` sub-reference); `task` = a task's requirement link whose baseline_hash no longer matches the linked item's current def_hash; `result` = a verification item's latest recorded pass whose recorded def_hash (or body_hash, for an older run) no longer matches. `unbaselined` counts references/links with no baseline yet (never suspects themselves — see action="baseline"). `reverify` lists Passing verification items whose own result is suspect or one of whose verifies links is suspect (does not change `state`). Filters: item, task_id, kinds (subset of link/task/result), layers, limit (default 50). action="clear": targets (required, array — each entry is one of {item,upstream} exact link, {item} all of that item's suspect links, {upstream} every link pointing at that upstream (bulk), {task_id,item?} task link(s), {layer} every suspect in that layer, {result:item} that item's result suspect), reason (required), evidence? ({run_id?,commit?,note?}), executor_kind (default "ai"), executor_id?. Moves each selected suspect's baseline to the current hash (a link's SubItem.link_baselines entry, a task's TaskLink.baseline_hash) — a result clear instead records one new carried-forward runs/<run_id>.json entry (reusing the last result verbatim against the item's current hashes; the authority for results stays runs-only). Writes one audit file per call to .handoff/trace/clears/<id>.json. Returns {cleared:{links,tasks,results},clear_id,baseline_suggestions,warnings} — baseline_suggestions is suggest-only (nothing is written): one entry per cleared task whose schedule has dates, {task_id,current_start,current_due,baseline_start?,baseline_due?,action:"set_recommended"(no baseline yet)|"update_recommended"(baseline differs from the schedule)|"manual_baseline_detected"(differing baseline on a pinned task, with a warning — not to be overwritten)}; apply one via handoff_update_task(schedule). action="baseline": migration helper for links/tasks that have no baseline at all — dry_run (default true) previews the count; scope? ({doc} or {layer}, omitted = whole project) restricts which unbaselined references are considered. Never touches an already-suspect link. Returns {baselined:{links,tasks,results:0},dry_run,warnings}.
handoff_trace_impact10 of 10 parameters describedRead-only impact analysis for a proposed change (FR-404) — never writes anything, including _trace_report.json. Exactly one entry point is required: (1) item (+ optional proposed or proposed_file, a Markdown block that must contain that item's own heading line — a block without it is treated as "assume changed" with a warning) — parses the proposed text the same way a real layer sync would to get a hypothetical new def_hash/ac_hash; omitting both proposed and proposed_file means "assume changed" (a sentinel hash that reads as different from every real baseline, since no concrete new hash is known). (2) doc (+ required proposed_body or proposed_body_file, a full layer-document body) — every item common to both the proposed parse and the current corpus whose def_hash/ac_hash would change is treated the same way, for the whole document at once; any id the target document currently owns (including its materialized implicit-acceptance items) that the proposed body no longer defines at all is reported as a deletion instead (see `removed` below), for item mode scoped to just that one item and its own acceptance criteria. (3) file — the original req_impact entry point (shares its file-matching core with handoff_doc_req_impact): every requirement whose impl_refs/test_refs/scope_paths match this file is treated as "implementation changed" (no def_hash simulation, so would_suspect stays empty; only rerun_candidates is populated). (4) git_diff: true — same as file, but against every path `git diff HEAD --name-only` reports changed. Returns a JSON string {changed:[ids],removed:[{id,downstream_refs:[{child,type}],tasks:[ids]}],would_suspect:{links:[{child,upstream,type}],tasks:[{task,item}]},rerun_candidates:[ids],potential:[{id,depth}],truncated,warnings} — would_suspect only ever reports a downstream reference/task link that already has a recorded baseline (an unbaselined one is never guessed at); removed lists an id the proposal deletes outright, with its direct downstream references/task links (these would become dangling once the proposal lands, never suspect — there is no current hash left on the removed side to compare a baseline against; also echoed into warnings); rerun_candidates is every changed id's own verifying children (any verifies edge to it, regardless of baseline) plus a changed id that is itself a verification item; potential is a breadth-first walk over the same refines/verifies reverse-edge index starting from changed, reporting only depth >= 2 ("if the intermediate item also changed" ripple, informational only — suspects never actually propagate past one hop), capped by limit (default 50, truncated is true when more were reachable). Requirement tree (SPEC-TREE-013): tree_children_affected:[{parent, change:'changed'|'removed', children:[ids], would_orphan?:[ids]}] lists the same-layer decomposition children of every changed or removed item (a decomposition is not a hashed link, so children never become suspect — they are what to re-read); for a removed parent would_orphan is the subset left with no surviving parent (a DAG child with another remaining parent is not orphaned). Empty when no item has decomposition children.
handoff_trace_lint10 of 10 parameters describedRead-only lint over the whole trace graph (FR-503/801; FR-504 added the quality rules and action="quality_prompt") — action="lint" and "quality_prompt" never write anything (the one write is action="nfr_check", below), E6 (in-memory-only resync of a directly-edited layer document, runs::load_latest_readonly, task_ids resolved from the task side without self-repair). action? ("lint" default | "quality_prompt" | "nfr_check"). action="nfr_check" (SPEC-RQ-001, ISO/IEC 25010 NFR checklist): classifies the selected requirements (items? = explicit stable_ids, default every requirement-layer item) into the 8 characteristics performance_efficiency / compatibility / usability / reliability / security / maintainability / portability / functional_suitability — an NFR-prefixed id is classified from its own segments (NFR-SECURITY-001, NFR-PERF-002) then from keywords in its text, any other item counts as functional_suitability, an NFR item that matches nothing is listed in unclassified. review? ({<category>: reviewed|applicable|not_applicable|not_reviewed}) records a judgement made from the prompt templates; recorded decisions persist across calls (not_reviewed clears one), otherwise status is derived: applicable when the category has items, else not_reviewed. Returns {categories:[{name,status,items:[stable_id],prompt_template (with a {text} placeholder),context}],unclassified,warnings} and — the only write this tool makes — merges {categories:[{name,status,items}],unclassified,scope,reviews} into .handoff/docs/_trace_report.json as `nfr_coverage` (the report is rebuilt first if absent; later `trace report` rebuilds carry nfr_coverage over). Unlike the other actions it takes the write lock for that merge. action="lint": Built-in rules (default severity in parens, overridable per id via config.toml's [trace.lint.rules] = "error"|"warning"|"info"|"off"): structural — unverified/unrefined/orphan/task_unlinked (warning), dangling/invalid_link/cycle/duplicate_id (error); change — suspect_link/suspect_task/stale_result/code_drift (warning; code_drift = a file named by an item's impl_refs/test_refs changed since its content_hash was recorded; refs without a recorded hash never fire — e.g. stamped before the file existed, body-declared test_refs, unreadable files; hashes are recorded only by trace_update set and doc_verify set_refs), unbaselined (info); tailoring — waiver_on_na/unlabeled_acceptance/invalid_waiver/unknown_acceptance_ref/missing_profile_layer (warning; missing_profile_layer = an item's effective profile default_needs requires a layer such as basic_spec/system_test/detailed_spec/unit_test that has no refining/verifying item for it, LINT-W030; low_confidence_spec = a basic_spec/detailed_spec item whose title or statement still carries the spec-writer's `(要確認)` low-confidence marker), redundant_waiver/layer_outside_profile (info); drift (FR-801) — unsynced_body/task_link_dangling/attribute_after_body (warning), task_ids_drift/orphaned_legacy/orphan_run/id_like_heading (info); tasks outside traceability — task_orphan (warning; a task with no requirement-type task_links entry, whatever its status; not reported: a skipped task, a task labelled `no-trace`, a parent task whose every leaf below is linked/no-trace/skipped, and any task of a project with no layer document; each finding also carries task_id, title and suggested_action); coverage gating (FR-202, info) — unwanted_coverage (a verifier whose layer is outside the item's effective needs — its own `- needs:` line or, when it has none, the project default profile's default_needs entry for its layer; the verifier is excluded from the item's coverage, so widen needs or move the verifier); quality (FR-504, info) — ambiguous_word (title matches a known vague term list, Japanese and English), missing_acceptance (a requirement-layer item with no acceptance-criteria block), passive_voice_hint (title matches a Japanese 「される」/「られる」 marker or an English "is/are/was/were + past participle" pattern…
handoff_trace_matrix7 of 7 parameters describedRead-only (E6, same fully-read-only load handoff_trace_lint/handoff_trace_impact use — in-memory-only layer-doc resync, runs::load_latest_readonly, task_ids resolved from the task side without self-repair) flat export of the whole trace graph as a CSV or Markdown table (FR-505) — handoff-vscode's matrix-export feature (t135) calls this instead of reimplementing CSV/Markdown generation itself (NFR-005). format (required): "markdown" | "csv". shape (default "tree"): "tree" is one row per top-level (root_layer) left-side item — INV-614's 'トレース表(行 = V字1本)' — with columns = every currently in-use layer (left side top to bottom, then right side top to bottom; a layer no item in the project uses gets no column) populated with that row's reachable descendants (refining children, and verifiers of anything in the row), plus a tasks column (every task with a requirement link to any id in the row, omit via include_tasks=false), then state (the root item's own aggregate TraceGraph state, already folding in every descendant) and suspect (the count of graph suspects whose relevant item is in the row). "edges" is one row per resolved refines/verifies link in the whole graph — {from,to,link_type,from_layer,to_layer,state (the from item's own state),suspect (true iff a link-kind suspect matches this exact {item: from, link_type, upstream->to})} — for import into an external tool; a dangling/invalid-level reference never appears here (handoff_trace_lint's dangling/invalid_link gaps cover those). root_layer (tree only, default: the shallowest-level left-side layer currently in use) must name a registered layer id; naming one no item in the project uses is not an error, it just yields zero rows. layers? restricts/reorders the column set to this list, intersected with (and reordered to match) the canonical in-use order — any entry that is unknown or not currently in use is dropped with a warning, never an error. A cell holding more than one id joins them with '; ' in CSV, '<br>' in Markdown (also how a literal embedded newline renders); CSV is RFC 4180 (every cell quoted, no BOM, LF line endings), Markdown escapes a literal '|'. output_file? is a path relative to the project directory (not .handoff/) to write the rendered content to instead of returning it inline — an absolute path or one that would escape the project directory (a '..' component) is rejected; this is the only write this otherwise fully read-only tool ever makes. Returns a JSON string {format,shape,root_layer? (tree only),columns,rows (row count),content? (omitted when output_file was given),output_file?,warnings}. Requirement tree (SPEC-TREE-014): shape=edges also lists the same-layer decomposition edges as rows with link_type 'parent' (child -> parent); when at least one parent row carries a branch label (the child's condition for a decision/select parent), a trailing 'condition' column is appended to every row (the label on labelled parent rows, empty elsewhere), otherwise the columns are unchanged. shape=tree, when the root layer has any parent edges, becomes a depth-first tree: a leading 'item' column holds the id indented two spaces per depth (Markdown output keeps the indent as ), an id with several parents is starred ('REQ-A2*') and listed under each parent but expanded only once, and a 'parents' column lists each row's direct parents; a root layer without parent edges keeps the previous one-row-per-item shape and columns unchanged.
handoff_trace_next6 of 6 parameters describedRead-only (E6, same fully-read-only load handoff_trace_lint/handoff_trace_matrix use — in-memory-only layer-doc resync, runs::load_latest_readonly, task_ids resolved from the task side without self-repair) ranking of "what to do next" across the whole trace graph into 11 kinds (FR-703; FR-307 added manual_pending; FR-204 added relink_candidate; REQ-LAG-006 added update_drifted_spec), each rank's detection rule and suggested follow-up call: 1 fix_failing (a verification item whose state is failing/blocked -> handoff_trace_slice then fix then handoff_trace_record), 2 review_suspect (an item with a suspect upstream link -> handoff_trace_impact then fix the body or handoff_trace_suspect clear), 3 update_drifted_spec (a left-side item whose impl_refs/test_refs files changed since their recorded content_hash, i.e. the code_drift lint finding -> handoff_trace_update upsert_item dry_run on the item's own document to revise the spec, then re-record its refs with a `set` op; the action lists plan_update_needed [{doc_id, stable_id, current_dev_stage}] when a task implementing the item is also linked to plan-document items; its right-side verifiers, and a drifted right-side item itself, are proposed as rerun; sorts before rerun; a proposal only, no task is ever created) and 3 rerun (a reverify or never-run verifier whose verified target is already implemented or beyond -> run the test then handoff_trace_ingest/handoff_trace_record) and manual_pending sharing the same rank 3 (an assignee-bearing item whose method is manual/visual/review and whose latest result is not_run -> handoff_trace_record), 4 write_verification (a left-side item WITH acceptance criteria whose horizontal coverage is uncovered or partial -> handoff_trace_scaffold into the pair layer's document, or handoff_doc_save creating that layer's first document when none exists; an item without acceptance criteria has nothing to scaffold and gets no candidate), 5 refine (a left-side item whose vertical coverage is uncovered or partial -> handoff_trace_update upsert_item dry_run adding a refining child in the next deeper layer's document, or handoff_doc_save creating that layer's first document; none for the deepest left layer), 6 create_task (a not_started left-side item with no implementing task yet whose vertical coverage is not already covered through its refining children -> handoff_trace_tasks), 7 fix_link (a dangling/invalid_link/cycle/duplicate_id/orphan structural gap -> fix the body), 8 baseline (an unbaselined refines/verifies reference -> handoff_trace_suspect baseline with dry_run=false, scoped to the item's document), 9 relink_candidate (a verifier or task still linked straight to an upper-layer item that a deeper-layer item now refines -> handoff_trace_update upsert_item dry_run rewriting verifies, or handoff_update_task rewriting requirement_ids; never proposes a link the verifier's level could not legally hold). Every suggest.arguments is valid against the named tool's input schema as returned (a record suggestion for a by-hand verification — manual_pending, or a rerun of an implicit/manual item — carries result not_run as a placeholder that MUST be replaced with the real outcome before calling: it is not a no-op, recorded as-is it writes a not_run run that supersedes a stale pass and clears its suspect). Within the same rank, ordering is deterministic: item priority (P0 before P1 before P2 before P3, unknown/missing last) -> the item's own layer level (shallower/upper first) -> stable_id natural order. task_id? narrows the candidate set to only that task's own requirement-linked items (same starting-set rule handoff_trace_slice's task_id branch uses). layers?[] restricts to items whose own effective layer is one of these, applied before ranking (never lets an out-of-scope item's candidate displace an in-scope one before limit truncation). assignee? restricts to items whose own SubItem.assignee matches exactly, applied the same way as layers?[]. kinds?[] restricts…
handoff_trace_tree7 of 7 parameters describedRead-only (E6, same fully-read-only load handoff_trace_lint/handoff_trace_next use) nested view of the requirement tree (decomposition DAG, SPEC-TREE-008). Built from the same tree index and sub-tree roll-up as handoff_trace_report(include_items) / _trace_report.json (schema v3), so the numbers always agree. root (an item id; an unknown id is an error) selects one node's tree; scope (an id prefix, e.g. "REQ-AUTH-") selects every item whose id starts with it, with the matching items that have no matching parent as roots; root and scope are mutually exclusive; with neither, the roots of every layer are returned (in-use layers first). layer limits the roots to one layer (an unknown layer is an error). depth (integer >= 0, default unlimited, 0 = roots only) bounds the expansion: a node below the limit keeps has_children=true with children=null. A node with several parents (DAG) is expanded at its first occurrence only; later occurrences have has_children=true and children=null (and are counted in totals.truncated_subtrees). filter keeps the matching nodes plus their ancestors (conditions are ANDed; each node's subtree roll-up is still the unfiltered value): state[] (passing|failing|blocked|not_run|uncovered, the node's own state), priority[] (P0..P3), suspect (true = only nodes with a suspect, false = only without), gaps_only (true = only nodes whose own state is uncovered or failing, that carry a suspect, or that have a tree-structure finding such as parent_dangling; not_run and blocked nodes are not gaps), kind[] (leaf|composite|decision|select). fields[] (own.<key> | subtree.<key>) trims each node's own / subtree objects to the listed keys; id, kind, parents, has_children, children and the branch labels condition/conditions are always returned, title/layer/doc/seq/order/priority are returned only when fields is omitted. Returns {roots:[{id,title,kind (leaf|composite|decision|select),layer,doc,seq,order,priority,condition? (the branch label of the edge from the parent this node is emitted under; omitted for roots and unlabelled edges),conditions? ({<parent_id>: label} for every labelled edge to a decision/select parent; omitted when empty),own:{state,dev_stage,approval,coverage:{horizontal,vertical},suspect (string[]: the distinct kinds link|task|result of the node's suspects, [] when none),tasks,acceptance_criteria (integer: the node's own acceptance-criteria count)},subtree:{depth,parents,children,leaves,state,dev_stage,approval,excluded,suspect,progress,tasks,all_tasks},parents,has_children,children:[...]|null}],totals:{nodes,leaves,composites,decisions,selects,max_depth,dag_shared,truncated_subtrees} (unique nodes shown),warnings}. An empty tree returns roots=[] with the DIAG-T001/T002/T003 diagnostics in warnings. Sibling order already reflects each parent's own order@ values — read children[] for order. CLI text output renders a node as `ID[*] [label] title (kind) ...`. CLI: handoff-mcp trace tree [--root ID | --scope PREFIX] [--depth N] [--layer L] [--filter-state S,..] [--filter-priority P,..] [--filter-suspect] [--gaps-only] [--filter-kind K,..] [--fields F,..] [--format json|text].
handoff_trace_test_run15 of 15 parameters describedTest run definitions and dynamically-computed progress (FR-304). action="create" (default, write): scope ({layers?: [layer id, ...], kinds?: [one of fix_failing, review_suspect, update_drifted_spec, rerun, manual_pending, write_verification, refine, create_task, fix_link, baseline, relink_candidate — same vocabulary as handoff_trace_next's own kinds filter], assignee?, items?: [stable_id, ...] — name the target items directly; combined with the other keys it narrows them, an id outside the matched set is skipped with a warning}), label?. Unknown scope keys and unknown top-level arguments are rejected. A scope that matches no items is refused (no empty campaign is created). Enumerates target_items the same way handoff_trace_next would for this scope: when scope.kinds is given, candidates are every item handoff_trace_next's derivation would surface for those kinds (needs the same full trace-graph build handoff_trace_next itself pays, PR-7 class); when scope.kinds is omitted, candidates are simply every layer item whose effective layer/assignee match scope.layers/scope.assignee (no graph build at all, PR-4 class); scope.items then keeps only the named ids. Persists the enumerated set, plus a generated test_run_id, to a new .handoff/trace/test_runs/<test_run_id>.json definition file (never overwritten, NFR-007). Returns a JSON string {test_run_id,target_items:[ids],total_target_count,warnings}. action="list" (read-only): limit? (default 20) — every test_runs/*.json definition, newest first. Returns a JSON string {test_runs:[{test_run_id,created_at,label,total_target_count}],truncated}. action="progress" (read-only): test_run_id (required) — filters runs/_latest.json's by_test_run[test_run_id] map (populated by handoff_trace_record/handoff_trace_ingest's own test_run_id argument) against the definition's own target_items and dynamically tallies progress; a target item with no recorded result against this test run counts as not_run (never cached, always recomputed from runs/*.json). An unknown test_run_id is an error. Returns a JSON string {test_run_id,total,executed,pass,fail,blocked,skipped,not_run,progress_pct,remaining:[ids],campaign_status,checklist_progress,warnings}. VERIFICATION CAMPAIGN (FR-512/SPEC-512): a test run is also a campaign with a checklist, campaign_status (draft -> in_progress -> completed -> approved) and progress {total,checked,pass,fail,blocked,waived,pending}. action="create" auto-generates one pending checklist row per target item ({item_id, acceptance_text (the item's description), result, evidence, note, verified_by, verified_at}) unless auto_checklist=false, in which case the checklist starts empty and a row is created the first time a target is checked (record_check/add_evidence), and complete requires every target to have been checked; its response also carries campaign_status and checklist_count, and list entries carry campaign_status and progress. action="get" (read-only): test_run_id — the full record incl. checklist. action="record_check" (write): test_run_id, item_id, result (pending|pass|fail|blocked|waived), note?, verified_by? (defaults to the calling agent), evidence? [{path,type,caption}] (appended; path must be non-empty and contain no '..'); the first non-pending check moves draft to in_progress. action="add_evidence" (write): test_run_id, item_id, evidence {path,type,caption} — appended without changing the verdict. action="set_status" (write): test_run_id, status — allowed transitions draft->in_progress, in_progress->completed (checklist must be non-empty with no pending item; fail/blocked rows are allowed — completed means every row was executed), completed->in_progress (reopen), completed->approved (approved_by required, and no fail/blocked row may remain: re-run it after reopening, mark it waived, or pass accept_failures=true to sign the failures off knowingly, e.g. for an inspection certificate that records a failed inspection); approved is terminal; draft is the initial state only a…
handoff_trace_propose7 of 7 parameters describedRead-only suggestion of existing V-model items that may already cover a task, plus a ready-to-review Markdown template for a new one, sized to the project's applicable profile (FR-1004). Exactly one of task_id (loads that task's own title/notes/scope_paths) or title (+ optional notes, for a task that doesn't exist yet) is required. candidates: every persisted item's stable_id/title (SubItem.description)/layer, scored by a lexical+semantic blend (the same one handoff_memory_save's near-duplicate detection uses) between the query text (title, or title+notes) and each item's own title — no document body is read, sorted by score descending, capped at limit (default 5). proposal: the applicable layer set and implicit_acceptance is resolved [trace] layers (explicit config) > the project default [trace] profile > a 'standard'-shaped fallback when neither is configured (each fallback/assumption is reported in warnings, never silent) — the new item's layer is the deepest left-side (definition) layer in that set. When implicit_acceptance is true (a minimal-shaped profile), the template is one item at that layer with an inline "Acceptance criteria:" block (its own layer sync auto-materializes the verification item per criterion) — e.g. a minimal profile proposes one REQ- item. Otherwise the template is that item plus its paired verification-layer item (an explicit `- layer: <id>` override lets both live in the one proposed document even though its own default layer is the left one) — e.g. a standard profile proposes a SPEC- item paired with an ST- one. IDs are '<prefix>-<max existing number for that prefix project-wide, +1>', zero-padded to 3 digits; the prefix is the layer's default id prefix unless prefix is given (e.g. prefix: "CART" proposes the next free CART-nnn; it must be one of the target layer's registered prefixes — built-in defaults plus [trace.id_prefixes] — otherwise the call fails listing the allowed ones; ignored with a warning when parent is given). Every fill-in slot (statement, acceptance bullet, branch label) is the language-neutral marker TBD — replace it; the paired verification item is titled '<title> [<verification layer id>]'. doc is the layer document (matching the new item's target layer) whose scope_paths overlaps the task's own scope_paths (exact match or directory-prefix overlap, same classification handoff_claim_task's scope-conflict advisory uses); when none exists (including the title-only input, which has no task scope_paths to compare against), doc is instead a suggested (never created) new slug derived from the layer id and the query title, flagged in warnings. With parent (requirement tree, SPEC-TREE-011) the new item is instead a same-layer child of that item: id '<parent>-<next sibling number>', layer = the parent's layer, '- parent: <parent>' in the template; when the parent is a decision/select the template carries a '- condition: TBD' line (replace it with a label unique among the parent's children: yes/no for a decision, a case name or the reserved 'default' for a select) and a warning says so. Creation is out of scope for this tool — apply the proposed markdown yourself via handoff_doc_save/handoff_doc_update_section, or via handoff_trace_update's upsert_item op, only after the requester has reviewed it. Returns a JSON string {candidates:[{id,title,layer,score}],proposal:{profile,doc,markdown,next_ids}|null,warnings} — proposal is null when no left-side (definition) layer or reciprocal pair could be resolved for the applicable profile.
handoff_trace_tasks8 of 8 parameters describedGenerates one task per V-model item still missing the task role it needs (FR-605). Target selection: a left-side (definition) item with no task yet holding an `implements` link to it, or a right-side (verification) item with no task yet holding an `executes` link to it AND whose latest recorded result (runs/_latest.json) is not `"pass"` (an already-passing verifier needs no task). An item that already has a task holding the role this call would otherwise generate is idempotent — reported in `skipped`, never regenerated. Exactly one of items ([stable_id, ...], explicit targets — any id not found in the project is reported in warnings) or select ({layers?: [layer id, ...], gap_kinds?: [one of unverified/unrefined/orphan/dangling/invalid_link/cycle/duplicate_id/task_unlinked], dev_stage?: "not_started"|"in_progress"|"implemented"|"tested"|"verified"}) restricts the scan; omitting both scans every item in the project. Each generated task: title `"<stable_id> <item title>"` (SubItem.description), a `requirement_ids`/`requirement_roles` reverse link to the source item (role implements/executes, same inference `handoff_update_task`'s own create path uses when no explicit role is given), `labels: ["layer:<effective layer id>"]`, `scope_paths` copied from the item's owning document (not the item itself) — done_criteria are deliberately never copied (FR-603). parent_id (optional) makes every generated task a child of that task. estimate_hours is required when mode="apply" and [settings] require_estimate_hours is enabled project-wide (every generated task starts in status "todo", which handoff_update_task's own per-task estimate rule exempts, so this tool enforces its own upfront whole-batch requirement instead of silently creating unestimated tasks); when given, it is applied to every task this call creates. mode="preview" (default) computes without writing; mode="apply" creates the tasks via handoff_update_task's own shared create path (same validation: status/priority, done-guard pre-check, dependency validation, require_estimate_hours). limit (default 20) caps the number of generated/planned entries (skipped items don't count) — scanning is read-only (E6: in-memory-only layer-doc resync, runs::load_latest_readonly, task_ids resolved from the task side without self-repair), the only write path is the task creation itself. Returns a JSON string {mode,created|planned:[{task_id? (apply only),item,role,title}],skipped:[{item,role,existing}],warnings}. Requirement tree (SPEC-TREE-014): an implements task is only generated for a leaf or for a composite/decision with its own integrated acceptance criteria; a composite without them is left out (reported in warnings — create the tasks on its leaves instead), also when named in items. GUI verification (REQ-GUI-REQ-002): an item carrying a `- mock:` attribute additionally yields a separate VRT task titled `"[VRT] <stable_id> <item title>"` (labels vrt + gui-verification, no requirement link, entry `kind: "vrt"`, role `vrt`) with three fixed done_criteria (golden screenshot captured, VRT PASS, AI visual verification PASS); it is idempotent on its own full title. default_milestone (REQ-MS-PIPE-003, optional string) sets schedule.milestone on every generated task (ordinary and VRT) whose item has no effective milestone of its own — the item's `- milestone:` attribute, else its document's milestone, always wins; omitted: no milestone.
handoff_trace_update9 of 9 parameters describedBulk-mutation entry point over 7 op kinds in one call (FR-702/FR-601's remainder). Input: ops (required, non-empty array — each entry has an 'op' field naming one of upsert_item/link/unlink/set/record/clear_suspect/set_layer_status, see below), task_id? (default task: a link/unlink op that omits its own 'task' uses it; it is also the task the merged record run is linked to — record ops have no task of their own; upsert_item/set/set_layer_status ignore it, and clear_suspect never uses it as a default — that op's own task_id is a clear-target selector; with propose=true it is expanded into the delta's link/unlink ops), dry_run? (default false), executor_kind? ('ai' default | 'human'), executor_id?, commit? (used by record ops). E15 atomicity: every op — input shape, enum values (role: implements/executes, priority: P0-P3, result, dev_stage, approval), and every referential lookup this op kind commits to (document existence, upsert_item's after target and its own id resolving to a real item once rendered, link/unlink's item and task, set's item) — is validated, in ops' input order, before anything is written; an item lookup is checked against the union of the pre-call corpus and every id an earlier upsert_item op in the same call already planned, so a link/set op can legally target an item an earlier op in the same call creates. record's item is deliberately not existence-checked (it is forwarded to handoff_trace_record, which already records an unresolvable item with a warning rather than rejecting it — trace_update does not impose a stricter policy than the single-op tool). If any op fails validation, nothing is written and the response's failed names that op (by its 0-based position in the input ops array, not execution order). Writes then run in the fixed category order §4.8/E15 specify regardless of input order — 本文 (upsert_item) -> リンク (link/unlink) -> 実行時データ (set) -> 記録 (record) -> 解除 (clear_suspect) — and a write-time failure (rare: an IO/optimistic-lock error) stops before the next category, returning applied for whatever already landed on disk (this tool never attempts a cross-file rollback, E15: 'ファイルをまたぐトランザクションにはしない'). upsert_item {doc, id, title?, statement?, acceptance?: [{label,text}], attrs?: {layer,refines,verifies,parent,order,"order@<parent_id>",kind,condition,"condition@<parent_id>",priority,method,test,rationale,derived,"waive-verify","waive-refine",needs,assignee,from,environment,milestone,mock,golden,viewport,capture_method}, after?}: rewrites one item in a layer document's body (§2.2 notation, rendered via the same src/storage/docs/layer_render.rs trace_scaffold uses). An existing item (matched by id in doc's current body) has only the parts actually given replaced — omitted title/statement/acceptance/attrs sub-keys keep the item's current value (attrs is merged key-by-key, not replaced as a whole block, so an existing rationale/derived/waiver/assignee/needs attribute the op doesn't mention survives untouched; attrs.assignee = single-line roster key and attrs.needs = comma-separated layer ids or an array (an empty array = explicit 'no coverage needed'), both cleared by "" or null; an attrs key outside the list above is ignored with an 'unknown attrs key' warning). An op-level key the op kind does not read is likewise ignored with an 'unknown key' warning (ops[i]: unknown key '...' on a <op> op was ignored). acceptance, when given, REPLACES the item's whole criteria list (not a label-wise merge): every existing criterion missing from it is deleted, and an 'acceptance_dropped: ...' warning names each dropped label plus any verifier of <id>#<label> (with its latest recorded result) that is left dangling — re-send every criterion to keep; a malformed acceptance entry (not {label,text} strings) fails validation; requirement-tree attrs: parent = same-layer parent id(s), comma-separated string or array (several parents make a DAG; "" clears), order = non-negative integer sibling order, order@<parent_id> = per-pa…
handoff_task_checklist3 of 3 parameters describedaction="view" (default, and only supported action — action="generate" was removed; use handoff_trace_scaffold instead): pure-view aggregation of a task's done_criteria and its linked documents' verification matrices. No new data is written — reads task_links (link_type="doc") and each linked document's verification matrix, computed fresh on every call. Returns {task_id,title,no_linked_docs:true,trace} as a fast-path response when the task has no linked documents. Otherwise returns {task_id,title,no_linked_docs:false,done_criteria:{items:[…],progress:{…}},verification_coverage:{documents:[{doc_id,slug,title,doc_type,items:[{fragment_seq,heading,status,stale,visual_state,impl_refs,test_refs}],progress:{…}}],overall:{…}},combined_readiness:{done_criteria_met,verification_complete,ready,blockers:[{type:"criteria"|"verification",…}]},suggested_actions:[…],trace}. trace is {layers,blockers} from this task's requirement-type task_links (independent of the doc-type links above), or null when it has none — same shape and read-only (E6) contract as handoff_get_task's trace field. Each item's visual_state is computed in priority order stale > skipped > verified > implemented (pending+impl_refs+test_refs) > in_progress (pending+impl_refs only) > untouched.
handoff_claim_task4 of 4 parameters describedClaim a task for exclusive work, guarded by a cross-process file lock (flock). Fails if the task is already claimed by another agent with a non-expired lease; an expired lease is silently taken over. A todo/blocked task moves to in_progress. Returns the updated task JSON, including the new lock. If the claimed task's scope_paths overlap another active (in_progress, locked) task's scope_paths, an advisory 'warnings' array is included ({level:"info"|"warn", message}) — same-directory overlap is 'info', same-file overlap is 'warn'. Warnings never block the claim.
handoff_release_task4 of 4 parameters describedRelease a task previously claimed by this agent, clearing its lock and reverting its status. Fails if the task's lock is held by a different agent.
handoff_list_agents3 of 3 parameters describedList registered agents across worktrees (`.handoff/agents/`), with freshly-computed active/stale/disconnected status based on heartbeat age.
handoff_review_list4 of 4 parameters describedList the items on the User Review Board (`.handoff/review_board.md`) with their status, without loading the whole file into context. Returns {items: [{id, title, status, priority, assignee, date, has_images, has_comparison (expected_image and actual_image both present), expected_image, actual_image, diff_image, similarity_pct, threshold, category}], summary: {total, pending, answered}} in file order. status is `pending` (checkbox `[ ]` and an empty memo line) or `answered` (checkbox `[x]` or a non-empty memo line); `resolved` items have moved to the decisions file and are not listed. Filters combine with AND; a filter that matches nothing returns an empty list. A missing board file returns an empty list and creates nothing. Read-only.
handoff_review_read4 of 4 parameters describedRead ONE item section of the User Review Board (`.handoff/review_board.md`) by stable id or 0-based seq, without loading the whole board. Returns {seq, id, title, category, body, status (pending|answered; a resolved item has left the board, so it is never returned), priority, assignee, date, task_id, doc_id, expected_image, actual_image, diff_image, similarity_pct, threshold (image comparison attributes, null when absent; similarity_pct and threshold are numbers, a non-numeric line is read as null with a warning), images[] (paths of the Markdown image links in the section), checkbox_checked, memo, content_hash}. status is `answered` when the user ticked the checkbox or wrote a memo, else `pending`. content_hash is the FNV-1a hash of the section's raw bytes: pass it back as expected_hash to handoff_review_update. format="meta" omits body and memo. `seq` counts ### item sections only (not ## categories) in file order. When both id and seq are given, id wins. An unknown id, an out-of-range seq, neither argument, or a missing board is an error. Read-only.
handoff_review_update4 of 4 parameters describedUpdate ONE item section of the User Review Board (`.handoff/review_board.md`) under an optimistic lock. Read the section first with handoff_review_read and pass its content_hash as expected_hash. Only the target section's bytes are rewritten; every other byte of the file (including sections the user edited meanwhile) is preserved exactly, and the file is replaced atomically (temp file + rename). If expected_hash is stale the call fails, the file is untouched, and the error reports the section's `current_hash` so you can re-read and retry. updates keys (all optional, at least one required; an unknown key is an error): body (replaces the whole body, image links included), priority / assignee (empty string removes the attribute line; an assignee key outside the config.toml `[assignees]` roster is still written but returns a warning), checkbox_checked, memo (replaces the memo text; empty clears it), images (replaces the body's standalone image-link lines with links to these paths; empty array removes them). Text that would restructure the board (a ## or ### heading, an unclosed code fence, a checkbox line inside memo) is rejected. The heading and its rb-id comment never change. Returns {id, updated[], status, checkbox_checked, content_hash} where content_hash is the section's new hash.
handoff_review_resolve4 of 4 parameters describedResolve ONE item of the User Review Board: move it from `.handoff/review_board.md` to the decisions archive `.handoff/review_board_decisions.md` together with the resolution text. The archive is plain Markdown (no frontmatter) starting with `# Decisions`; the new entry is inserted directly below that heading (newest first) as `### <title> <!-- rb-id: R-NNN -->` followed by `- date: YYYY-MM-DD`, `- original_id: R-NNN` and the decision text (a decision line starting with `#` is stored with a leading backslash; an unclosed code fence is rejected). The archive is created on the first resolve. Runs under the board write lock on a fresh read; the archive is written first and the board second, both atomically (temp file + rename), so if the board write fails the archive entry is kept, the item stays on the board unchanged, and a retried resolve does not duplicate an identical entry. Every other byte of the board is preserved (an emptied `##` category stays). The resolved id stays reserved: handoff_review_add never reuses it. Any item (pending or answered) can be resolved. A missing board, an unknown id, a missing or empty decision, or an id that appears twice on the board is an error and nothing is written. Optional record_session_decision=true also appends the decision to the active session (a missing session is a warning, not an error). Returns {id, title, decisions_path, warnings[]}.
handoff_review_init1 of 1 parameter describedCreate the User Review Board, `.handoff/review_board.md`, with the default category sections (設計判断, 実装確認, テスト確認, その他). The board is a plain Markdown file (no frontmatter) the user reads and answers in any editor or Markdown preview: `##` headings are categories, `###` headings are items. An existing board is left byte-identical. handoff_review_add creates the board on first use, so calling this is optional. Returns {created, path, exists}.
handoff_review_add14 of 14 parameters describedAdd an item to the User Review Board (`.handoff/review_board.md`) for the user to review. Appends a `### <title> <!-- rb-id: R-NNN -->` section at the end of the `##` category section named `category` (the section is created when missing, and so is the board). The section holds visible `- priority:` / `- assignee:` / `- task_id:` / `- doc_id:` / `- expected_image:` / `- actual_image:` / `- diff_image:` / `- similarity_pct:` / `- threshold:` lines (only those given; the last five record an image comparison / VRT verdict), `- date: YYYY-MM-DD`, the body with any image links, a `- [ ] 確認済み` checkbox and an empty `メモ:` line the user fills in. The stable id R-NNN is one more than the highest id used so far. Titles, attributes and image paths must be single-line; the body must not contain `##` or `###` heading lines (use `####` or bold) or an unclosed code fence. Nothing is written when the input is rejected. An assignee key that is not an `[assignees.<key>]` entry of config.toml is still written but returns a warning. Returns {id, category, category_created, board_created, warnings, path}.
handoff_overview1 of 1 parameter describedCross-worktree overview of a single project's multi-agent state: registered agents, a task x agent claim matrix, and a worktree x branch x session mapping. Call from the primary worktree to monitor every worktree working the same project. Works with zero registered agents/claims (single-WT environments).
handoff_reclaim_task3 of 3 parameters describedForcibly release a task's claim lease as a management operation, regardless of which agent holds it or whether the lease has expired (no ownership check, unlike handoff_release_task). Reverts the task to todo and records a task.reclaimed event in events.jsonl. Fails if the task has no active lock.
handoff_events6 of 6 parameters describedQuery .handoff/events.jsonl (lease/agent/session lifecycle events: task.claimed, task.released, task.expired, task.reclaimed, agent.registered, session.created, session.activated, session.resumed, session.closed, session.pruned, memory.merged) with optional filters. Returns matching events oldest-first, most-recent-first when truncated by limit.
handoff_report21 of 21 parameters describedReport engine (FR-513/SPEC-513): generate Markdown reports from Handlebars templates and run them through an approval workflow. Built-in templates are embedded in the binary; a `<report_type>.md.hbs` file in .handoff/templates/ overrides the built-in of the same name (other *.md.hbs files there are registered too, usable as partials). Templates see `{report: <metadata>, data: <data argument>}`; output is not HTML-escaped. Reports are stored as .handoff/reports/<report_id>.md (body) + <report_id>.json (metadata). action="generate" (write): report_type (required: verification|weekly|inspection|effort|monthly|milestone|defect|completion|daily|quarterly|yearly), scope? ({label?,period?,from?,to?,layers?,items?,campaign?,statuses?,assignee?,milestone?}; unknown keys are an error, and so is a known key the chosen report_type does not use), data? (object passed to the template). report_type=verification (FR-514/SPEC-514) collects its own data: scope.layers / scope.items / scope.campaign / scope.statuses select the rows (campaign rows come from the campaign checklist; otherwise every trace item in the selected layers, using its latest recorded run, a `waive-verify` waiver, or the graph state), and the report has summary counts (the coverage rate is pass/(total-waived), the same covered/(total-na-waived) formula handoff_trace_report and the baseline diff use), per-layer coverage, results with evidence links, failed/blocked items with follow-up tasks, waived items with reasons, and an approval block; keys passed in `data` overlay the collected ones. report_type=weekly (FR-515/SPEC-515) collects its own data for scope.period (ISO week `2026-W41` or range `2026-10-05..2026-10-11`; or scope.from + scope.to; default: the current ISO week; the resolved from/to are stored on the report's scope): tasks completed in the period (completed_at in range, supplemented by `task.status_changed` -> done events in events.jsonl), in-progress tasks with progress and remaining hours, blocked tasks, hours logged in the period (time_log.jsonl) per task vs. estimates and cumulative consumption, per-layer verification progress (from the trace report; a trace failure is rendered, not fatal), milestone progress, and next week's scheduled tasks; keys passed in `data` overlay the collected ones. report_type=inspection (FR-523/SPEC-523, R2: inspection certificate) requires scope.campaign: an APPROVED verification campaign (any other campaign status is an error; layers/items/statuses/period/from/to/assignee are rejected because the certificate covers the whole checklist); it collects its own data and renders document control (document no. `INSP-<campaign id>`, version, issue date, inspectors = checklist verifiers, approver, overall judgement pass|fail|incomplete), revision history, summary counts, the judgement of every checklist item with evidence links (every item is titled with the wording frozen in the campaign checklist, i.e. what was inspected; an item whose current definition differs is flagged `definition changed after inspection` and listed in a Definition Changes After Inspection section with both wordings), non-conforming (failed/blocked) items with follow-up tasks and a blank disposition column, waived items with reasons, and a signature block. report_type=effort (FR-524/SPEC-524, R5: effort report) collects its own data from time_log.jsonl and the task list for scope.period (ISO week or date range) or scope.from + scope.to (default: the whole log) and optional scope.assignee (the entry's agent id, else the task's assignee, else `(unassigned)`; exact match): hours by week and day, by task, by assignee (with share), and an estimate-vs-actual deviation analysis (task schedule estimate vs cumulative actual_hours, variance and variance %, largest first); layers/items/campaign/statuses are rejected; keys passed in `data` overlay the collected ones. Creates a `draft` report; version is 1 + the number of existing reports with the same type and scope. report_typ…
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.