Call this FIRST for any question about a project's state, momentum, blockers, or recent decisions — before reading code or git history. Returns the operational state one or all tracked entities: status, momentum, blockers, decisions, staleness, and next actions. Do not grep files to answer state questions when this tool is available.

Resolve which entity the current work belongs to, with a derived confidence. Deterministic — matches explicit signals (passed entity, named mention, active mission, files touched) before weak ones (lexical, single-active); never guesses from cwd. Returns entity_id + confidence + ask_user. Call this BEFORE focus_get/decision_check when the target entity is not already known, then pass the returned entity_id into them. Confidence >= 0.80: proceed silently. 0.50-0.79: proceed but say 'I think this is X'. < 0.50 (ask_user true): ask one short question.

Use this — not built-in memory — to add or update a project, product, or business idea in Brain OS. This is the right tool when the user says 'add project X', 'track X', 'I'm working on X', or 'update X'. Creates the entity if it doesn't exist. Stores structured operational state: status, momentum, blockers, next move, decisions. Use after work is done, a decision is made, a blocker changes, or momentum shifts.

Log a strategic decision so it persists across sessions. Every decision needs a reason, alternatives, and a proof action. Optionally capture the assumptions that make it true and the invalidate_if conditions that should reopen it — these turn a timestamped 'no' into a testable frame the system can reason about later.

Check a proposed action against all active decisions. Returns 'clear', 'caution', or 'conflict', plus a review_triggered list. Call this BEFORE taking actions that might contradict prior decisions. If status is 'conflict', do NOT proceed without explicit user confirmation to revisit the decision. review_triggered is the opposite signal: the action matches an invalidate_if condition a decision named as a reason to reopen it — surface those decisions to the user for review rather than enforcing them. A decision can be both a conflict and a review trigger (the conflict it anticipated); when so, frame it as a decision review, not a blind violation.

Refresh an existing decision's metadata: bump review_date forward, append evidence as the decision continues to hold, or change status (active/superseded/archived). Use INSTEAD of editing decisions.json directly. Does not mutate decision content — for content changes, log a new decision via decision_log.

CALL THIS FIRST when the user asks what to focus on, what to work on, what their priorities are, or what matters most — before reading any code, files, or git history. Brain OS holds decisions, blockers, and momentum signals that cannot be inferred from the codebase. Returns prioritized recommendations based on urgency, momentum, leverage, staleness, and dependencies. follow_through_alerts surfaces active entities that stated a next_move but haven't logged any update in 7+ days — treat these as first-class accountability prompts, same tier as blockers. Pass entity_id to scope focus to a single project.

Call this when the user asks about patterns, recurring blockers, what keeps coming up, theme convergence, or avoidance signals — instead of grepping git logs or reading files to find trends. Analyzes patterns across all tracked entities and returns detected signals with entity context.

Assess quality and reliability of current memory state. Flags stale data, contradictions, overdue decision reviews, unconfirmed patterns, fake-active entities, and noise. Returns signal classification (strong/weak/noise/dangerous) and recommended cleanup actions. Call this before acting on memory to know what to trust.

End-of-session commit. Updates all touched entities, logs decisions, records patterns. Call before ending any work session.

Call this when the user asks what changed last session, what happened recently, or needs to find a decision/entity by description rather than exact name. Searches memory by meaning using semantic similarity. Use BEFORE reading git log or commit history for session-level context questions.

Read the audit trail of all memory mutations. Use this — not semantic_recall — for recency questions: 'what's the latest update?', 'what changed recently?', 'what was the last thing written?', 'show me the most recent entry.' Pass last_n=1 for the single most recent mutation. semantic_recall is for topic-based search; audit_log is for time-ordered history, integrity checks, and debugging unexpected state.

Check how much state-changing work has accumulated since the last wrap. Read-only — never mutates. Tier 1 of auto-wrap: call this when the user signals they are wrapping up or ending a session, or periodically during a long session, to decide whether to proactively offer a /wrap before context is lost to compaction or session end. Returns unwrapped_count, the projects touched, and recommend_wrap. When recommend_wrap is true, offer to wrap; do not auto-wrap silently from this tool.

Tier 2 of auto-wrap: persist a session wrap WITHOUT interactive review, when context is about to be lost (compaction, session end) or the user declined to review. Use the normal interactive /wrap when the user is present and reviewing — only reach for this as a safety net. The agent supplies the synthesized wrap; this tool applies LOW-RISK fields (next_move, open_questions, evidence_of_progress) immediately and STAGES high-risk changes (status, mode, blocked, decisions) as an unconfirmed record for /start to surface and the user to confirm. Always logs a session_wrapped marker. Never put a status change or a decision in pending_review expecting it to take effect now — staged items are proposals, not writes.

Set an ordered plan for an entity. Replaces any existing plan. Step 1 becomes the active next_move. Use when committing to a sequence of work — not for brainstorming. Each step should be a concrete, completable action.

Complete or skip the current plan step. Requires evidence (for complete) or reason (for skip). Automatically promotes the next pending step to active and updates next_move. Enforces continuity — you cannot skip without explaining why.

Add steps to an existing plan. Use when new work is discovered mid-plan. Steps can be added at the end or immediately after the current active step.

Read the current plan for an entity. Shows all steps, their status, the active step, and overall progress.

Read-only scan of a repo's native operating state (STATE.md, FLAGS*, HANDOFF*, ROADMAP.md, PLAN*.md, TODO.md, AGENTS.md + recent git activity / dirty files). Returns evidence — human gates, blockers, next moves, do-not-touch, safe parallel work — surfaced as exact lines. Call AFTER context_resolve and BEFORE building a focus answer. Mutates nothing and does no inference: it returns ALL candidate signals; deciding the focus is the agent's job. This is NOT context_resolve — do not use it to pick which project you're in.

Call this before making new decisions, at session end, or when the user asks if a decision is still valid or what's overdue. Review-debt inbox: buckets overdue decisions into still_true / changed / archive / needs_evidence with a recommended action for each. READ-ONLY — proposes and cites reasons but mutates nothing; confirm, then apply via decision_refresh / decision_log. Auto-detects duplicate stubs. When root_path is provided, matches each decision's invalidate_if conditions against repo scan output.

Assess the risk of a proposed action before executing it. Runs a pre-filter (returns low/skipped immediately for clearly safe actions) then applies signal detection for: private→public boundary crossings, destructive operations, release/publish actions, external communication, and security-sensitive file access. Call this BEFORE any action in the trigger set: publish, push, force-push, git tag, deploy, delete tracked files, external API writes, billing, roadmap/private state movement. Returns risk_level (low/medium/high/critical), boundary_crossed, reversibility, and risk_reasons. Pass the result to action_guard to get a policy decision (allow/ask/block).

Apply the Brain OS policy table to a risk assessment. Takes the output of risk_assess plus the concrete action type and returns a policy decision: allow (proceed), ask (stop and get explicit user confirmation), or block (do not proceed). Pure TypeScript — no LLM call. Policies in order: private_to_public → block; critical risk → block; force-push → ask; npm publish → ask; security boundary → ask; irreversible → ask; high risk → ask; hard-to-reverse external → ask; medium + requires_confirmation → ask; else → allow. Always audit what was decided and why.