Record build/test results for ceremony tracking and delivery gates.

Use when:

• You just ran project-native validation (via shell/CI/script) and need the outcome logged.

• You want the delivery gate to see the latest pass/fail + coverage.

• You want Q-learning feedback attached to a phase transition.

This tool does NOT execute subprocesses — run validation commands first, then call this with the results.

Input:

• tests_passed: True or False — required; no default guess.

• test_count: total checks/tests that ran.

• failure_count: number that failed.

• coverage_pct: 0.0-100.0, if measured.

• static_checks_clean: preferred neutral status for configured static/type/lint/schema checks.

• mypy_clean: legacy compatibility alias; use only for older clients or Python-specific reports.

• scope: label like full, quick, type-check, cargo test, npm test.

• failures: optional list of up to 10 failure descriptions.

• run_path: optional run directory for event logging.

• min_coverage: when set, falls tests_passed to False if coverage_pct is below the threshold (adds coverage_threshold_failed flag).

Output: dict with fields {status, run_id?, outcome, tests_passed, coverage_pct, static_checks_clean, mypy_clean, coverage_threshold_failed?, gate_effects: list[str]}.

Load prior learnings + any active run so you start with full context.

Use when:

• Starting a new session (first action, before reading code or editing).

• Resuming after context compaction and you need the pin and learnings reloaded.

• Switching onto an unfamiliar task and want a focused recall on the topic.

Recalls high-impact learnings (patterns, gotchas, architecture decisions) and checks for an active run (phase, progress, last checkpoint). Partial-failure resilient: a failure in one sub-step does not block the others.

Input:

• query: optional focus string. When set, performs a focused recall on your topic AND a baseline high-impact recall, then merges + dedupes. Empty string or "*" uses default wildcard behavior.

• verbose: when False (default) returns a COMPACT payload — the learnings list is capped to the top-K most relevant (with a learnings_omitted "N more" indicator) and the low-signal diagnostic sub-blocks (embed_health/assertion_health/sync_health/step_durations_ms) are folded into a one-line health_summary to cut token cost. Run/pin recovery, errors, framework_reminder, and degraded advisories are always preserved. Set verbose=True for the full diagnostic payload (legacy behavior).

Output: SessionStartResultDict with fields {learnings: list, learnings_count: int, learnings_omitted?: int, run: RunStatusDict, auto_recalled?: list, health_summary?: str (compact), embed_health?: dict (verbose), assertion_health?: dict (verbose), framework_reminder: str, errors: list, success: bool, compact: bool, payload_token_estimate: int}.

Example: trw_session_start(query="sqlite extension macos") → {"learnings": [...], "learnings_count": 8, "compact": true, "health_summary": "embed=ok; start=42ms (verbose=True for ...)", "run": {"active_run": "/path/...", "phase": "IMPLEMENT"}, ...}

See Also: trw_init, trw_recall

Persist learnings and progress so future sessions inherit this session's work.

Use when:

• Your session is about to end and you want discoveries to persist for future agents.

• A milestone is reached and you want to close out the current run directory.

Before calling, check: did you record at least one discovery with trw_learn? If not, add even a one-line root-cause learning so the next agent avoids re-discovery.

Runs reflect + checkpoint synchronously, then launches housekeeping (consolidation, publish, telemetry, tier sweep) in the background. Background work is concurrency-safe — overlapping batches are skipped rather than queued.

Input:

• run_path: path to run directory (auto-detected if None).

• skip_reflect: skip reflection step (e.g., already reflected).

• skip_index_sync: skip INDEX/ROADMAP sync step.

• allow_unverified: explicit override for delivery without a passing trw_build_check record. Use only for documented acceptable failures.

• unverified_reason: required rationale when allow_unverified is true.

Output: DeliverResultDict with fields {run_path: str, reflect: dict, checkpoint: dict, deferred: str, critical_steps_completed: int, deferred_steps: int, errors: list, success: bool, learning_reflection?: str}.

Example: trw_deliver() → {"run_path": "/path/...", "critical_steps_completed": 2, "deferred": "launched", "success": true}

See Also: trw_checkpoint, trw_instructions_sync

Refresh the caller's pin heartbeat and append a heartbeat event.

Use when:

• A long-running campaign needs to keep its pin alive between work units.

• You want to probe whether the current run is stale enough to checkpoint.

Rate-limit: if now - last_heartbeat_ts < 60s the call short-circuits (no events.jsonl append, no pin-store write) and returns rate_limited=True so long-running loops don't spam the audit trail. Rate-limit state lives in pins.json::<pin_key>::last_heartbeat_ts so the 60s window survives server restart.

