=== behavioral_protocol ===
# TRW Behavioral Protocol

## TRW Behavioral Protocol (Auto-Generated)

| Tool | When | Why |
|------|------|-----|
| `trw_session_start()`<br><sub>e.g. `trw_session_start(query='task domain')`</sub> | First action — loads prior learnings + recovers active run state | Start from accumulated knowledge instead of zero — prior agents already found gotchas for your area |
| `trw_learn(summary, detail)`<br><sub>e.g. `trw_learn(summary='...', impact=0.8)`</sub> | On errors, discoveries, or gotchas | Saves your finding so no future agent repeats your mistake — this is how institutional knowledge grows |
| `trw_checkpoint(message)`<br><sub>e.g. `trw_checkpoint(message='...')`</sub> | After milestones — preserves progress across context compactions | Preserves material unfinished work; a durable native handoff with a next-read pointer is also valid |
| `trw_deliver()` | For completed-work acceptance under the delivery gates | Recorded learnings already persist; unfinished work does not require delivery |

Full tool lifecycle: `/trw-ceremony-guide`


### Execution Phases

```
RESEARCH → PLAN → IMPLEMENT → VALIDATE → REVIEW → DELIVER
```

- **RESEARCH**: Discover context, audit codebase, register findings
- **PLAN**: Design implementation approach, identify dependencies
- **IMPLEMENT**: Execute work with periodic checkpoints, shard self-review before completing
- **VALIDATE**: Run trw_build_check, verify coverage, lead checks shard integration
- **REVIEW**: Review diff for quality (DRY/KISS/SOLID), fix gaps, record learnings
- **DELIVER**: Sync artifacts, checkpoint, close run


### Tool Lifecycle

Call `trw_skill_discovery()` for the live tool and skill surface, and `trw_status()` for the phase you are in and what it expects next. Both read the running server, so neither can drift from what is actually exposed to you.


### Completed-work Flows (delivery gates apply)

**Quick Task** (no run needed):
```
trw_session_start -> work -> trw_learn (if discovery) -> trw_deliver()
```

**Full Run**:
```
trw_session_start -> trw_init(task_name, prd_scope)
  -> work + trw_checkpoint (periodic) + trw_learn (discoveries)
  -> trw_build_check(tests_passed=<bool>, test_count=<n>, failure_count=<n>, static_checks_clean=<bool|null>, scope='<exact command>') [VALIDATE]
  -> review diff, fix gaps, trw_learn         [REVIEW]
  -> trw_deliver()
```


### Framework Reference

Read `.trw/frameworks/FRAMEWORK.md` at session start — it defines phase gates, exit criteria, quality rubrics, and formation selection. Re-read after context compaction.


## TRW Delegation & Orchestration (Auto-Generated)

As orchestrator, your responsibilities are: (1) assess and decompose tasks, (2) use focused helpers only when the active harness supports them, (3) verify integration and quality, (4) maintain strategic oversight, and (5) preserve knowledge via TRW tools. Direct implementation is reserved for small or tightly coupled edits.

### When to Delegate

```
Task arrives → Assess scope and harness
├── Trivial or tightly coupled?   → Self-implement with checkpoint
├── Research/read-only?           → Focused helper if available; otherwise sequential shard
├── Single-scope? (≤3 files)      → One helper or one local pass
├── Multi-scope? (4+ files)       → Split by explicit file ownership
└── Interdependent/high-risk?     → Plan contracts first, then implement/review in stages
```

Delegation is optional. The invariant is focused context, explicit file ownership, persisted findings, and final integration by the orchestrator. If the client has no safe delegation surface, execute the same shards sequentially in the current session.


<!-- trw:lifecycle-sync:sha256-ac9a7444faf4 -->

## TRW Governance (non-negotiable)

Call `trw_session_start()` first.

## Deliver Gate (v26.2)

Do NOT call `trw_deliver` unless at least one of:
- (a) `trw_build_check` reported `tests_passed=true` and `static_checks_clean=true` (or omitted), with a non-zero `test_count` and a non-empty `scope`, **or**
- (b) `allow_unverified=true` and `unverified_reason` contains a valid, unexpired
  acceptable-failure record with `failed_command`, `residual_risk`, `owner`, and
  `expiry_iso`, **or**
- (c) an authorized operator/config override is recorded with technical rationale.

A review-verdict label or free-text reason alone is not an acceptable-failure record.
Under the default `deliver_gate_mode: block_coding` a missing build check blocks when the task type expects a build artifact (`coding`, `rca`, `eval`) OR when the session recorded modifications to at least `deliver_gate_unclassified_change_threshold` distinct files — so an unclassified or misclassified run that changed code still blocks. A run that modified nothing surfaces the missing-build warning as an advisory without requiring an exception record.

