[TASK TOOLS] Adds a list of tasks to the project backlog.

[TASK TOOLS] Queries the task backlog in LanceDB with optional filters and returns matching task summaries ranked by creation order.

All parameters are optional filters — omit to retrieve all tasks with default status. Default status filter is 'open'; pass status=None to retrieve tasks of all statuses. Do NOT call get_task_details on every result — use this tool for status checks and task selection, then call get_task_details on the single selected task for full content.

Allowed status values: open | in_progress | blocked | done | None (no filter) Allowed priority values: low | medium | high | critical | None (no filter) Allowed type values: feature | bug | task | td | None (no filter)

Returns: list of task summary objects — each with task_id, title, status, priority, type, and blocked_by. Full problem/solution content is excluded; call get_task_details for that. Raises: 404 if project is not found.

[TASK TOOLS] Returns full task details.

[TASK TOOLS] Partially updates mutable fields on an existing task (status, priority, title, solution, etc.) using a merge strategy — only keys present in updates are changed; all other fields remain intact. Use this for in-progress changes (e.g. updating priority or editing the solution).

Do NOT use to close a task — call complete_tasks instead, which atomically closes and auto-unblocks dependents. Do NOT use to create tasks — call add_tasks instead.

Allowed updates keys: status : open | in_progress | blocked | done priority : low | medium | high | critical title : str problem : str solution : str blocked_by : list[task_id]

Returns: updated task object with all current field values. Raises: 404 if task_id not found in project.

[TASK TOOLS] Atomically closes one or more tasks and auto-unblocks dependents.

[ARTIFACT TOOLS] Semantic search over artifact chunks, optionally scoped to one or more directories; returns each hit's location plus file content. Read-only.

Parameters: project : project name. query : natural-language search text. limit : max hits. With scopes, applies to the combined OR result, not per scope. scopes : project-relative directory paths, max 20, OR semantics. Omit (or None/[]) for unscoped -- unchanged from before this param existed. Directories only; a file path simply matches nothing.

Returns: on a normal or unscoped call, a list of hits (path, section, start_line, end_line, distance, content, warning -- as before). If scopes matched zero chunks, returns a single object instead of a list: {"message": str} explaining why -- check for a "message" key, not list length, to tell the two shapes apart. Raises: 404 unknown project. Validation error for a bad scope (absolute, '..', outside project root) or >20 scopes -- names the scope, never a host path. Per-hit read failures set warning (partial success), not an exception.

Do NOT use to read a known file -- call read_project_artifacts instead. Do NOT pass a file path as a scope -- scopes are directories.

[CODE TOOLS] Semantic search over indexed source code skeletons. Searches the code_skeleton_index populated by marrow_worker. Returns matching code units (methods, classes, namespaces, etc.) ranked by semantic similarity to the query, each with file path, line range, and skeleton text. Use root_path to scope to a module.

[CODE TOOLS] Retrieves a token-optimized outline of a file's code units (classes, methods) with line numbers. Use depth=1 for orientation (names only), depth=2 for analysis (signatures), depth=0 for full detail.

[CODE TOOLS] Returns a live directory tree of all files indexed in the code skeleton index. Use this to orient yourself and find relevant subdirectories before starting a scoped search.

[CODE TOOLS] Read a precise line range from the live source repository ("The Scalpel"). Requires SOURCE_ROOT to be configured in project/.settings.

[SESSION TOOLS] Reads session.md, detects the active pipeline phase, and returns core guidelines + phase-appropriate role guidelines + filtered foundational ADRs

• role-linked skill stubs (=== PLAYBOOKS === section, when the role has skills registered) as a single assembled string.

If start_role is provided, session.md is bypassed entirely: the named role is resolved directly and SESSION STATE is omitted from the response.

[SESSION TOOLS] Assembles and returns the full context bundle (core guidelines + role-specific phase guidelines + filtered foundational ADRs) for a named agent role, without reading or modifying session.md.

Use this for deliberate mid-session role switches when you already know the target role and do not want to disturb pipeline state. Do NOT use at session start — call get_session_context instead, which also injects the SESSION STATE block and the correct NEXT STEP directive.

Allowed role values: any role registered in the project's role_profiles.yaml (e.g. 'discovery', 'architecture', 'planning', 'execution'). Returns an error string listing valid roles if the value is unrecognised.

Returns: assembled markdown string (core guidelines + role guidelines + ADRs). Raises: error string if role is not registered in role_profiles.yaml.

[PROJECT TOOLS] Returns a list of all available projects.

[PROJECT TOOLS] Creates a new Marrow project workspace by copying the built-in default template into TASKS_DIR/projects/{project}. Produces a ready-to-use artifact tree (session.md, spec.md, guidelines, role_profiles.yaml).

Primary use case: first-run initialization on Glama or any single-container deployment where shell access is unavailable. For docker-compose deployments, use the marrow-init service instead.

Do NOT use to list existing projects — call list_projects instead. Do NOT use to read session state — call get_session_context(project) after init.

Parameters: project : str — unique project name (must not already exist) template : str — scaffold template; only "default" is supported in this release