Input:

• message: optional context string logged alongside the heartbeat event.

Output: TrwHeartbeatResultDict — on success {run_id, last_heartbeat_ts, stale_after_ts, age_hours, should_checkpoint, rate_limited}; on missing-pin {error: "no_active_pin", hint: "call trw_init or trw_adopt_run first"}.

Transfer an existing run's pin to the caller's session.

Use when:

• Resuming a run started by another session (fresh context, same task).

• Reclaiming a run whose previous owner went away without delivering.

Guards:

• Out-of-project run_path raises StateError (no force override).

• Terminal status (delivered/complete/failed) requires force=True.

• Live owner (heartbeat within pin_ttl_hours) requires force=True and emits run_adopted_potential_writer_conflict WARN when displaced.

Input:

• run_path: absolute path to the run directory to adopt (required).

• force: override terminal-status and live-owner guards.

Output: TrwAdoptRunResultDict with fields {adopted_run_id, previous_pin_key, from_pin_key, to_pin_key, adopted_ts, from_owner_was_live, force_used}.

Example: trw_adopt_run(run_path="/repo/.trw/runs//") → {"adopted_run_id": "", "from_pin_key": "sess-a", "to_pin_key": "sess-b", "force_used": false, ...}

Capture a safety checkpoint before the context window compacts.

Use when:

• Invoked by the PreCompact hook on imminent context compaction.

• You suspect compaction is near and want a clean resume point on disk.

PRD-CORE-165 FR-01: pass directive (the active operator directive / task you are mid-flight on) and context_anchor (where you are in it — e.g. the in-flight experiment or handoff pointer). These live in the conversation, not in trw state, so they cannot be auto-derived; when supplied they are persisted into the pre-compact state and surfaced on the next trw_session_start so the post-compaction session resumes exactly instead of re-orienting by hand. Both are optional and backward-compatible.

Best-effort: sub-step failures populate status but do not raise.

Output: PreCompactResultDict with fields {status: "written"|"skipped"|"error", reason?: str, checkpoint_path?: str, instructions_path?: str, compact_state_path?: str, directive?: str, context_anchor?: str}.

Persist a non-obvious discovery so future agents inherit the finding.

Use when:

• You just found a root cause, gotcha, or durable pattern worth remembering.

• Capture it the moment you validate an approach that prevents repeated mistakes.

• You hit an architecture constraint that is not obvious from reading the code.

Only record learnings that:

• prevent repeated mistakes,

• change future implementation/debugging/review behavior,

• are specific enough to recall later. Routine observations ("I read the file", "the test passed") degrade recall quality.

Required:

• summary: one-line headline.

• detail: full finding with context, symptoms, and why it matters.

Recommended:

• tags: keywords for trw_recall filtering. Accepts a JSON list (["a","b"]) OR a comma/whitespace-separated string ("a,b c").

• impact: 0.0-1.0; high values surface more often.

Advanced (auto-detected if omitted):

• shard/source/client/model/type/domain/phase/team/protection metadata.

• scope: write-tier override (PRD-CORE-185). "auto" (default) routes portable learnings to the machine-local user tier when a user-scope store is present, else the project tier; "project"/"user" force it. Most learnings need only summary and detail. Adding tags and impact improves recall precision. All other fields are auto-detected.

Output: LearnResultDict with {id: str, status: "saved"|"deduped"|"error", dedup_match?: dict, ceremony_hint?: str}.

See Also: trw_recall, trw_learn_update

Update an existing learning — status, fields, or feedback signal.

Use when:

• The issue a learning describes has been fixed (status="resolved").

• A pattern is no longer applicable (status="obsolete").

• Detail or summary can be sharpened now that root cause is clearer.

• You want to boost/demote an entry's recall ranking via feedback.

Output: dict with fields {status: "updated"|"not_found"|"invalid", error?: str, field_updated?: str}.

Retrieve prior learnings relevant to your current task.

Use when:

• You are about to work in an unfamiliar area of the codebase.

• You suspect a bug has been seen before and want prior root-cause notes.

• You want a narrow tag/impact slice before spawning a subagent.

See Also: trw_learn, trw_session_start.

Results are ranked by combined relevance (query match on summary/tags/detail) and utility (impact, type-aware recency decay, prior feedback). Context boosts prioritize entries matching your current domain, phase, and team.

Output: RecallResultDict with fields {learnings: list[{id, summary, detail?, tags, impact, ...}], count: int, query: str, ceremony_hint?: str}.

Sync TRW protocol and ceremony guidance into the client's instruction file.

Use when:

• Onboarding a new project and the instruction file (CLAUDE.md / AGENTS.md) does not yet contain the TRW auto-generated section.