### Session Boundaries

Preserve material unfinished work via checkpoint or durable native handoff + next-read pointer. Nothing material to preserve: no artifacts. trw_deliver is completed-work acceptance under unchanged gates; recorded learnings already persist.

### Troubleshooting: the MCP surface is absent

If the `trw_*` tools are missing or fail (`fetch failed`, a connect timeout, an
empty tool list), every obligation still binds — RIGID names an OBLIGATION, not a
tool call. Use the offline substitute:

| Obligation | Offline substitute |
|---|---|
| `trw_session_start` | `trw-mcp local status`, then `trw-mcp local recall --query "<domain>"` |
| `trw_init` | `trw-mcp local init --task NAME` |
| `trw_checkpoint` | `trw-mcp local checkpoint --message MSG` |
| `trw_learn` | `trw-mcp local learn --summary S --detail D --tag T` |
| `trw_recall` | `trw-mcp local recall --query Q` |
| `trw_build_check` | run the project-native check yourself, then write the exact command string and its integer exit code into the active run's `reports/` directory |
| `trw_deliver` (completed-work acceptance only) | `trw-mcp local deliver --message MSG` — records `gate_evaluated: false`, which is an UNGATED delivery; the gate above still binds until evidence exists |
| Feedback | `trw-mcp local feedback --category C --subject S --message M` |

Writes made offline are marked (`source_identity=local_cli` plus a transient
`trw-reconcile-pending` tag) and the next successful `trw_session_start` reports
them back, so you do not have to track them by hand.


=== ceremony_quick_ref ===
## TRW Behavioral Protocol (Auto-Generated)

| Tool | When | Why |
|------|------|-----|
| `trw_session_start()`<br><sub>e.g. `trw_session_start(query='task domain')`</sub> | First action — loads prior learnings + recovers active run state | Start from accumulated knowledge instead of zero — prior agents already found gotchas for your area |
| `trw_learn(summary, detail)`<br><sub>e.g. `trw_learn(summary='...', impact=0.8)`</sub> | On errors, discoveries, or gotchas | Saves your finding so no future agent repeats your mistake — this is how institutional knowledge grows |
| `trw_checkpoint(message)`<br><sub>e.g. `trw_checkpoint(message='...')`</sub> | After milestones — preserves progress across context compactions | Preserves material unfinished work; a durable native handoff with a next-read pointer is also valid |
| `trw_deliver()` | For completed-work acceptance under the delivery gates | Recorded learnings already persist; unfinished work does not require delivery |

Full tool lifecycle: `/trw-ceremony-guide`


=== phase_descriptions ===
### Execution Phases

```
RESEARCH → PLAN → IMPLEMENT → VALIDATE → REVIEW → DELIVER
```

- **RESEARCH**: Discover context, audit codebase, register findings
- **PLAN**: Design implementation approach, identify dependencies
- **IMPLEMENT**: Execute work with periodic checkpoints, shard self-review before completing
- **VALIDATE**: Run trw_build_check, verify coverage, lead checks shard integration
- **REVIEW**: Review diff for quality (DRY/KISS/SOLID), fix gaps, record learnings
- **DELIVER**: Sync artifacts, checkpoint, close run


=== ceremony_table ===
### Tool Lifecycle

| Phase | Tool | When to Use | What It Does | Example |
|-------|------|-------------|--------------|---------|
| Start | `trw_session_start` | First action — loads prior learnings + recovers active run state | Start from accumulated knowledge instead of zero — prior agents already found gotchas for your area | `trw_session_start(query='task domain')` |
| Start | `trw_recall` | Quick tasks — retrieves relevant prior learnings without a full run | Surface discoveries from past sessions so you don't repeat solved problems | `trw_recall('auth patterns', min_impact=0.7)` |
| Start | `trw_status` | When resuming — shows current phase, progress, and next steps | Pick up where you left off instead of redoing completed work | `trw_status()` |
| RESEARCH | `trw_init` | New structured tasks — creates run directory for tracking | Enables run checkpoints; a durable native handoff can preserve work without creating a run | `trw_init(task_name='...')` |
| Any | `trw_learn` | On errors, discoveries, or gotchas | Saves your finding so no future agent repeats your mistake — this is how institutional knowledge grows | `trw_learn(summary='...', impact=0.8)` |
| Any | `trw_checkpoint` | After milestones — preserves progress across context compactions | Preserves material unfinished work; a durable native handoff with a next-read pointer is also valid | `trw_checkpoint(message='...')` |
| PLAN | `trw_prd_create` | When defining requirements for a new feature or fix | Ambiguous requirements are the cheapest defect to fix in spec and the most expensive in code | `trw_prd_create(input_text='...')` |
| PLAN | `trw_prd_validate` | Before implementation begins | Catches requirement gaps before they become code bugs — cheaper to fix in spec than in code | `trw_prd_validate(prd_path='...')` |
| VALIDATE | `trw_build_check` | After implementation and before delivery | Catches failures before delivery — a failure found after delivery cascades into multi-file rework | `trw_build_check(tests_passed=<bool>, test_count=<n>, failure_count=<n>, static_checks_clean=<bool|null>, scope='<exact command>')` |
| REVIEW | `review diff` | After VALIDATE — check quality (DRY/KISS/SOLID), fix gaps, record learnings | Independent review catches what self-review misses — implementers optimize for completion, reviewers for correctness | `Read diff, fix gaps, trw_learn(summary='...')` |
| DELIVER | `trw_instructions_sync` | At delivery | Refreshes the client's instruction file (CLAUDE.md / AGENTS.md / etc.) so every future session starts with your best insights | `trw_instructions_sync()` |
| DELIVER | `trw_deliver` | For completed-work acceptance under the delivery gates | Recorded learnings already persist; unfinished work does not require delivery | `trw_deliver()` |


