# Hamster Sync Local Testing

> Local testing runbook for validating Linear, Jira, and Confluence sync against the local dev stack. MUST USE this skill whenever testing sync behavior locally, debugging sync issues, verifying sync after code changes, running sync test scenarios, checking sync connections/webhooks/mappings, triggering resync, testing team switches, or verifying provider-to-Hamster state agreement. Also use when inspecting tmux logs for sync, querying sync_entity_mappings, diagnosing initiative/brief/task/blueprint sync problems, validating the Jira personal data reporting cycle (report-accounts cadence, 429 handling, PII scrubbing on closed/updated actions, reserved \"unknown\" accountId), or testing the Confluence reconciliation-only inbound path, root-page bootstrap, OAuth scope drift / reauth_required flagging, space-picker scope, page ancestry under root, hamster label scope, storage-format ↔ markdown conversion, or retained `cloud_id + space_id` identity across reconnect.

- Skill: `gethamster/hamster-sync-local-testing` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx get-skill add gethamster/hamster-sync-local-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gethamster/hamster-sync-local-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: gethamster (https://skillmd.com/u/gethamster)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/gethamster/hamster-sync-local-testing

---


# Sync Service Local Testing

Canonical runbook for validating Linear, Jira, and Confluence sync against the real local
stack. Use tmux logs, Supabase state, sync API calls, and direct provider queries together
to verify runtime behavior.

Provider-shape cheatsheet:

| Provider | Inbound channel | Outbound trigger | Entities | Identity key |
| --- | --- | --- | --- | --- |
| Linear | Per-connection webhook | DB trigger → outbox | initiative/project/issue → initiative/brief/task | `workspace_id` (+ team) |
| Jira | Static webhook + token | DB trigger → outbox | epic/issue/subtask → brief/task | `cloud_id + project_id` |
| Confluence | Periodic reconciliation (no webhook) | DB trigger `enqueue_blueprint_confluence_page_change` → outbox | page → blueprint document | `cloud_id + space_id` |

## Quick Reference

| Task | How | Reference |
| --- | --- | --- |
| Get local JWT + account ID | Auth setup flow | [auth-setup.md](references/auth-setup.md) |
| Get provider OAuth token | Vault query | [auth-setup.md](references/auth-setup.md) |
| Check sync connection state | SQL queries | [sql-queries.md](references/sql-queries.md) |
| Check entity mappings | SQL queries | [sql-queries.md](references/sql-queries.md) |
| Trigger resync / team switch / delete | curl commands | [api-commands.md](references/api-commands.md) |
| Query Linear entities directly | GraphQL | [linear-queries.md](references/linear-queries.md) |
| Query Jira entities directly | REST | [jira-queries.md](references/jira-queries.md) |
| Query Confluence pages/spaces directly | REST V2 | [confluence-queries.md](references/confluence-queries.md) |
| Verify Jira personal data reporting cadence | SQL + BullMQ trigger | [sql-queries.md](references/sql-queries.md) |
| Force Confluence reconciliation now | BullMQ enqueue or env tick | [confluence-queries.md](references/confluence-queries.md) |
| Validate mention / mark / formatting / special-character survival across the round-trip | Force-resync trick + native payload curl + Yjs decode | [content-validation.md](references/content-validation.md) |
| Seed a brief with the canonical all-elements demo doc | Browser-console editor `setContent` snippet | [full-content-seed.md](references/full-content-seed.md) |
| Run E2E test scenarios | Checklists below | This file |

## Branch-Aware Test Planning

Before running any scenario, analyze the current branch to build a targeted test plan.
The goal is to focus testing time on the code paths that actually changed, rather than
blindly running every scenario.

### Step 1: Identify what changed

```bash
git log --oneline dev..HEAD
git diff dev --stat
git diff dev --name-only
```

If the branch has no divergence from `dev`, try `main` instead.

### Step 2: Classify the changes

Read the changed files and diffs. Map each change to a sync domain:

| Change area | Relevant scenarios |
| --- | --- |
| `sync.orchestrator.ts`, inbound/outbound consumers | Initiative 2-Way Sync, Baseline & Resync |
| `sync-connections.controller.ts`, connection lifecycle | Team Switch, Delete-Recreate, Baseline |
| `context-connections.service.ts`, retained sync re-link logic | Delete-Recreate, Team Switch and Switch Back |
| Initiative-related mappers, `initiative_briefs` triggers | Initiative 2-Way Sync |
| `webhook.consumer.ts`, `linear-provider-scope-evaluator.ts` | Initiative 2-Way Sync, Workspace-Scoped Filter Checks |
| `webhooks/jira-webhook.controller.ts`, `jira-site-webhook-manager.service.ts` | Jira Baseline & Routing, Jira Scope & Webhook Auth |
| `adapters/jira/*`, `jira-provider-scope-evaluator.ts` | Jira Epic/Issue/Subtask 2-Way Sync, Jira Scope Drift |
| `jira-personal-data-reporting.consumer.ts`, `jira-personal-data-reporting.repository.ts`, `JiraAdapter.reportPersonalData` | Jira Personal Data Reporting |
| `user-mappings.repository.ts` PII handling, `user-mapping-refresh.consumer.ts` | Jira Personal Data Reporting |
| Jira status/field mapping bootstrap | Jira Epic/Issue/Subtask 2-Way Sync |
| `adapters/confluence/confluence.adapter.ts`, `confluence.api-client.ts` | Confluence Blueprint 2-Way Sync, Confluence Reauth |
| `confluence-root-page-bootstrap.ts`, `confluence-root-page-manager.ts` | Confluence Root Page Bootstrap |
| `confluence-provider-scope-evaluator.ts`, hamster label / app property handling | Confluence Scope and Out-of-Scope Drift |
| `confluence.conversion.ts`, storage-format macros | Confluence Content Conversion |
| `SyncEngineService.ensureConfluenceReconciliationSchedule`, `ReconciliationConsumer` Confluence branch | Confluence Reconciliation Cadence |
| `reviveRetainedConfluenceConnectionIfPresent`, `cloud_id + space_id` retained identity SQL | Confluence Delete-Recreate / Same-Space Reconnect |
| Migration `*_confluence-sync.sql`, `enqueue_blueprint_confluence_page_change` trigger | All Confluence scenarios |
| Webhook controller, webhook registration | Baseline & Resync, Team Switch |
| Reconciliation consumer, resync logic | Baseline & Resync |
| `apply_inbound_brief_insert`, `sync_entity_mappings`, reconnect migrations | Delete-Recreate, Baseline & Resync |
| Migration files, schema changes | All scenarios (schema changes affect everything) |
| Outbox triggers, document polling | Local -> provider sync |
| Vault, credentials, OAuth | Auth setup only (verify token retrieval works) |
| `core/document-sync.adapter.ts`, `merge/text-delta-merge.ts`, `shared/services/yjs-document.service.ts` | Content & Formatting Validation (see [content-validation.md](references/content-validation.md)) |
| `packages/shared/src/documents/conversion/adf/*`, `adapters/linear/linear-pm-converter.ts` | Content & Formatting Validation |
| Per-provider native-wire flags (`ENABLE_JIRA_NATIVE_ADF_*`, `ENABLE_CONFLUENCE_NATIVE_STORAGE_*`, `ENABLE_LINEAR_NATIVE_PM_*`) | Content & Formatting Validation |

### Step 3: Build the test plan

Based on the classification:

1. **Always run Scenario 1 (Baseline & Resync)** - it's the health check that catches regressions in any area
2. Add scenarios that map to the changed code paths
3. If a migration was added, run all scenarios - schema changes have broad blast radius
4. Present the plan to the user before executing

Provider mapping shortcut:

- Linear changes usually imply Scenarios 2, 3, 4, 5, and 7
- Jira changes usually imply Scenarios 8, 9, and 10
- Jira user-mapping or personal-data-reporting changes imply Scenario 11
- Confluence changes usually imply Scenarios 12, 13, 14, and 15
- Confluence OAuth scope, refresh, or 401/403 handling changes imply Scenario 16

### Fallback: when the branch is unclear

If the diff is empty, the changes don't touch sync code, or you can't confidently map
changes to scenarios, fall back to the provider-specific default plan:

**Linear default plan**

1. Baseline & Resync
2. Linear Delete-Recreate
3. Linear Initiative 2-Way Sync (both directions)
4. Linear Team Switch and Switch Back
5. Linear Workspace-Scoped Filter Checks

**Jira default plan**

1. Baseline & Resync
2. Jira Epic / Issue / Subtask 2-Way Sync
3. Jira Delete-Recreate / Same-Project Reconnect
4. Jira Scope Drift and Label Loss

**Confluence default plan**

1. Baseline & Resync (still relevant — Confluence connections use the same `sync_connections` row, resync re-baselines hashes)
2. Confluence Root Page Bootstrap
3. Confluence Blueprint 2-Way Sync (page <-> document)
4. Confluence Scope and Out-of-Scope Drift
5. Confluence Delete-Recreate / Same-Space Reconnect
6. Confluence Reauth on Scope / Credential Failure (if OAuth code changed)

This is also the right plan when the user says "just test everything" or doesn't specify.

---

## Prerequisites

Before starting, confirm:

- Local stack is running in a persistent tmux `dev` session via `pnpm dev:with-sync`
- **Cloudflare tunnel is running** so provider webhooks can reach the local stack. Without a tunnel, inbound webhook events cannot arrive and you will be forced to rely on resync, which masks real bugs. Verify by checking the webhook URL on the active sync connection points to a live `*.trycloudflare.com` domain.
- If the current branch added DB changes, local migrations are already applied
- You have a team account ID for the workspace under test
- An active sync connection exists with valid provider OAuth credentials in Vault
- If you are validating workspace-scoped webhook filtering, a second Linear team in the same workspace must exist
- If you are validating Jira scope behavior, the selected Jira project must contain both hamster-labeled and non-hamster epics
- If you are validating Confluence sync, verify `ENABLE_CONFLUENCE_TWO_WAY_SYNC=true` and `SYNC_CONFLUENCE_RECONCILIATION_ENABLED=true` reached the running sync process (tmux startup logs). The same selected Confluence space must contain at least one page eligible for the hamster scope (descendant of the Hamster root) and one non-hamster page outside the root

Recommended baseline test fixture:

- One active Linear sync connection for the account
- At least one synced task
- At least one synced brief/project
- At least one synced initiative linked through `initiative_briefs`

Recommended Jira-specific fixture:

- One active Jira sync connection for the selected `cloud_id + project_id`
- At least one hamster-labeled Jira epic already mapped to a Hamster brief
- At least one Jira issue under that epic and at least one subtask under that issue
- At least one Jira epic without the `hamster` label to validate out-of-scope behavior

Recommended Confluence-specific fixture:

- One active Confluence sync connection for the selected `cloud_id + space_id`
- `provider_config.config.root_page_id` is populated (root page already bootstrapped); if it is null, expect bootstrap-on-first-tick behavior and validate that path explicitly
- At least one Hamster-managed page under the root (has `hamster` label and stamped `hamster.managed=true` app property) already mapped to a local blueprint document
- At least one page in the same space that lives outside the Hamster root or lacks the hamster label — must stay out of scope across reconciliations
- Provider OAuth credentials grant the full Confluence scope set (`read:page:confluence`, `write:page:confluence`, `delete:page:confluence`, `read:space:confluence`, `read:content.metadata:confluence`, `offline_access`). If scopes drift or are missing, `reauth_required=true` is the expected response on the first failed operation, not a silent skip

If the stack is not running, start it in a persistent tmux session:

```bash
tmux new-session -d -s dev 'pnpm dev:with-sync'
```

If local schema is behind the branch:

```bash
pnpm --filter web supabase db push --local
```

## Local Topology

- Proxy: `http://127.0.0.1:8080` (preferred for all API calls)
- Web app direct: `127.0.0.1:3000`
- Local Supabase API: `127.0.0.1:54321`
- Local Postgres: `127.0.0.1:54322`

Sync routes live under `/sync/v1/...`:

- `POST /sync/v1/connections/:id/resync`
- `PATCH /sync/v1/connections/:id`
- `DELETE /sync/v1/connections/:id`
- `POST /sync/v1/connections/:id/enable`
- `POST /sync/v1/connections/:id/disable`
- `POST /sync/v1/webhooks/linear/:accountId/:connectionId`
- `POST /sync/v1/webhooks/jira`

Confluence has no webhook route. Inbound arrives via the periodic `sync-reconciliation` BullMQ
queue. The repeat job id is `sync-confluence-reconciliation-repeat`, scheduled by
`SyncEngineService.ensureConfluenceReconciliationSchedule` at
`SYNC_CONFLUENCE_RECONCILIATION_INTERVAL_MS` (default 10 minutes). Outbound starts from the
`enqueue_blueprint_confluence_page_change` Postgres trigger on `document` mutations.

## Cold-Start Orientation

If starting from empty context, anchor with these facts:

- `apps/sync` owns webhook ingress, queue consumers, reconciliation, and sync API routes
- Local writes enqueue outbound work through DB triggers and outbox processing
- Inbound sync (provider -> Local) arrives via webhooks through the Cloudflare tunnel - this is the main channel and must be tested directly
- Resync (`/sync/v1/connections/:id/resync`) is for re-baselining hashes and verifying idempotency, not for testing the inbound path

Provider-specific ingress rules:

- Linear uses a per-connection webhook route and direct GraphQL verification.
- Jira uses the static `/sync/v1/webhooks/jira` endpoint, validates a stored webhook token, and routes events by `site_url + project_id`.
- Jira scope is stricter than project membership alone: only hamster-labeled epics import as briefs, and only issues/subtasks linked to those epics through parentage or epic-link custom fields import as tasks.
- Confluence has **no webhook channel** — Atlassian Cloud does not expose one for OAuth apps. Inbound runs entirely through periodic reconciliation (default 10 min) and on-demand resync. Reconciliation walks the selected space's pages, evaluates scope via hamster label + space + ancestor-under-root, and reconciles `external_version`. Do not invent a webhook test for Confluence — there is no controller.
- Confluence scope is: page lives in the configured `space_id`, page has the `hamster` label, and page sits at or under the bootstrapped root page (`provider_config.config.root_page_id`). Any one missing → out of scope.

Key source files:

- `apps/sync/src/modules/sync-engine/controllers/sync-connections.controller.ts`
- `apps/sync/src/modules/sync-engine/webhooks/linear-webhook.controller.ts`
- `apps/sync/src/modules/sync-engine/webhooks/jira-webhook.controller.ts`
- `apps/sync/src/modules/sync-engine/queues/outbound-sync.consumer.ts`
- `apps/sync/src/modules/sync-engine/queues/reconciliation.consumer.ts`
- `apps/sync/src/modules/sync-engine/sync.orchestrator.ts`
- `apps/sync/src/modules/sync-engine/adapters/jira/jira-provider-scope-evaluator.ts`
- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence.adapter.ts`
- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence.api-client.ts`
- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence-root-page-bootstrap.ts`
- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence-root-page-manager.ts`
- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence-provider-scope-evaluator.ts`
- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence.conversion.ts`
- `apps/sync/src/modules/sync-engine/sync-engine.service.ts` (Confluence reconciliation schedule)
- `packages/supabase/src/vault-connection-credentials.ts`

## Verification Workflow

Every sync test follows this core loop. Do not skip steps.

```
1. Capture tmux BEFORE mutation
2. Run the mutation (API call, DB update, provider change)
3. Wait for the webhook or outbox processing to fire (check tmux)
4. Capture tmux AFTER mutation
5. Verify local DB state
6. Verify remote provider state
7. Use resync ONLY for hash re-baselining or final idempotency checks
```

**Webhooks are the main channel for Linear and Jira.** Inbound sync (provider -> Local) arrives
via webhooks through the Cloudflare tunnel. When testing inbound changes for Linear or Jira,
mutate on the provider and wait for the webhook to arrive naturally. Check tmux for the
relevant webhook controller (`LinearWebhookController` or `JiraWebhookController`) and
`InboundSyncConsumer` log lines to confirm the webhook was received and processed. Do not
substitute resync for webhook testing - resync uses the reconciliation path which bypasses
the real-time change detection and can mask bugs (e.g. hash-match field mismatches that
silently drop webhook updates while reconciliation still works).

**Confluence has no webhook channel.** Inbound runs entirely through periodic reconciliation
plus on-demand resync. There is no "wait for the webhook" step. The verification loop for
Confluence becomes:

```
1. Capture tmux BEFORE mutation
2. Mutate the page on Confluence (REST V2 or UI)
3. Either wait for the next reconciliation tick OR enqueue a one-shot reconciliation job
4. Capture tmux AFTER reconciliation runs (look for ReconciliationConsumer + ConfluenceAdapter logs)
5. Verify local DB state (document/blueprint row, sync_entity_mappings, sync_logs entry)
6. Re-fetch the Confluence page via REST to confirm round-trip outbound was not stomped
```

For Confluence, resync is *not* a "use only as a final idempotency check" — it is the primary
verification trigger when you cannot wait 10 minutes for the next tick. The trade-off is
opposite to Linear/Jira: there is no separate webhook path to mask, but resync still re-baselines
hashes, so a reconciliation-only bug in scope/conversion will still surface there.

### Tool Priority

Use these in this order - start with the fastest feedback loop:

1. **`mcp__supabase__query`** - fastest way to confirm DB state matches runtime behavior
2. **Direct `curl`** - local auth, sync API calls, Linear GraphQL queries, Jira REST queries
3. **tmux logs** - needed after every major step to confirm processing

Useful tmux commands:

```bash
tmux ls
tmux list-panes -a -F "#{session_name}:#{window_index}.#{pane_index} #{pane_current_command} #{pane_pid} #{pane_title}"
tmux capture-pane -p -t dev:1.1 -S -400
```

Do not use `interactive_bash` for `capture-pane`.

## Auth Setup

Read [auth-setup.md](references/auth-setup.md) for the full flow. Quick summary:

1. Get local Supabase env: `pnpm --filter web supabase status -o env`
2. Get JWT with seeded credentials (`owner@tryhamster.com` / `testingpassword`)
3. Find active sync connection via SQL
4. Get provider OAuth token from `vault.decrypted_secrets`
5. Set shell variables for the provider under test (`LINEAR_TOKEN` or `JIRA_TOKEN`, plus provider-specific IDs)

## Current Data Model

Understanding this is critical for correct verification:

- `initiatives` + linked `document` = canonical initiative entity
- `initiative_briefs` = canonical initiative <-> brief association set
- `brief.initiative_id` is a compatibility shadow only - never treat it as source of truth
- Outbound sync starts from local DB changes and outbox processing, not ad hoc web calls
- Confluence pages map to `document` rows of type `'blueprint'` — not briefs, not tasks. The
  hamster_entity_type in `sync_entity_mappings` for Confluence is `'blueprint'`; the
  external_entity_type is `'page'`. `sync_entity_mappings.external_version` stores the
  numeric Confluence page version for conflict detection
- Confluence connection identity in `provider_config.config` is `{ cloud_id, space_id, space_key, root_page_id, site_url, granted_scope_names }`. `root_page_id` is lazy-bootstrapped on first outbound or first reconciliation; treat a null `root_page_id` as "bootstrap pending", not as an error

## Caveats

- Initiatives are workspace-wide, so team-switch tests can surface workspace-scope behavior
- Bounded initiative queries with nested `projects -> teams` are helpful for debugging but are not complete evidence for very large initiatives
- Linear identifiers do not equal Hamster display IDs
- Outbound brief/project status sync is not canonical - do not assume local brief status changes round-trip to Linear project status
- Jira v1 sync scope is selected project only; hamster-labeled epics become briefs, and standalone Jira issues without a mapped hamster epic brief should stay out of scope
- For linked Jira context connections, relinking the same `cloud_id + project_id` should reuse retained identity; even in other recreate flows, duplicate briefs/tasks after reconnect are still a bug
- Confluence allows N connections per account (1 per `cloud_id + space_id`), unlike Linear/Jira which enforce one-per-account-per-provider. The unique index `idx_sync_connections_one_per_provider_account` exempts Confluence
- Confluence retained identity is `cloud_id + space_id`. `reviveRetainedConfluenceConnectionIfPresent` revives a tombstoned row instead of minting a new one when the same space is reconnected. Same-space reconnect must reuse the prior `sync_entity_mappings` rows — duplicate briefs/blueprints for the same page id are a bug
- The Confluence "Hamster" root page is per-space, never per-account. Cross-account adoption is explicitly refused via the `isAccountLive` probe in `confluence-root-page-manager.adoptUnclaimedRootPage`. If a second local account ever sees the same Confluence space, the root page from the first account must NOT be claimed

## E2E Test Scenarios

### 1. Baseline and Resync

**Goal**: Verify the sync connection is healthy and resync is idempotent.

**Steps**:

1. Query active connection, mappings, local entities, and provider state
  (see [sql-queries.md](references/sql-queries.md))
2. Trigger resync (see [api-commands.md](references/api-commands.md))
3. Inspect tmux logs

**Pass criteria**:

- Connection remains active
- Mappings stay stable (no new duplicates)
- No duplicate tasks, briefs, or initiatives appear
- tmux shows no repeated create loops or duplicate key errors
- Provider and local state still agree after resync

### 2. Linear Delete-Recreate

**Goal**: Verify connection deletion and recreation handles mappings cleanly.

**Prerequisite**: Know whether the connection is sync-only or linked to a context connection.

**Most important variant**: Delete a Linear connection and recreate or relink the **same workspace and same team**. This is the regression-prone path for duplicate briefs and duplicate project mappings.

**Steps**:

1. Record active `sync_connection_id` and mapping counts
2. Delete through the correct flow:

- Linked connection: context-connection flow
- Sync-only: `DELETE /sync/v1/connections/:id`

3. Recreate or relink the same Linear source
4. Enable sync and trigger resync
5. Re-query mappings and local entities

**Required assertions for same-team recreate**:

- Capture the original `sync_connection_id`, `workspace_id`, and `team_id` before delete
- Capture `sync_entity_mappings` for `hamster_entity_type = 'brief'` grouped by `external_id`
- After recreate, verify the only acceptable identity outcomes are: (a) the old same-team sync row was revived, or (b) retained same-team sync identity was reused. Any extra independent same-team history row is a failure.
- Verify each Linear project `external_id` resolves to exactly one Hamster `brief_id`
- Verify repeated brief titles did not appear with different `brief_id` / `document_id` pairs
- If a new sync row was created intentionally, verify the recreated row reused the prior `brief` mappings rather than minting new briefs
- Check `sync_logs` for project entities and confirm recreate settled into `update` / reused mapping behavior rather than repeated inbound `create success` for already-known projects
- Verify there is only one active webhook for the recreated same-team connection path

**Pass criteria**:

- Old mappings are reused or cleanly revived
- No duplicate initiatives, briefs, tasks, or subtasks
- Webhook registration is healthy after recreation
- Same-team recreate does not increase the number of unique Hamster briefs for existing Linear project IDs
- After recreate, one Linear project `external_id` maps to one Hamster `brief_id`

### 3. Linear Team Switch

**Goal**: Verify switching Linear teams preserves identity deterministically.

**Prerequisite**: Alternate Linear team exists in the same workspace with seed data.

**Steps**:

1. Start from a known active Linear sync connection
2. PATCH to another `team_id` in the same workspace
  (see [api-commands.md](references/api-commands.md))
3. Inspect tmux and DB state
4. PATCH back to the original team
5. Inspect tmux and DB state again

**Pass criteria**:

- Previous connection row is tombstoned when switching away
- Original connection row is revived when switching back (not a third new row)
- Initiative mapping counts remain one active mapping per external initiative ID
- No duplicate initiative rows for the original team after switching back
- Active webhook belongs to the active connection only
- Old webhook is cleared or tombstoned locally after switch

### 4. Linear Initiative 2-Way Sync

**Goal**: Verify initiative changes propagate bidirectionally.

#### Local -> Linear

1. Update local initiative title, status, body content
2. Insert or delete `initiative_briefs` rows
3. Inspect tmux
4. Query Linear initiative directly

**Pass**: Linear `name`, `status`, `content`, and linked projects match local state.

**Required title coverage**:

- Verify a local initiative title change reaches Linear `initiative.name`
- Verify the corresponding outbound sync log exists for that initiative external ID

#### Linear -> Local

1. Mutate initiative in Linear (`name`, `status`, `description`, or `content`)
2. Add/remove project links in Linear
3. Wait for the webhook to arrive (check tmux for `LinearWebhookController` and `InboundSyncConsumer` log lines). Do NOT use resync as a shortcut - it bypasses the change detection path and can mask bugs.
4. Check `sync_logs` for the entity to confirm the inbound update was processed (not hash-skipped)
5. Query local state

**Pass**: Local `initiatives.status`, document title, body, and `initiative_briefs` match Linear. A `sync_logs` entry exists for the inbound update (proves the webhook path processed it, not reconciliation).

**Required workspace-scoped initiative checks**:

- Run at least one inbound initiative **title-only** webhook test on an initiative that is already mapped to the active connection
- If the initiative was previously marked out of scope, verify the mapping re-enters scope (`in_scope = true`, `out_of_scope_reason = null`) after the webhook is processed
- Confirm tmux does **not** show `filterReason: 'team_not_included'` for a connected-team initiative title update

**When to use resync in this scenario**: Only after the webhook test passes, as a final idempotency check (resync should produce 0 deleted, 0 deferred, and no state drift).

### 5. Linear Team Switch and Switch Back

**Goal**: Verify switching to another Linear team and switching back preserves connection
identity, tombstones correctly, and produces no duplicate entities or mappings.

**Prerequisite**: A second Linear team exists in the same workspace. Query teams:

```bash
curl -s "$API" \
  -H "Authorization: Bearer $LINEAR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { teams { nodes { id key name } } }"}' | jq .
```

**Steps**:

1. Record pre-switch baseline:

- Active connection ID, team_id, webhook_id
- Mapping counts by entity type (initiative, project, issue)
- Total connection rows for the account

2. PATCH to the alternate team (see [api-commands.md](references/api-commands.md)):

- Use the active connection's ID
- Supply the alternate `team_id` with the same `workspace_id`

3. Verify switch-away state:

- Original connection row has `deleted_at` set, `sync_enabled = false`, `webhook_id = null`
- A new connection row was created for the alternate team (not the same row reused)
- New webhook registered in Linear for the alternate team
- Old webhook removed from Linear
- Only 2 total connection rows (original tombstoned + new active)

4. Wait for initial sync of the new team to complete (inspect tmux)

5. PATCH back to the original team:

- Use the new connection's ID this time
- Supply the original `team_id`

6. Verify switch-back state:

- The **original** connection row (from step 1) is revived: `deleted_at = null`, `sync_enabled = true`
- The alternate connection is tombstoned: `deleted_at` set, `webhook_id = null`
- Still only 2 total connection rows (no third row created)
- A fresh webhook registered in Linear for the original team
- No leftover webhooks for the alternate team

7. Verify no duplicates after switch-back:

- Original mapping counts match pre-switch baseline
- No duplicate initiative mappings across connections (`GROUP BY external_id HAVING count > 1` returns empty)
- Only 1 active webhook in Linear total

**Pass criteria**:

- Original connection is tombstoned on switch away, revived on switch back
- Alternate connection is created on switch away, tombstoned on switch back
- Exactly 2 connection rows at all times (never 3)
- No duplicate entity mappings across connections
- Webhook ownership follows the active connection exclusively
- Original mapping counts are preserved after the round-trip

### 6. Exact E2E Assertions

For every scenario, verify all applicable items explicitly:

- [ ] Connection row is the expected active row
- [ ] Webhook state is correct for the active connection
- [ ] Mapping row points to the expected hamster ID and external ID
- [ ] Local entity count did not duplicate unexpectedly
- [ ] Provider entity and local entity agree on the fields under test
- [ ] tmux shows a successful sync path or an intentional, understood skip
- [ ] If resync was used, post-resync state still matches both sides
- [ ] Initiative title changes are tested both directions, not just status/link changes
- [ ] Brief/project title changes are tested both directions
- [ ] Task/issue title changes are tested both directions
- [ ] For workspace-scoped webhooks, a connected-team initiative webhook is accepted and an unconnected-team project webhook is ignored
- [ ] When an ignored webhook is expected, confirm the exact skip reason in tmux (`project_not_tagged`, `project_not_included`, or `team_not_included`)
- [ ] For Jira, a non-hamster epic is ignored and produces no brief mapping
- [ ] For Jira, a top-level issue without a mapped hamster epic is ignored or marked out of scope
- [ ] For Jira reconnect, the same `cloud_id + project_id` preserves brief/task identity instead of duplicating mappings
- [ ] For Jira, subtasks keep correct `parent_task_id` and `brief_id` inheritance from the mapped hamster epic path
- [ ] For Confluence, every active connection has a non-null `provider_config.config.root_page_id` after the first reconciliation
- [ ] For Confluence, each `external_id` (page id) maps to exactly one `document_id` of type `'blueprint'`
- [ ] For Confluence, scope filter produced the expected `out_of_scope_reason` for non-hamster, non-rooted, and other-space pages
- [ ] For Confluence reconnect, the same `cloud_id + space_id` revives or reuses retained identity instead of minting a new root or duplicate mappings
- [ ] For Confluence, terminal 401/403 set `reauth_required=true` instead of retrying
- [ ] For Confluence outbound, the page on Confluence carries the `hamster` label and the managed app property after create/update
- [ ] For Confluence content, layout/placeholder/emoticon/status macros round-trip without dropping content silently

### 7. Linear Workspace-Scoped Filter Checks

**Goal**: Verify workspace-scoped Linear webhooks accept connected-team updates and ignore unconnected-team updates.

**Why this is mandatory**: Workspace-scoped webhooks are required for initiatives, but they also deliver events outside the currently active team. Full E2E coverage is incomplete unless both the positive and negative scope decisions are tested.

**Steps**:

1. Query Linear teams and identify:

- the active connected team
- a second team in the same workspace that is not currently connected

2. Pick four concrete provider entities:

- a mapped initiative on the connected team/workspace
- a mapped project on the connected team
- a mapped issue on the connected team
- a project on the other team

3. Run connected-team inbound title updates for initiative, project, and issue via Linear GraphQL mutations
4. Wait for the webhooks to arrive naturally and capture tmux logs
5. Verify local DB state updated for all three connected-team entities
6. Mutate the other-team project title in Linear
7. Wait for the webhook and confirm it is ignored without creating a mapping

**Pass criteria**:

- Connected-team initiative webhook produces inbound processing and updates the local initiative title
- Connected-team project webhook produces inbound processing and updates the local brief title
- Connected-team issue webhook produces inbound processing and updates the local task title
- Other-team project webhook is skipped with an intentional filter reason (`project_not_tagged` or `project_not_included`)
- No mapping row is created for the other-team project on the active connection

### 8. Jira Epic / Issue / Subtask 2-Way Sync

**Goal**: Verify Jira scope and hierarchy behave like the production contract.

**Steps**:

1. Identify one hamster-labeled Jira epic in the selected project and one non-hamster epic
2. Mutate the hamster epic in Jira and wait for the webhook
3. Verify the mapped Hamster brief updates (or is created on first import)
4. Mutate a Jira issue under that epic, or one linked via Jira epic-link custom fields, and verify it attaches to the mapped brief
5. Mutate a Jira subtask under that issue and verify it inherits the correct `parent_task_id` and `brief_id`
6. Create or update a Hamster brief and verify the outbound Jira epic keeps the `hamster` label

**Pass criteria**:

- Hamster-labeled Jira epics import as Hamster briefs
- Jira epics without the `hamster` label stay out of scope
- Jira issues under a mapped hamster epic, including epic-link custom-field variants, attach to the correct brief
- Jira subtasks under those issues inherit the correct task parentage and brief linkage
- Outbound Hamster brief creation/update preserves the Jira `hamster` label

### 9. Jira Delete-Recreate / Same-Project Reconnect

**Goal**: Verify the same Jira source (`cloud_id + project_id`) does not mint duplicate Hamster entities, and that linked-context relink reuses retained identity.

**Steps**:

1. Record the active Jira `sync_connection_id`, `cloud_id`, `project_id`, and mapping counts
2. If the Jira connection is linked to a context connection, exercise the real relink/confirm flow for the same Jira site/project pair
3. Otherwise, recreate the same Jira site/project pair and verify mapping/entity reuse even if the connection row itself is not revived by that flow
4. Trigger resync only after inbound webhook behavior is understood
5. Re-query `sync_connections`, `sync_entity_mappings`, local briefs, and local tasks

**Pass criteria**:

- In the linked-context relink flow, same-source Jira reconnect revives or reuses retained identity instead of minting unrelated history rows
- Existing Jira epic external IDs still resolve to the same Hamster brief IDs
- Existing Jira issue/subtask external IDs still resolve to the same Hamster task IDs
- No duplicate briefs/tasks appear for the same Jira external IDs after reconnect

### 10. Jira Scope Drift and Label Loss

**Goal**: Verify Jira entities leave scope cleanly when their hamster epic linkage disappears.

**Steps**:

1. Start from a mapped hamster-labeled Jira epic plus a mapped child issue
2. Remove the `hamster` label from the epic (or move the issue away from the hamster epic)
3. Wait for the webhook and inspect tmux + `sync_logs`
4. Re-query `sync_entity_mappings` and local entities

**Pass criteria**:

- Epic mapping becomes out of scope when the `hamster` label is removed
- Child issue/task mapping becomes deleted or out of scope when the hamster epic linkage disappears
- No replacement brief/task is minted during the out-of-scope transition

### 11. Jira Personal Data Reporting

**Goal**: Verify the periodic Atlassian `report-accounts` cycle reports stored PII on time, honors the cycle and Retry-After headers, scrubs PII on `closed`/`updated` actions, and never includes the reserved `unknown` accountId.

**Why this is mandatory**: Atlassian monitors apps for correct use of this API. Apps that miss cycles, over-report, or report closed accounts past a reasonable window get flagged. The invariants are encoded across the `JiraAdapter.reportPersonalData` path, the `JiraPersonalDataReportingConsumer`, and the `sync_jira_personal_data_reporting_state` table. See [jira-personal-data-reporting.md](references/jira-personal-data-reporting.md) for setup, trigger recipes, and SQL spot-checks.

**Prerequisites**:

- A real Jira sync connection on the local account (same one used by scenarios 8-10)
- `.env.1p` already sets `SYNC_ENGINE_ENABLED`, `SYNC_JIRA_PERSONAL_DATA_REPORTING_ENABLED`, and `ENABLE_JIRA_TWO_WAY_SYNC`. Confirm they are `true` in the running process via tmux startup logs — do **not** add these to a local `.env.local` unless you specifically need to override
- At least one `sync_user_mappings` row for the connection that has `external_email` or `external_display_name` set and `external_user_id` that is a real Atlassian accountId (not `unknown`)

**Steps**:

1. **Verify the scheduled cycle is live.** Look at the tmux sync pane at startup for `"Queued Jira personal data reporting jobs for enabled Jira connections"`. If you see `SYNC_JIRA_PERSONAL_DATA_REPORTING_ENABLED=false` or a skip log, the flag didn't reach the process.
2. **Seed a due-now state row** so you don't have to wait for the natural 7-day cadence. Query and mutate `sync_jira_personal_data_reporting_state` per [jira-personal-data-reporting.md](references/jira-personal-data-reporting.md) — either seed `next_report_at = now() - interval '1 minute'` or delete the state rows so every mapping becomes first-time-due.
3. **Trigger the consumer** either by waiting for the next interval tick or by enqueueing a job directly with the connection id. The reference file has a one-off Node snippet.
4. **Observe tmux** for `"Jira personal data reporting cycle complete"` with `reportedCount`, `actionCount`, and `cyclePeriodSeconds`. Atlassian's real response for a fresh accountId is usually `actionCount=0`; for a stale one you'll see `updated` or `closed` in `actions`.
5. **Exercise the rate-limit path** by simulating 429 behavior. Easiest: temporarily point the adapter's app-token call at a stub, or simulate by updating the state row to a recent `retry_after_until` and verifying the consumer re-enqueues with the expected delay instead of re-hitting Atlassian.
6. **Exercise the "closed" scrub** by picking one mapping, stamping the state with `last_atlassian_status = 'closed'` manually if needed, or choosing a real Atlassian accountId you've closed in an Atlassian sandbox — then verify `external_email`, `external_display_name`, `personal_data_retrieved_at` all become `null` on the mapping, and `external_is_active` flips to `false`.
7. **Exercise the "updated" scrub** analogously — verify PII is cleared (forces the next user-mapping refresh to re-fetch it) but `external_is_active` stays `true`.
8. **Run the compliance spot-checks** from [jira-personal-data-reporting.md](references/jira-personal-data-reporting.md) — they must all return zero rows.

**Pass criteria**:

- A due state row leads to a `POST https://api.atlassian.com/app/report-accounts/` with the correct batch shape (≤90 accounts, each `{accountId, updatedAt}` in RFC 3339 format)
- After a successful cycle, `next_report_at` advances by `cycle_period_seconds` (7 days by default, or the capped `Cycle-Period` header value), `last_error` is `null`, `retry_after_until` is `null`
- A 429 branch stores `retry_after_until` and re-enqueues with a delay that respects `Retry-After` but does not exceed 24h
- `closed` and `updated` actions clear `external_email` / `external_display_name` / `personal_data_retrieved_at` on the matching `sync_user_mappings` rows; `closed` additionally sets `external_is_active = false`
- The reserved `unknown` accountId never appears in the reporting state table (DB CHECK) and never leaves the consumer in a request body
- No `sync_user_mappings` row with `external_user_id = 'unknown'` stores `external_email` or `external_display_name`
- No mapping stores PII with a `NULL` `personal_data_retrieved_at` after the next `refresh-user-mappings` pass — the timestamp must be stamped whenever PII is persisted

### 12. Confluence Root Page Bootstrap

**Goal**: Verify the per-space "Hamster" root page is created (or adopted) exactly once, and that
`provider_config.config.root_page_id` is populated before any outbound page write attempts.

**Why this is mandatory

…(truncated)