• You've changed the behavioral protocol template and need it re-rendered.

• You switch IDE clients and need the correct surface written.

Renders behavioral protocol and ceremony guidance into the auto-generated block of whichever client surface is present (CLAUDE.md, AGENTS.md, .codex/INSTRUCTIONS.md). Learnings are not promoted into the instruction file — trw_session_start() recall handles that (PRD-CORE-093).

Output: ClaudeMdSyncResultDict with fields {status: "success"|"error", files_written: list[str], sections_synced: int}.

Deprecated alias for trw_instructions_sync.

Use when: maintaining backward compatibility with older callers; prefer trw_instructions_sync in new code. This alias emits a deprecation warning on every invocation and will be removed in a future release.

Output: same as trw_instructions_sync — ClaudeMdSyncResultDict with fields {status, files_written, sections_synced}.

Classify a meta-tune surface as control vs advisory.

Use when you need to know whether a candidate path is governed by the SAFE-001 control surface registry before promoting a meta-tune proposal.

Returns: dict with classification ("control"|"advisory"), surfaces (list of surface names), and rationale.

Roll back a previously promoted meta-tune proposal.

Use when a promoted candidate is causing regressions and you need to restore the prior surface content while writing an entry to the SAFE-001 audit log.

Returns: dict serialization of the rollback result, including the proposal id and the restored content hash.

Create a run directory and register it as the active run.

Use when:

• Starting a new task, sprint, or investigation that needs persistent TRW state.

• You need run metadata, framework assets, and active-run pinning before work begins.

Bootstraps state, run metadata, events, framework assets, optional wave/artifact metadata, and a trace/profile-aware task_profile.

Input: task_name plus optional objective, config_overrides, task_root, wave_manifest, complexity signals, artifacts, and protection flag.

Output: dict with run_id, run_path, task_dir, phase, and status fields.

Report the active run's phase, wave progress, shard state, and last activity.

Use when:

• Resuming after context compaction or a session restart.

• Deciding whether to checkpoint, advance phase, or re-delegate a wave.

Input:

• run_path: path to the run directory. Auto-detects from pin if None.

Output: TrwStatusDict with fields {run_id, task, phase, status, confidence, framework, event_count, reflection, waves?, wave_progress?, wave_status?, reversions, last_activity_ts?, hours_since_activity?, stale_count}.

Append a progress snapshot so work survives context compaction.

Use when:

• You complete a milestone or before context compaction/interruption.

• After each meaningful work batch so another agent can resume safely.

Input: optional run_path plus required message. Optional shard_id and wave_id annotate delegated or wave-aware progress.

Output: dict with status, run_path, checkpoint path, and message metadata.

Generate an AARE-F compliant PRD from a feature description.

Use when:

• You have a feature request or requirements and need a structured PRD.

• Before writing code for a P0/P1/P2 feature or risky behavioral change.

• You want auto-incremented PRD ID, YAML frontmatter, and catalogue sync.

Produces 12 standard sections, confidence scores, and traceability links. Updates INDEX.md/ROADMAP.md when index_auto_sync_on_status_change is on.

Input:

• input_text: feature request or description (becomes Problem Statement + Background).

• category: one of CORE, QUAL, INFRA, LOCAL, EXPLR, RESEARCH, FIX (plus any values added to .trw/config.yaml::extra_prd_categories).

• priority: P0, P1, P2, or P3 — drives base confidence scores.

• title: auto-generated from input_text when empty.

• sequence: auto-increments from existing catalogue when default (1).

• risk_level: optional critical|high|medium|low — scales validation strictness.

Output: PrdCreateResultDict with fields {prd_id: str, title: str, category: str, priority: str, output_path: str, content: str, sections_generated: int, index_synced: bool}.

Example: trw_prd_create(input_text="Add rate limiting to public API", category="CORE", priority="P1") → {"prd_id": "PRD-CORE-001", "output_path": "docs/requirements-aare-f/prds/PRD-CORE-001.md", "sections_generated": 12, "index_synced": true, ...}

See Also: trw_prd_validate

Score a PRD against the V2 validation suite before implementation.

Use when:

• A PRD just landed and you need a READY / NEEDS-WORK verdict before coding.

• You want ambiguity / completeness / traceability gates checked in one call.

Runs structure compliance, content quality, AARE-F compliance, and ambiguity analysis. Catches issues here that would otherwise cause rework.

Input:

• prd_path: path to the PRD markdown file (required).

