# Task: [RELS.2002]: Implement UpdateRelationshipTool

## Status
- [x] **Task completed** - acceptance criteria met
- [x] **Tests pass** - tests executed and passing (or N/A if no tests)
- [x] **Verified** - by the verify-task agent

**Note on "Tests pass"**:
- If tests were created/modified, you MUST run them and show output
- "Tests pass" means tests were EXECUTED and all passed
- "Tests pass - N/A" is only valid for documentation-only tickets
- Test file existence alone does NOT satisfy this requirement

## Agents
- implement-feature
- unit-test-runner
- verify-task
- commit-task

## Summary
Implement the `update_relationship` tool to add lookup and summary fields to existing relationships. This tool is ADDITIVE ONLY - it will not delete existing fields.

## Background
This tool enhances existing relationships by adding new lookup or summary fields. It's critical that agents understand this is additive only - fields can only be removed by using separate field deletion tools. The tool description must clearly state "ADDITIVE ONLY" to prevent confusion.

This completes Phase 2 from plan.md: Write Operations - Create and Update.

## Acceptance Criteria
- [x] Tool name is `update_relationship` (snake_case)
- [x] Tool extends BaseTool with proper TypeScript types
- [x] Adds lookup fields to existing relationships
- [x] Adds summary fields to existing relationships
- [x] JSON Schema conditional validation: summary_accumulation_type required when summary_field_id provided
- [x] Tool description clearly states "ADDITIVE ONLY"
- [x] Tool description explains how to remove fields (use field deletion tools)
- [x] Tool registered in relationships/index.ts
- [x] Unit tests cover additive behavior and all error scenarios
- [x] All tests pass with `npm test`

## Technical Requirements
- Endpoint: POST `/tables/{tableId}/relationships/{relationshipId}`
- Parameters similar to create_relationship but require relationship_id
- Support adding lookup_field_ids
- Support adding summary field with accumulation type
- Conditional validation: summary_accumulation_type required if summary_field_id provided
- Return updated relationship structure
- Does NOT delete existing fields (API behavior, verify in tests)

## Implementation Notes
From architecture.md:

```typescript
interface UpdateRelationshipParams {
  table_id: string;              // Required: Child table ID
  relationship_id: number;       // Required: Relationship ID (foreign key field ID)
  lookup_field_ids?: number[];   // Optional: Additional parent field IDs for lookups
  summary_field_id?: number;     // Optional: Child field ID to summarize
  summary_label?: string;        // Optional: Label for summary field
  summary_accumulation_type?: string;  // Required if summary_field_id
  summary_where?: string;        // Optional: Quickbase query filter
}

interface UpdateRelationshipResult {
  id: number;
  parentTableId: string;
  childTableId: string;
  foreignKeyField: FieldInfo;
  lookupFields: FieldInfo[];
  summaryFields: FieldInfo[];
}
```

JSON Schema must use same conditional validation as create_relationship:
```typescript
if: {
  properties: { summary_field_id: { type: 'number' } },
  required: ['summary_field_id']
},
then: {
  required: ['summary_accumulation_type']
}
```

Tool description (from architecture.md):
```
Adds lookup fields and/or summary fields to an existing relationship. This operation
is ADDITIVE ONLY - it will not delete existing lookup or summary fields. Use this to
enhance relationships with additional calculated fields. To remove fields from a
relationship, you must delete them individually using the field deletion tools.
```

## Dependencies
- RELS.1001 - Domain setup complete
- RELS.2001 - CreateRelationshipTool provides pattern for summary validation
- Existing: Field deletion tools (mentioned in description)

## Risk Assessment
- **Risk**: Agents expect update to replace fields instead of adding
  - **Mitigation**: Clear "ADDITIVE ONLY" in description; test and document behavior
- **Risk**: Adding fields that already exist
  - **Mitigation**: Handle API response appropriately; test edge case
- **Risk**: Empty update (no fields to add)
  - **Mitigation**: Allow but may be no-op; test and document behavior

## Files/Packages Affected
- src/tools/relationships/update_relationship.ts (new file)
- src/tools/relationships/index.ts (update exports and registration)
- src/__tests__/tools/relationships.test.ts (extend tests)

## Deliverables Produced

Documents created in `deliverables/` directory:

- None

## Verification Notes
Verify-task agent should confirm tests cover all critical paths from quality-strategy.md:

Happy Path:
- Add lookup fields to existing relationship
- Add summary field to existing relationship
- Add both lookup and summary fields

Error Cases:
- Relationship not found
- Invalid lookup field IDs
- Missing accumulation type when summary_field_id provided (validated by JSON Schema)

Edge Cases:
- Adding fields that already exist (verify additive behavior)
- Empty update (no fields to add)

Verify conditional validation works:
- Providing summary_field_id without summary_accumulation_type MUST fail validation

Verify additive behavior:
- Adding new lookup fields doesn't remove existing ones
- Adding summary field doesn't affect existing lookups
- Result includes ALL fields (existing + newly added)

## Verification Audit
<!-- Audit log maintained by verify-task agent for enterprise compliance -->
| Date | Agent | Decision | Notes |
|------|-------|----------|-------|
| 2025-12-28 | verify-task | PASS | All 10 acceptance criteria met, 143 tests passing, 100% coverage on relationships tools |