# Boundary sync and status mapping (v1)

**Status:** normative for ISSUE-WP-0005  
**Date:** 2026-07-22  
**Implements:** INTENT “Boundary sync discipline”  
**Related:** `docs/uuid-external-id-mapping.md`, `issue_core/core/mapping.py`

## Principles

1. Fleet **work-record `status`** and tracker **`IssueState`** are distinct
   vocabularies. Never treat them as the same enum.
2. **v1 is outward-only.** Operators (or automation) call
   `issue map push-status` with a work-record status; issue-core updates the
   external issue. Inward sync does **not** write work-record files.
3. **Lane, tags, budgets** stay on the work record. Projections may carry
   title, body, and agreed labels only.
4. Unmapped backend issues are **outside** the work-record spine.

## Mapping keys

| Side | Key |
| --- | --- |
| Work record | **UUIDv7** (bookkeeping); canonical id optional denorm for UX |
| External | `(backend, external_id)` where backend is `sqlite` \| `gitea` \| … |

## Outward status table (task kind + pass-through)

| Work-record / input status | Tracker `IssueState` |
| --- | --- |
| `wait` | `open` |
| `todo` | `open` |
| `progress` | `in_progress` |
| `done` | `closed` |
| `cancel` | `closed` |
| `open` | `open` (pass-through) |
| `in_progress` | `in_progress` |
| `blocked` | `blocked` |
| `closed` | `closed` |

Other kinds (intake, decision, …) should not use this table until kind-
specific rules are added. Prefer projecting only after promotion to `task`
when unsure.

## Fields

| May project outward | Stay on work record only |
| --- | --- |
| title, description/body | `lane` |
| labels agreed for external collab | policy/derived `tags` |
| tracker state (via table above) | budgets / token envelopes |
| comments (future) | owner spine identity (`agt-…`) |

## CLI

```bash
issue map push-status --uuid <work-record-uuid> --status progress
issue map push-status --id ISSUE-WP-0005-T07 --status done
```

## Non-goals (v1)

- Silent mutation of ADR-001 work-record files from tracker webhooks
- Full comment CRDT merge
- Multi-backend active mappings per UUID (one active per backend)

## Implementation

- Policy function: `map_work_record_status_to_issue_state()` in
  `issue_core/core/mapping.py`
- CLI: `issue map push-status`