Output: ValidateResultDict with fields {total_score: float (0-100), quality_tier: str, grade: str, valid: bool, ambiguity_rate: float, completeness_score: float, traceability_coverage: float, improvement_suggestions: list[ImprovementSuggestionDict], failures: list[ValidationFailureDict], dimensions: list[DimensionScoreDict], path: str, sections_found: list[str], sections_expected: list[str], smell_findings: list[dict], ears_classifications: list[dict], readability: dict[str, float], section_scores: list[SectionScoreDict], effective_risk_level: str, risk_scaled: bool, status_drift_warnings: list[str], integrity_warnings: list[str], cache: dict}.

quality_tier values: "skeleton" | "draft" | "review" | "approved" (QualityTier enum; no "PRODUCTION" tier exists).

Example: trw_prd_validate(prd_path="docs/requirements-aare-f/prds/PRD-QUAL-074.md") → {"total_score": 87, "quality_tier": "approved", "grade": "A", "valid": true, "improvement_suggestions": []}

Compute a structured code-review verdict and persist a review.yaml artifact.

Use when:

• Gating a PR or delivery and you need a pass/warn/block verdict with receipts.

• You have pre-collected findings from a reviewer subagent (auto mode).

• You want to detect spec-vs-code drift between a PRD and git diff (reconcile).

Modes:

• manual: caller passes findings=[...] directly (backward compatible).

• auto: multi-reviewer analysis with confidence filtering.

• cross_model: route diff to an external model family.

• reconcile: compare PRD FRs against git diff.

Input:

• findings: list[{category, severity, description}] — triggers manual mode.

• run_path: explicit run directory; auto-detected when None.

• mode: explicit mode override; auto-detected when None.

• reviewer_findings: pre-collected findings from subagent layer (auto).

• prd_ids: explicit PRD IDs; reconcile mode auto-discovers when None.

Output: dict with fields {verdict: "pass"|"warn"|"block", findings_count: int, categories: dict, review_path: str, run_id: str, mode: str}.

Example: trw_review(findings=[{"category":"security","severity":"high","description":"..."}]) → {"verdict": "block", "findings_count": 1, "review_path": ".../review.yaml", "mode": "manual"}

Return a merged cross-emitter event view for a session.

Diff two PRD files with requirement, metric, and acceptance-gate focus.

Use when:

• Reviewing changes between two PRD versions or drafts.

• Auditing how requirements or acceptance criteria have evolved.

Structured diff between two surface snapshots.

Returns {added, removed, changed} lists of surface_id strings. changed entries appear in both snapshots with different content_hash values.

Return cold-start codebase intelligence for file_path.

Use when an agent is about to edit a file and needs sidecar-backed risk context plus relevant prior learnings before reading broadly.

Sources:

• trw-distill sidecar (tier-gated; requires team/pro/enterprise)

• existing learnings via trw_recall (always)

Returns BeforeEditHintResult.model_dump() enriched by client tier. NEVER raises — failure paths populate distill_status + distill_action so the operator gets an actionable next step.

Return c735+c743 BeforeYouEditBatch for the current SHA.

Use when an agent is planning a multi-file edit and needs batched before-edit hints from a persisted trw-distill sidecar.

Tier-gated (paid tiers only — see trw_before_edit_hint for the free-tier learnings counterpart). Returns BeforeEditHintBatchResult.model_dump(). NEVER raises.

Return c737/c739 ranked composite-risk report for the current SHA.

Use when a reviewer needs file-level structural risk ordering from a persisted trw-distill sidecar before prioritizing review effort.

Tier-gated. top_n=0 returns all entries; default 20. Returns CodebaseRiskReportResult.model_dump() enriched by client tier. NEVER raises.

Return c741 RiskOrderingComparison for the current SHA.

Use when comparing two persisted risk-ordering sidecars for overlap and rank-correlation drift.

Tier-gated. NEVER raises.

Return the latest c745 CrossRepoOrderingAggregate.

Use when comparing structural-risk ordering consistency across multiple repositories from a persisted aggregate sidecar.

Sidecar SHA derived from sorted-repo-names (NOT git HEAD), so operator passes sidecar_path/sidecar_dir or the tool searches the repo-default location for the most-recent aggregate. Tier-gated. NEVER raises.

Update the local SHA-256 code-index manifest.

Use when an agent needs a fresh local code-index manifest before code search or symbol analysis without returning file bodies.

Search local indexed code chunks.

Use when an agent has run trw_code_index_update and needs ranked code context without reading full files.

Find local indexed symbols with exact matches ranked first.

Use when an agent needs symbol locations from the local code index without scanning or returning full file bodies.

Return entity-level structural risk rows for the current SHA.