=== ceremony_flows ===
### Completed-work Flows (delivery gates apply)

**Quick Task** (no run needed):
```
trw_session_start -> work -> trw_learn (if discovery) -> trw_deliver()
```

**Full Run**:
```
trw_session_start -> trw_init(task_name, prd_scope)
  -> work + trw_checkpoint (periodic) + trw_learn (discoveries)
  -> trw_build_check(tests_passed=<bool>, test_count=<n>, failure_count=<n>, static_checks_clean=<bool|null>, scope='<exact command>') [VALIDATE]
  -> review diff, fix gaps, trw_learn         [REVIEW]
  -> trw_deliver()
```


=== framework_reference ===
### Framework Reference

Read `.trw/frameworks/FRAMEWORK.md` at session start — it defines phase gates, exit criteria, quality rubrics, and formation selection. Re-read after context compaction.


=== closing_reminder ===
<!-- trw:lifecycle-sync:sha256-ac9a7444faf4 -->

## TRW Governance (non-negotiable)

Call `trw_session_start()` first.

## Deliver Gate (v26.2)

Do NOT call `trw_deliver` unless at least one of:
- (a) `trw_build_check` reported `tests_passed=true` and `static_checks_clean=true` (or omitted), with a non-zero `test_count` and a non-empty `scope`, **or**
- (b) `allow_unverified=true` and `unverified_reason` contains a valid, unexpired
  acceptable-failure record with `failed_command`, `residual_risk`, `owner`, and
  `expiry_iso`, **or**
- (c) an authorized operator/config override is recorded with technical rationale.

A review-verdict label or free-text reason alone is not an acceptable-failure record.
Under the default `deliver_gate_mode: block_coding` a missing build check blocks when the task type expects a build artifact (`coding`, `rca`, `eval`) OR when the session recorded modifications to at least `deliver_gate_unclassified_change_threshold` distinct files — so an unclassified or misclassified run that changed code still blocks. A run that modified nothing surfaces the missing-build warning as an advisory without requiring an exception record.

### Session Boundaries

Preserve material unfinished work via checkpoint or durable native handoff + next-read pointer. Nothing material to preserve: no artifacts. trw_deliver is completed-work acceptance under unchanged gates; recorded learnings already persist.

### Troubleshooting: the MCP surface is absent

If the `trw_*` tools are missing or fail (`fetch failed`, a connect timeout, an
empty tool list), every obligation still binds — RIGID names an OBLIGATION, not a
tool call. Use the offline substitute:

| Obligation | Offline substitute |
|---|---|
| `trw_session_start` | `trw-mcp local status`, then `trw-mcp local recall --query "<domain>"` |
| `trw_init` | `trw-mcp local init --task NAME` |
| `trw_checkpoint` | `trw-mcp local checkpoint --message MSG` |
| `trw_learn` | `trw-mcp local learn --summary S --detail D --tag T` |
| `trw_recall` | `trw-mcp local recall --query Q` |
| `trw_build_check` | run the project-native check yourself, then write the exact command string and its integer exit code into the active run's `reports/` directory |
| `trw_deliver` (completed-work acceptance only) | `trw-mcp local deliver --message MSG` — records `gate_evaluated: false`, which is an UNGATED delivery; the gate above still binds until evidence exists |
| Feedback | `trw-mcp local feedback --category C --subject S --message M` |

Writes made offline are marked (`source_identity=local_cli` plus a transient
`trw-reconcile-pending` tag) and the next successful `trw_session_start` reports
them back, so you do not have to track them by hand.