Returns: { project, files_created } where files_created lists every file path copied into the new workspace (relative to workspace root).

Raises: ValidationError if project already exists or template is unsupported.

[ARTIFACT TOOLS] Reads one or more artifact files in a single batch call. Each item in reads targets one file and specifies an independent read mode.

Read modes per item: full — returns the entire file content. paged — windowed read of the entire file. max_chars (default 10000), skip_chars, and direction (default). section — returns only the content under a named ## header (requires section_name). lines — returns a specific line range (requires start_line and end_line).

Optional per-item fields: max_chars : int — truncate response at N characters (default 10000). skip_chars : int — skip N characters from the start of the selection. direction : 'begin' | 'end' — read from start or end of file (default 'begin'). line_numbers : bool — prefix each line with its 1-based line number.

Do NOT loop this tool per file — batch all reads into a single call to minimise round-trips. For source code files in src/, use view_file_source instead.

Returns: list of result objects — each with path and content (or error if not found). Raises: per-item error entry if a path does not exist; does not abort the batch.

[ARTIFACT TOOLS] Creates or updates one or more artifact files in a single atomic batch. Each item in updates targets one file and specifies an independent write mode — modes in the same batch do not interact.

Write modes per update item: replace_file — overwrites the entire file (creates it if absent). replace_section — replaces the content under a named ## header; raises if the header appears more than once (ADR-0011). append_section — appends a new ## section at the end of the file. replace_chunk — replaces lines start_line..end_line with new content. patch — finds old_str (must be unique in the file) and replaces it with new content. Preferred for surgical single-line edits. delete_section — removes a named ## section and its content.

Do NOT use replace_file when only a section needs updating — use patch or replace_section to avoid clobbering concurrent edits. Do NOT use this tool for source code in src/ — the source directory is read-only from the agent's perspective.

Returns: list of result objects, one per update — each with path and status. Raises: duplicate-header error (with line numbers) if replace_section finds multiple matching headers in the same file.

[ARTIFACT TOOLS] Lists artifact files in a project's artifact storage, optionally scoped to a subfolder and optionally traversing subdirectories.

path narrows the listing to a specific folder (e.g. 'docs/features/active'); omit or pass '' to list from the project root. recursive=True traverses all subdirectories; default is False (top-level only).

Do NOT use to read file content — call read_project_artifacts instead. Do NOT use to browse source code — call get_project_map for the src/ tree.

Returns: list of objects — each with path (relative to project root) and size in bytes. Raises: 404 if the project or path does not exist.

[ARTIFACT TOOLS] Moves or renames an artifact.

[ARTIFACT TOOLS] Deletes a single artifact file by moving it to the recycle bin. The file is preserved in the recycle bin and can be restored using restore_project_artifact if needed.

Do NOT use to move or rename a file — call move_project_artifact instead.

Returns: confirmation string with the deleted file path. Raises: 404 error if the path does not exist in artifact storage.

[ARTIFACT TOOLS] Full-text search across all artifact files in a project, matching against file content and returning files and sections that contain the query string.

Query is plain text — no special syntax required. Case-insensitive. For semantic / meaning-based search, use semantic_search instead. Do NOT use this to list files — call list_project_artifacts instead. Do NOT use this for source code — call search_code_skeletons instead.

Returns: list of match objects — each with path, matched section name, and a short excerpt of the matched content with surrounding context. Raises: 404 if the project does not exist.

[ARTIFACT TOOLS] Extracts table of contents.

[HISTORY TOOLS] Returns the version history for a single artifact file — a list of backup snapshots automatically created by save_project_artifacts on each write. Each entry represents a point-in-time copy that can be restored.

Use this to inspect available versions before calling restore_project_artifact. The most recent backup is listed first. Do NOT use this to read current file content — call read_project_artifacts instead.

Returns: list of version objects — each with backup_name, created_at timestamp, and size in bytes. Empty list if no history exists for the path. Raises: 404 if the artifact path does not exist in the project.

[HISTORY TOOLS] Restores a named backup snapshot of an artifact, replacing the current live file with the backup content. The current live version is NOT automatically backed up before the restore — it will be overwritten.

Use list_artifact_history first to retrieve valid backup_name values for the target path. The backup_name is the exact string returned in the history list. Do NOT guess or construct backup names — always read them from list_artifact_history.

Returns: confirmation string with the restored path and backup_name applied. Raises: 404 if the path or backup_name does not exist.

[BUILD TOOLS] Executes a named build pipeline defined in the project's build manifest (a YAML file registered under docs/builds/ in the artifact store). The manifest defines the sequence of steps (shell commands, artifact writes, tool calls) that run in order.

Optional variables dict injects runtime values into manifest template placeholders, e.g. {"FEATURE": "Auth"} replaces {{FEATURE}} in step definitions.

Do NOT use this to read or write individual artifacts — call save_project_artifacts or read_project_artifacts instead.

Returns: build result object with status (success | failure), step outputs, and elapsed time. Raises: 404 if build_name does not match any manifest in the project. RuntimeError if any step in the pipeline fails (includes step output).