Use when a reviewer needs symbol/function/class/endpoint blast-radius triage from a persisted sidecar. Tier-gated. top_n=0 returns all matching rows. NEVER raises for sidecar failures.

Export canonical privacy-safe AgentWorkEvidence for a TRW run.

Use when a judge, eval harness, reviewer, or knowledge-graph importer needs one schema-valid work record instead of scraping run internals.

Validate an AgentWorkEvidence candidate and return structured errors.

Use when an external producer or fixture needs schema validation before evidence is accepted by a judge or graph-ingestion pipeline.

Rank eligible SKILL.md files without executing them.

Use when an agent needs safe skill recommendations from explicit SKILL.md paths before invoking any workflow.

Submit a memo to the TRW maintainer (PRD-CORE-182).

Use when:

• You found a bug, installation problem, or rough edge worth flagging.

• You want to send a feature request or piece of feedback that deserves a real reply instead of disappearing into a personal log.

• You want the maintainer to see exactly which trw-mcp / Python / OS you are on without retyping it — environment metadata is attached automatically.

Input:

• category: one of bugfix, installation, feedback, feature_request, question, other.

• subject: short headline (1-200 chars, no newlines).

• message: full memo body (10-10000 chars).

• contact_email: optional reply-to address; defaults to no reply-to.

• metadata: optional extra key/value pairs (16 keys max, 200 char values max). Merged on top of the auto-attached environment dict.

Output: dict with success, submission_id (when 200), error (when non-200), status_code (HTTP status or 0 on validation/transport error), and metadata_attached (the dict actually sent so you can audit it locally).

Never raises — transport and validation failures are reported in the error field.

Probe the five compounding-pipeline signals (sync_push, graph_edges, embedding_coverage, recall_feedback, bandit_state). Returns a structured report with degraded flag and advisory.

Use when:

• trw_session_start returns a pipeline_health_advisory and you need the full per-signal breakdown to diagnose which subsystem is degraded.

• Performing a routine operator health check outside of ceremony.

Checks: sync_push (consecutive_failures + last_push_at age), graph_edges (knowledge graph empty?), embedding_coverage (< 10%?), recall_feedback (all recall_count=0?), and bandit_state (mtime stale?).

Returns a structured report with:

• degraded: True if any signal is degraded.

• advisory: Compact single-line string naming degraded signals.

• Per-signal sub-dicts with detailed status.

All probes are read-only and fail-open individually.

Run a bounded, sandboxed experiment to resolve a disputed plan assumption.

Use when, during the PLAN phase, two plan branches disagree on a load-bearing, empirically resolvable claim a rubric cannot adjudicate (e.g. "this parser handles a 50MB JSONL stream without OOM"). The command runs inside the shared SAFE-001 sandbox (subprocess + seccomp + no-network default), bounded by timeout_s and memory_mb, and a typed ProbeResult with verdict in {supports, refutes, inconclusive} comes back.

Budget is enforced per planning_mode (DIRECT=0, DUAL_DRAFT=1, TRIANGULATED=2, TRIANGULATED_WITH_PROBE=3); exhaustion returns a typed budget error. Identical probes within a run are served from cache.

Returns: dict serialization of ProbeResult (or a typed error dict on validation failure / budget exhaustion / feature-flag disabled).

Report live probe budget usage for a session (read-only, FR-10).

Use when you need to detect runaway probe usage before it becomes cost/latency creep. Returns {used, remaining, total, planning_mode, by_hypothesis_id, by_mode} consistent with emitted ProbeEvents in the same run. Read-only — never mutates budget state.

Explain the resolved profile's per-field layer attribution.

Use when:

• A surprising ceremony/review/build-check gate fires and you need to see WHICH layer contributed the offending value.

• Auditing the policy in force for the session (NIST 24h reconstruction).

Resolves the full 6-layer chain (defaults → org → domain → task-type → session → client) and reports, for every surface field, its effective value, the origin layer, and the full override chain.

Input (all optional — inferred when omitted):

• domain: override the inferred domain layer (e.g. frontend).

• task_type: override the inferred task-type layer (e.g. bugfix).

• prd_path: PRD/file path used to infer the domain when not explicit.

• task_name: task name used to infer the task-type when not explicit.

Output: dict with fields (list of {field, value, origin_layer, override_chain}), layers_applied, surface_snapshot_id, session_override_hash, and resolved_profile. On error: a {error: str} payload (fail-open, never raises).

Grant this session single-use access to a phase-masked tool.

Use when a genuine cross-phase or emergency-debug need requires a tool the current phase masks — and only then, since every grant is logged to telemetry. The grant is single-use (one subsequent call) and the TTL is capped at 5 minutes regardless of ttl_seconds.