Scan source files for dead code, duplicates, oversized modules, and dependencies. Use when: you need repository-wide findings before planning changes. Don't use when: you only need source lines from a known file (use get_chunk instead).

Returns {summary, dead_code, duplicates, god_files, dep_graph, subprojects}. Summary includes file/symbol/line counts, languages, parse_failures and unscanned-source counts. Findings carry file paths and 1-indexed lines; dep_graph has nodes, {from, to} edges, circular paths, external_imports, unresolved_relative_imports and package_imports counts. A missing/non-directory root or a path-validation failure returns error, empty findings/graph and a zero summary, without subprojects. Lists are capped at 200 items, duplicate groups at 50 and their locations at 10; shortened lists gain _total, with truncated listing shortened top-level/graph lists. Summary counts remain complete. In a nonempty Git index, only tracked files are analysed; outside Git, all eligible files are.

Read an inclusive line range from a UTF-8 file without modifying it. Use when: you need to inspect a finding or obtain context for a patch. Don't use when: you need repository-wide findings (use scan_repo instead).

Returns {source, language, start_line, end_line, total_lines} on success, or {error} on failure. Source joins the selected lines with newlines; start_line/end_line report the clamped inclusive range. Large files can be read in slices; binary, lock and minified-file guards still apply.

Apply a unified diff to one file, optionally run tests, and attempt rollback on failure. Use when: you have reviewed the source and prepared a specific patch. Don't use when: you only need to record existing edits in Git (use git_commit instead).

Returns {success, test_output, error, rolled_back}. Successful patches also return git_state (clean, modified, untracked or no_repo) and backup (null when Git holds the original, otherwise a retained .reforge-bak path). Tests are optional; success without test_command does not mean tests ran. No commit is created. Reapplying the same diff is not idempotent.

Stage the named files and create a Git commit within the session budget. Use when: edits have been reviewed and should be recorded in local Git history. Don't use when: you need to apply or test a patch first (use write_fix instead).

Returns {success, commit_hash, branch, files_committed, error}. A checkpoint additionally returns needs_confirmation=true and message; retry with confirmed=true after approval. files_committed echoes the requested list, not an inventory of the commit: previously staged changes are also committed. Refuses an empty commit when the staged index matches HEAD; refusals do not consume the session budget. Initial commits with staged content are allowed. May create/check out a branch and invoke Git hooks; does not push.

Read one top-level value from persisted repository state without writing files. Use when: you need a saved hypothesis, fix queue, fix log or health history. Don't use when: you need to replace a stored value (use write_memory instead).

Returns {key, value, found}; an unknown key returns value=null and found=false. Built-in default keys may return found=true even when no state file exists.

Create or replace one top-level value in reforge-state.json via a staged write. Use when: you need to persist a hypothesis, fix log or pending work across sessions. Don't use when: you only need to inspect a stored value (use read_memory instead).

Returns {success, key, previous_value}, with error on an OSError while saving. previous_value is null for an absent key or a previously null value. Repeated calls can change previous_value and rotate timestamped state backups, so this is not idempotent even when the supplied value is unchanged.

Infer a repository's architectural pattern and save its hypothesis to reforge-state.json. Use when: you need an initial map of the project's likely shape and entry points. Don't use when: you only need the previously saved hypothesis (use read_memory instead).

Returns {pattern, evidence, entry_points, inferred_modules, confidence, hypothesis}. Pattern is REST API, CLI tool, web frontend, library or unknown; confidence is a heuristic fraction from 0 to 1. Classification uses imported modules, with filename-based entry-point/module guesses. Scans without an external model, then writes architecture_hypothesis and rotates state backups.

Estimate the risk of changing one symbol on a heuristic 0-to-100 scale. Use when: you need to prioritize a specific proposed change before patching. Don't use when: you need an overall repository health trend (use get_health_score instead).

Returns {score, breakdown, basis, referenced_by, recommendation}. Breakdown contains point contributions: inbound_refs (0-30), has_tests (0 or 20 for no referencing test), lines_changed (5/10/17/25 based on file length, not patch size), is_circular (0 or 25). basis is symbol, or file when reference sets are unavailable. referenced_by contains at most 10 sorted paths. Recommendation is safe to fix (<=30), fix with caution (<=60), or manual review recommended (>60); this is not a guarantee of correctness or coverage.

Compute repository health from scan metrics and append a timestamped state entry. Use when: you need a before/after health metric and persisted history. Don't use when: you only need findings without writing state (use scan_repo instead).

Returns {score, coverage, breakdown, scan_summary}, plus caveat for limited coverage or parse failures. score is 0-100 (higher is healthier), or null when no files were analysed. coverage is the analysed fraction (0-1, three decimal places), not test coverage. Breakdown contains dead_code_ratio, duplicate_ratio (fractions rounded to three decimals), god_file_count and circular_count. Deductions cap at 30/30/20/20 points respectively; only Python/JS/TS-sensitive cycles reduce health. The history entry is appended on every call, so repeated calls are not idempotent.

Write REFORGE_CHANGES.md from saved health history, fixes and pending work. Use when: you need a human-readable report of state recorded during cleanup. Don't use when: you only need one raw saved state value (use read_memory instead).

Returns {success, path}, with error if the Markdown file could not be written. Reads health_history, fix_log and pending_fixes; it does not rescan, infer fixes from Git or populate those lists. Overwrites the report with a fresh UTC generation timestamp, so repeated calls are not idempotent.