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.
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
Get provider OAuth token
Vault query
auth-setup.md
Check sync connection state
SQL queries
sql-queries.md
Check entity mappings
SQL queries
sql-queries.md
Trigger resync / team switch / delete
curl commands
api-commands.md
Query Linear entities directly
GraphQL
linear-queries.md
Query Jira entities directly
REST
jira-queries.md
Query Confluence pages/spaces directly
REST V2
confluence-queries.md
Verify Jira personal data reporting cadence
SQL + BullMQ trigger
sql-queries.md
Force Confluence reconciliation now
BullMQ enqueue or env tick
confluence-queries.md
Validate mention / mark / formatting / special-character survival across the round-trip
Seed a brief with the canonical all-elements demo doc
Browser-console editor setContent snippet
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
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:
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
Baseline & Resync
Linear Delete-Recreate
Linear Initiative 2-Way Sync (both directions)
Linear Team Switch and Switch Back
Linear Workspace-Scoped Filter Checks
Jira default plan
Baseline & Resync
Jira Epic / Issue / Subtask 2-Way Sync
Jira Delete-Recreate / Same-Project Reconnect
Jira Scope Drift and Label Loss
Confluence default plan
Baseline & Resync (still relevant — Confluence connections use the same sync_connections row, resync re-baselines hashes)
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:
tmux new-session -d -s dev 'pnpm dev:with-sync'
If local schema is behind the branch:
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.
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:
mcp__supabase__query - fastest way to confirm DB state matches runtime behavior
Direct curl - local auth, sync API calls, Linear GraphQL queries, Jira REST queries
tmux logs - needed after every major step to confirm processing
Useful tmux commands:
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 for the full flow. Quick summary:
Get local Supabase env: pnpm --filter web supabase status -o env
Get JWT with seeded credentials (owner@tryhamster.com / testingpassword)
Find active sync connection via SQL
Get provider OAuth token from vault.decrypted_secrets
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:
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:
Query active connection, mappings, local entities, and provider state
(see sql-queries.md)
Trigger resync (see api-commands.md)
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:
Record active sync_connection_id and mapping counts
Delete through the correct flow:
Linked connection: context-connection flow
Sync-only: DELETE /sync/v1/connections/:id
Recreate or relink the same Linear source
Enable sync and trigger resync
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:
Start from a known active Linear sync connection
PATCH to another team_id in the same workspace
(see api-commands.md)
Inspect tmux and DB state
PATCH back to the original team
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
Update local initiative title, status, body content
Insert or delete initiative_briefs rows
Inspect tmux
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
Mutate initiative in Linear (name, status, description, or content)
Add/remove project links in Linear
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.
Check sync_logs for the entity to confirm the inbound update was processed (not hash-skipped)
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:
curl -s "$API" \
-H "Authorization: Bearer $LINEAR_TOKEN" \
-H "Content-Type: application/json" \
--data '{"query":"query { teams { nodes { id key name } } }"}' | jq .
Steps:
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
PATCH to the alternate team (see api-commands.md):
Use the active connection's ID
Supply the alternate team_id with the same workspace_id
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)
Wait for initial sync of the new team to complete (inspect tmux)
PATCH back to the original team:
Use the new connection's ID this time
Supply the original team_id
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
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:
Query Linear teams and identify:
the active connected team
a second team in the same workspace that is not currently connected
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
Run connected-team inbound title updates for initiative, project, and issue via Linear GraphQL mutations
Wait for the webhooks to arrive naturally and capture tmux logs
Verify local DB state updated for all three connected-team entities
Mutate the other-team project title in Linear
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:
Identify one hamster-labeled Jira epic in the selected project and one non-hamster epic
Mutate the hamster epic in Jira and wait for the webhook
Verify the mapped Hamster brief updates (or is created on first import)
Mutate a Jira issue under that epic, or one linked via Jira epic-link custom fields, and verify it attaches to the mapped brief
Mutate a Jira subtask under that issue and verify it inherits the correct parent_task_id and brief_id
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:
Record the active Jira sync_connection_id, cloud_id, project_id, and mapping counts
If the Jira connection is linked to a context connection, exercise the real relink/confirm flow for the same Jira site/project pair
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
Trigger resync only after inbound webhook behavior is understood
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:
Start from a mapped hamster-labeled Jira epic plus a mapped child issue
Remove the hamster label from the epic (or move the issue away from the hamster epic)
Wait for the webhook and inspect tmux + sync_logs
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 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:
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.
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 — either seed next_report_at = now() - interval '1 minute' or delete the state rows so every mapping becomes first-time-due.
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.
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.
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.
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.
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.
Run the compliance spot-checks from 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 NULLpersonal_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)
1---2name: hamster-sync-local-testing3description: "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."4version: "1.0.0"5metadata:6 source: https://skillmd.com/skills/gethamster/hamster-sync-local-testing7---89# Sync Service Local Testing1011Canonical runbook for validating Linear, Jira, and Confluence sync against the real local12stack. Use tmux logs, Supabase state, sync API calls, and direct provider queries together13to verify runtime behavior.1415Provider-shape cheatsheet:1617| Provider | Inbound channel | Outbound trigger | Entities | Identity key |18| --- | --- | --- | --- | --- |19| Linear | Per-connection webhook | DB trigger → outbox | initiative/project/issue → initiative/brief/task | `workspace_id` (+ team) |20| Jira | Static webhook + token | DB trigger → outbox | epic/issue/subtask → brief/task | `cloud_id + project_id` |21| Confluence | Periodic reconciliation (no webhook) | DB trigger `enqueue_blueprint_confluence_page_change` → outbox | page → blueprint document | `cloud_id + space_id` |2223## Quick Reference2425| Task | How | Reference |26| --- | --- | --- |27| Get local JWT + account ID | Auth setup flow | [auth-setup.md](references/auth-setup.md) |28| Get provider OAuth token | Vault query | [auth-setup.md](references/auth-setup.md) |29| Check sync connection state | SQL queries | [sql-queries.md](references/sql-queries.md) |30| Check entity mappings | SQL queries | [sql-queries.md](references/sql-queries.md) |31| Trigger resync / team switch / delete | curl commands | [api-commands.md](references/api-commands.md) |32| Query Linear entities directly | GraphQL | [linear-queries.md](references/linear-queries.md) |33| Query Jira entities directly | REST | [jira-queries.md](references/jira-queries.md) |34| Query Confluence pages/spaces directly | REST V2 | [confluence-queries.md](references/confluence-queries.md) |35| Verify Jira personal data reporting cadence | SQL + BullMQ trigger | [sql-queries.md](references/sql-queries.md) |36| Force Confluence reconciliation now | BullMQ enqueue or env tick | [confluence-queries.md](references/confluence-queries.md) |37| 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) |38| Seed a brief with the canonical all-elements demo doc | Browser-console editor `setContent` snippet | [full-content-seed.md](references/full-content-seed.md) |39| Run E2E test scenarios | Checklists below | This file |4041## Branch-Aware Test Planning4243Before running any scenario, analyze the current branch to build a targeted test plan.44The goal is to focus testing time on the code paths that actually changed, rather than45blindly running every scenario.4647### Step 1: Identify what changed4849```bash50git log --oneline dev..HEAD51git diff dev --stat52git diff dev --name-only53```5455If the branch has no divergence from `dev`, try `main` instead.5657### Step 2: Classify the changes5859Read the changed files and diffs. Map each change to a sync domain:6061| Change area | Relevant scenarios |62| --- | --- |63| `sync.orchestrator.ts`, inbound/outbound consumers | Initiative 2-Way Sync, Baseline & Resync |64| `sync-connections.controller.ts`, connection lifecycle | Team Switch, Delete-Recreate, Baseline |65| `context-connections.service.ts`, retained sync re-link logic | Delete-Recreate, Team Switch and Switch Back |66| Initiative-related mappers, `initiative_briefs` triggers | Initiative 2-Way Sync |67| `webhook.consumer.ts`, `linear-provider-scope-evaluator.ts` | Initiative 2-Way Sync, Workspace-Scoped Filter Checks |68| `webhooks/jira-webhook.controller.ts`, `jira-site-webhook-manager.service.ts` | Jira Baseline & Routing, Jira Scope & Webhook Auth |69| `adapters/jira/*`, `jira-provider-scope-evaluator.ts` | Jira Epic/Issue/Subtask 2-Way Sync, Jira Scope Drift |70| `jira-personal-data-reporting.consumer.ts`, `jira-personal-data-reporting.repository.ts`, `JiraAdapter.reportPersonalData` | Jira Personal Data Reporting |71| `user-mappings.repository.ts` PII handling, `user-mapping-refresh.consumer.ts` | Jira Personal Data Reporting |72| Jira status/field mapping bootstrap | Jira Epic/Issue/Subtask 2-Way Sync |73| `adapters/confluence/confluence.adapter.ts`, `confluence.api-client.ts` | Confluence Blueprint 2-Way Sync, Confluence Reauth |74| `confluence-root-page-bootstrap.ts`, `confluence-root-page-manager.ts` | Confluence Root Page Bootstrap |75| `confluence-provider-scope-evaluator.ts`, hamster label / app property handling | Confluence Scope and Out-of-Scope Drift |76| `confluence.conversion.ts`, storage-format macros | Confluence Content Conversion |77| `SyncEngineService.ensureConfluenceReconciliationSchedule`, `ReconciliationConsumer` Confluence branch | Confluence Reconciliation Cadence |78| `reviveRetainedConfluenceConnectionIfPresent`, `cloud_id + space_id` retained identity SQL | Confluence Delete-Recreate / Same-Space Reconnect |79| Migration `*_confluence-sync.sql`, `enqueue_blueprint_confluence_page_change` trigger | All Confluence scenarios |80| Webhook controller, webhook registration | Baseline & Resync, Team Switch |81| Reconciliation consumer, resync logic | Baseline & Resync |82| `apply_inbound_brief_insert`, `sync_entity_mappings`, reconnect migrations | Delete-Recreate, Baseline & Resync |83| Migration files, schema changes | All scenarios (schema changes affect everything) |84| Outbox triggers, document polling | Local -> provider sync |85| Vault, credentials, OAuth | Auth setup only (verify token retrieval works) |86| `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)) |87| `packages/shared/src/documents/conversion/adf/*`, `adapters/linear/linear-pm-converter.ts` | Content & Formatting Validation |88| Per-provider native-wire flags (`ENABLE_JIRA_NATIVE_ADF_*`, `ENABLE_CONFLUENCE_NATIVE_STORAGE_*`, `ENABLE_LINEAR_NATIVE_PM_*`) | Content & Formatting Validation |8990### Step 3: Build the test plan9192Based on the classification:93941. **Always run Scenario 1 (Baseline & Resync)** - it's the health check that catches regressions in any area952. Add scenarios that map to the changed code paths963. If a migration was added, run all scenarios - schema changes have broad blast radius974. Present the plan to the user before executing9899Provider mapping shortcut:100101- Linear changes usually imply Scenarios 2, 3, 4, 5, and 7102- Jira changes usually imply Scenarios 8, 9, and 10103- Jira user-mapping or personal-data-reporting changes imply Scenario 11104- Confluence changes usually imply Scenarios 12, 13, 14, and 15105- Confluence OAuth scope, refresh, or 401/403 handling changes imply Scenario 16106107### Fallback: when the branch is unclear108109If the diff is empty, the changes don't touch sync code, or you can't confidently map110changes to scenarios, fall back to the provider-specific default plan:111112**Linear default plan**1131141. Baseline & Resync1152. Linear Delete-Recreate1163. Linear Initiative 2-Way Sync (both directions)1174. Linear Team Switch and Switch Back1185. Linear Workspace-Scoped Filter Checks119120**Jira default plan**1211221. Baseline & Resync1232. Jira Epic / Issue / Subtask 2-Way Sync1243. Jira Delete-Recreate / Same-Project Reconnect1254. Jira Scope Drift and Label Loss126127**Confluence default plan**1281291. Baseline & Resync (still relevant — Confluence connections use the same `sync_connections` row, resync re-baselines hashes)1302. Confluence Root Page Bootstrap1313. Confluence Blueprint 2-Way Sync (page <-> document)1324. Confluence Scope and Out-of-Scope Drift1335. Confluence Delete-Recreate / Same-Space Reconnect1346. Confluence Reauth on Scope / Credential Failure (if OAuth code changed)135136This is also the right plan when the user says "just test everything" or doesn't specify.137138---139140## Prerequisites141142Before starting, confirm:143144- Local stack is running in a persistent tmux `dev` session via `pnpm dev:with-sync`145- **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.146- If the current branch added DB changes, local migrations are already applied147- You have a team account ID for the workspace under test148- An active sync connection exists with valid provider OAuth credentials in Vault149- If you are validating workspace-scoped webhook filtering, a second Linear team in the same workspace must exist150- If you are validating Jira scope behavior, the selected Jira project must contain both hamster-labeled and non-hamster epics151- 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 root152153Recommended baseline test fixture:154155- One active Linear sync connection for the account156- At least one synced task157- At least one synced brief/project158- At least one synced initiative linked through `initiative_briefs`159160Recommended Jira-specific fixture:161162- One active Jira sync connection for the selected `cloud_id + project_id`163- At least one hamster-labeled Jira epic already mapped to a Hamster brief164- At least one Jira issue under that epic and at least one subtask under that issue165- At least one Jira epic without the `hamster` label to validate out-of-scope behavior166167Recommended Confluence-specific fixture:168169- One active Confluence sync connection for the selected `cloud_id + space_id`170- `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 explicitly171- 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 document172- 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 reconciliations173- 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 skip174175If the stack is not running, start it in a persistent tmux session:176177```bash178tmux new-session -d -s dev 'pnpm dev:with-sync'179```180181If local schema is behind the branch:182183```bash184pnpm --filter web supabase db push --local185```186187## Local Topology188189- Proxy: `http://127.0.0.1:8080` (preferred for all API calls)190- Web app direct: `127.0.0.1:3000`191- Local Supabase API: `127.0.0.1:54321`192- Local Postgres: `127.0.0.1:54322`193194Sync routes live under `/sync/v1/...`:195196- `POST /sync/v1/connections/:id/resync`197- `PATCH /sync/v1/connections/:id`198- `DELETE /sync/v1/connections/:id`199- `POST /sync/v1/connections/:id/enable`200- `POST /sync/v1/connections/:id/disable`201- `POST /sync/v1/webhooks/linear/:accountId/:connectionId`202- `POST /sync/v1/webhooks/jira`203204Confluence has no webhook route. Inbound arrives via the periodic `sync-reconciliation` BullMQ205queue. The repeat job id is `sync-confluence-reconciliation-repeat`, scheduled by206`SyncEngineService.ensureConfluenceReconciliationSchedule` at207`SYNC_CONFLUENCE_RECONCILIATION_INTERVAL_MS` (default 10 minutes). Outbound starts from the208`enqueue_blueprint_confluence_page_change` Postgres trigger on `document` mutations.209210## Cold-Start Orientation211212If starting from empty context, anchor with these facts:213214- `apps/sync` owns webhook ingress, queue consumers, reconciliation, and sync API routes215- Local writes enqueue outbound work through DB triggers and outbox processing216- Inbound sync (provider -> Local) arrives via webhooks through the Cloudflare tunnel - this is the main channel and must be tested directly217- Resync (`/sync/v1/connections/:id/resync`) is for re-baselining hashes and verifying idempotency, not for testing the inbound path218219Provider-specific ingress rules:220221- Linear uses a per-connection webhook route and direct GraphQL verification.222- Jira uses the static `/sync/v1/webhooks/jira` endpoint, validates a stored webhook token, and routes events by `site_url + project_id`.223- 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.224- 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.225- 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.226227Key source files:228229- `apps/sync/src/modules/sync-engine/controllers/sync-connections.controller.ts`230- `apps/sync/src/modules/sync-engine/webhooks/linear-webhook.controller.ts`231- `apps/sync/src/modules/sync-engine/webhooks/jira-webhook.controller.ts`232- `apps/sync/src/modules/sync-engine/queues/outbound-sync.consumer.ts`233- `apps/sync/src/modules/sync-engine/queues/reconciliation.consumer.ts`234- `apps/sync/src/modules/sync-engine/sync.orchestrator.ts`235- `apps/sync/src/modules/sync-engine/adapters/jira/jira-provider-scope-evaluator.ts`236- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence.adapter.ts`237- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence.api-client.ts`238- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence-root-page-bootstrap.ts`239- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence-root-page-manager.ts`240- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence-provider-scope-evaluator.ts`241- `apps/sync/src/modules/sync-engine/adapters/confluence/confluence.conversion.ts`242- `apps/sync/src/modules/sync-engine/sync-engine.service.ts` (Confluence reconciliation schedule)243- `packages/supabase/src/vault-connection-credentials.ts`244245## Verification Workflow246247Every sync test follows this core loop. Do not skip steps.248249```2501. Capture tmux BEFORE mutation2512. Run the mutation (API call, DB update, provider change)2523. Wait for the webhook or outbox processing to fire (check tmux)2534. Capture tmux AFTER mutation2545. Verify local DB state2556. Verify remote provider state2567. Use resync ONLY for hash re-baselining or final idempotency checks257```258259**Webhooks are the main channel for Linear and Jira.** Inbound sync (provider -> Local) arrives260via webhooks through the Cloudflare tunnel. When testing inbound changes for Linear or Jira,261mutate on the provider and wait for the webhook to arrive naturally. Check tmux for the262relevant webhook controller (`LinearWebhookController` or `JiraWebhookController`) and263`InboundSyncConsumer` log lines to confirm the webhook was received and processed. Do not264substitute resync for webhook testing - resync uses the reconciliation path which bypasses265the real-time change detection and can mask bugs (e.g. hash-match field mismatches that266silently drop webhook updates while reconciliation still works).267268**Confluence has no webhook channel.** Inbound runs entirely through periodic reconciliation269plus on-demand resync. There is no "wait for the webhook" step. The verification loop for270Confluence becomes:271272```2731. Capture tmux BEFORE mutation2742. Mutate the page on Confluence (REST V2 or UI)2753. Either wait for the next reconciliation tick OR enqueue a one-shot reconciliation job2764. Capture tmux AFTER reconciliation runs (look for ReconciliationConsumer + ConfluenceAdapter logs)2775. Verify local DB state (document/blueprint row, sync_entity_mappings, sync_logs entry)2786. Re-fetch the Confluence page via REST to confirm round-trip outbound was not stomped279```280281For Confluence, resync is *not* a "use only as a final idempotency check" — it is the primary282verification trigger when you cannot wait 10 minutes for the next tick. The trade-off is283opposite to Linear/Jira: there is no separate webhook path to mask, but resync still re-baselines284hashes, so a reconciliation-only bug in scope/conversion will still surface there.285286### Tool Priority287288Use these in this order - start with the fastest feedback loop:2892901. **`mcp__supabase__query`** - fastest way to confirm DB state matches runtime behavior2912. **Direct `curl`** - local auth, sync API calls, Linear GraphQL queries, Jira REST queries2923. **tmux logs** - needed after every major step to confirm processing293294Useful tmux commands:295296```bash297tmux ls298tmux list-panes -a -F "#{session_name}:#{window_index}.#{pane_index} #{pane_current_command} #{pane_pid} #{pane_title}"299tmux capture-pane -p -t dev:1.1 -S -400300```301302Do not use `interactive_bash` for `capture-pane`.303304## Auth Setup305306Read [auth-setup.md](references/auth-setup.md) for the full flow. Quick summary:3073081. Get local Supabase env: `pnpm --filter web supabase status -o env`3092. Get JWT with seeded credentials (`owner@tryhamster.com` / `testingpassword`)3103. Find active sync connection via SQL3114. Get provider OAuth token from `vault.decrypted_secrets`3125. Set shell variables for the provider under test (`LINEAR_TOKEN` or `JIRA_TOKEN`, plus provider-specific IDs)313314## Current Data Model315316Understanding this is critical for correct verification:317318- `initiatives` + linked `document` = canonical initiative entity319- `initiative_briefs` = canonical initiative <-> brief association set320- `brief.initiative_id` is a compatibility shadow only - never treat it as source of truth321- Outbound sync starts from local DB changes and outbox processing, not ad hoc web calls322- Confluence pages map to `document` rows of type `'blueprint'` — not briefs, not tasks. The323 hamster_entity_type in `sync_entity_mappings` for Confluence is `'blueprint'`; the324 external_entity_type is `'page'`. `sync_entity_mappings.external_version` stores the325 numeric Confluence page version for conflict detection326- 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 error327328## Caveats329330- Initiatives are workspace-wide, so team-switch tests can surface workspace-scope behavior331- Bounded initiative queries with nested `projects -> teams` are helpful for debugging but are not complete evidence for very large initiatives332- Linear identifiers do not equal Hamster display IDs333- Outbound brief/project status sync is not canonical - do not assume local brief status changes round-trip to Linear project status334- 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 scope335- 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 bug336- 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 Confluence337- 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 bug338- 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 claimed339340## E2E Test Scenarios341342### 1. Baseline and Resync343344**Goal**: Verify the sync connection is healthy and resync is idempotent.345346**Steps**:3473481. Query active connection, mappings, local entities, and provider state349 (see [sql-queries.md](references/sql-queries.md))3502. Trigger resync (see [api-commands.md](references/api-commands.md))3513. Inspect tmux logs352353**Pass criteria**:354355- Connection remains active356- Mappings stay stable (no new duplicates)357- No duplicate tasks, briefs, or initiatives appear358- tmux shows no repeated create loops or duplicate key errors359- Provider and local state still agree after resync360361### 2. Linear Delete-Recreate362363**Goal**: Verify connection deletion and recreation handles mappings cleanly.364365**Prerequisite**: Know whether the connection is sync-only or linked to a context connection.366367**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.368369**Steps**:3703711. Record active `sync_connection_id` and mapping counts3722. Delete through the correct flow:373374- Linked connection: context-connection flow375- Sync-only: `DELETE /sync/v1/connections/:id`3763773. Recreate or relink the same Linear source3784. Enable sync and trigger resync3795. Re-query mappings and local entities380381**Required assertions for same-team recreate**:382383- Capture the original `sync_connection_id`, `workspace_id`, and `team_id` before delete384- Capture `sync_entity_mappings` for `hamster_entity_type = 'brief'` grouped by `external_id`385- 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.386- Verify each Linear project `external_id` resolves to exactly one Hamster `brief_id`387- Verify repeated brief titles did not appear with different `brief_id` / `document_id` pairs388- If a new sync row was created intentionally, verify the recreated row reused the prior `brief` mappings rather than minting new briefs389- Check `sync_logs` for project entities and confirm recreate settled into `update` / reused mapping behavior rather than repeated inbound `create success` for already-known projects390- Verify there is only one active webhook for the recreated same-team connection path391392**Pass criteria**:393394- Old mappings are reused or cleanly revived395- No duplicate initiatives, briefs, tasks, or subtasks396- Webhook registration is healthy after recreation397- Same-team recreate does not increase the number of unique Hamster briefs for existing Linear project IDs398- After recreate, one Linear project `external_id` maps to one Hamster `brief_id`399400### 3. Linear Team Switch401402**Goal**: Verify switching Linear teams preserves identity deterministically.403404**Prerequisite**: Alternate Linear team exists in the same workspace with seed data.405406**Steps**:4074081. Start from a known active Linear sync connection4092. PATCH to another `team_id` in the same workspace410 (see [api-commands.md](references/api-commands.md))4113. Inspect tmux and DB state4124. PATCH back to the original team4135. Inspect tmux and DB state again414415**Pass criteria**:416417- Previous connection row is tombstoned when switching away418- Original connection row is revived when switching back (not a third new row)419- Initiative mapping counts remain one active mapping per external initiative ID420- No duplicate initiative rows for the original team after switching back421- Active webhook belongs to the active connection only422- Old webhook is cleared or tombstoned locally after switch423424### 4. Linear Initiative 2-Way Sync425426**Goal**: Verify initiative changes propagate bidirectionally.427428#### Local -> Linear4294301. Update local initiative title, status, body content4312. Insert or delete `initiative_briefs` rows4323. Inspect tmux4334. Query Linear initiative directly434435**Pass**: Linear `name`, `status`, `content`, and linked projects match local state.436437**Required title coverage**:438439- Verify a local initiative title change reaches Linear `initiative.name`440- Verify the corresponding outbound sync log exists for that initiative external ID441442#### Linear -> Local4434441. Mutate initiative in Linear (`name`, `status`, `description`, or `content`)4452. Add/remove project links in Linear4463. 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.4474. Check `sync_logs` for the entity to confirm the inbound update was processed (not hash-skipped)4485. Query local state449450**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).451452**Required workspace-scoped initiative checks**:453454- Run at least one inbound initiative **title-only** webhook test on an initiative that is already mapped to the active connection455- 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 processed456- Confirm tmux does **not** show `filterReason: 'team_not_included'` for a connected-team initiative title update457458**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).459460### 5. Linear Team Switch and Switch Back461462**Goal**: Verify switching to another Linear team and switching back preserves connection463identity, tombstones correctly, and produces no duplicate entities or mappings.464465**Prerequisite**: A second Linear team exists in the same workspace. Query teams:466467```bash468curl -s "$API" \469 -H "Authorization: Bearer $LINEAR_TOKEN" \470 -H "Content-Type: application/json" \471 --data '{"query":"query { teams { nodes { id key name } } }"}' | jq .472```473474**Steps**:4754761. Record pre-switch baseline:477478- Active connection ID, team_id, webhook_id479- Mapping counts by entity type (initiative, project, issue)480- Total connection rows for the account4814822. PATCH to the alternate team (see [api-commands.md](references/api-commands.md)):483484- Use the active connection's ID485- Supply the alternate `team_id` with the same `workspace_id`4864873. Verify switch-away state:488489- Original connection row has `deleted_at` set, `sync_enabled = false`, `webhook_id = null`490- A new connection row was created for the alternate team (not the same row reused)491- New webhook registered in Linear for the alternate team492- Old webhook removed from Linear493- Only 2 total connection rows (original tombstoned + new active)4944954. Wait for initial sync of the new team to complete (inspect tmux)4964975. PATCH back to the original team:498499- Use the new connection's ID this time500- Supply the original `team_id`5015026. Verify switch-back state:503504- The **original** connection row (from step 1) is revived: `deleted_at = null`, `sync_enabled = true`505- The alternate connection is tombstoned: `deleted_at` set, `webhook_id = null`506- Still only 2 total connection rows (no third row created)507- A fresh webhook registered in Linear for the original team508- No leftover webhooks for the alternate team5095107. Verify no duplicates after switch-back:511512- Original mapping counts match pre-switch baseline513- No duplicate initiative mappings across connections (`GROUP BY external_id HAVING count > 1` returns empty)514- Only 1 active webhook in Linear total515516**Pass criteria**:517518- Original connection is tombstoned on switch away, revived on switch back519- Alternate connection is created on switch away, tombstoned on switch back520- Exactly 2 connection rows at all times (never 3)521- No duplicate entity mappings across connections522- Webhook ownership follows the active connection exclusively523- Original mapping counts are preserved after the round-trip524525### 6. Exact E2E Assertions526527For every scenario, verify all applicable items explicitly:528529- [ ] Connection row is the expected active row530- [ ] Webhook state is correct for the active connection531- [ ] Mapping row points to the expected hamster ID and external ID532- [ ] Local entity count did not duplicate unexpectedly533- [ ] Provider entity and local entity agree on the fields under test534- [ ] tmux shows a successful sync path or an intentional, understood skip535- [ ] If resync was used, post-resync state still matches both sides536- [ ] Initiative title changes are tested both directions, not just status/link changes537- [ ] Brief/project title changes are tested both directions538- [ ] Task/issue title changes are tested both directions539- [ ] For workspace-scoped webhooks, a connected-team initiative webhook is accepted and an unconnected-team project webhook is ignored540- [ ] When an ignored webhook is expected, confirm the exact skip reason in tmux (`project_not_tagged`, `project_not_included`, or `team_not_included`)541- [ ] For Jira, a non-hamster epic is ignored and produces no brief mapping542- [ ] For Jira, a top-level issue without a mapped hamster epic is ignored or marked out of scope543- [ ] For Jira reconnect, the same `cloud_id + project_id` preserves brief/task identity instead of duplicating mappings544- [ ] For Jira, subtasks keep correct `parent_task_id` and `brief_id` inheritance from the mapped hamster epic path545- [ ] For Confluence, every active connection has a non-null `provider_config.config.root_page_id` after the first reconciliation546- [ ] For Confluence, each `external_id` (page id) maps to exactly one `document_id` of type `'blueprint'`547- [ ] For Confluence, scope filter produced the expected `out_of_scope_reason` for non-hamster, non-rooted, and other-space pages548- [ ] For Confluence reconnect, the same `cloud_id + space_id` revives or reuses retained identity instead of minting a new root or duplicate mappings549- [ ] For Confluence, terminal 401/403 set `reauth_required=true` instead of retrying550- [ ] For Confluence outbound, the page on Confluence carries the `hamster` label and the managed app property after create/update551- [ ] For Confluence content, layout/placeholder/emoticon/status macros round-trip without dropping content silently552553### 7. Linear Workspace-Scoped Filter Checks554555**Goal**: Verify workspace-scoped Linear webhooks accept connected-team updates and ignore unconnected-team updates.556557**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.558559**Steps**:5605611. Query Linear teams and identify:562563- the active connected team564- a second team in the same workspace that is not currently connected5655662. Pick four concrete provider entities:567568- a mapped initiative on the connected team/workspace569- a mapped project on the connected team570- a mapped issue on the connected team571- a project on the other team5725733. Run connected-team inbound title updates for initiative, project, and issue via Linear GraphQL mutations5744. Wait for the webhooks to arrive naturally and capture tmux logs5755. Verify local DB state updated for all three connected-team entities5766. Mutate the other-team project title in Linear5777. Wait for the webhook and confirm it is ignored without creating a mapping578579**Pass criteria**:580581- Connected-team initiative webhook produces inbound processing and updates the local initiative title582- Connected-team project webhook produces inbound processing and updates the local brief title583- Connected-team issue webhook produces inbound processing and updates the local task title584- Other-team project webhook is skipped with an intentional filter reason (`project_not_tagged` or `project_not_included`)585- No mapping row is created for the other-team project on the active connection586587### 8. Jira Epic / Issue / Subtask 2-Way Sync588589**Goal**: Verify Jira scope and hierarchy behave like the production contract.590591**Steps**:5925931. Identify one hamster-labeled Jira epic in the selected project and one non-hamster epic5942. Mutate the hamster epic in Jira and wait for the webhook5953. Verify the mapped Hamster brief updates (or is created on first import)5964. Mutate a Jira issue under that epic, or one linked via Jira epic-link custom fields, and verify it attaches to the mapped brief5975. Mutate a Jira subtask under that issue and verify it inherits the correct `parent_task_id` and `brief_id`5986. Create or update a Hamster brief and verify the outbound Jira epic keeps the `hamster` label599600**Pass criteria**:601602- Hamster-labeled Jira epics import as Hamster briefs603- Jira epics without the `hamster` label stay out of scope604- Jira issues under a mapped hamster epic, including epic-link custom-field variants, attach to the correct brief605- Jira subtasks under those issues inherit the correct task parentage and brief linkage606- Outbound Hamster brief creation/update preserves the Jira `hamster` label607608### 9. Jira Delete-Recreate / Same-Project Reconnect609610**Goal**: Verify the same Jira source (`cloud_id + project_id`) does not mint duplicate Hamster entities, and that linked-context relink reuses retained identity.611612**Steps**:6136141. Record the active Jira `sync_connection_id`, `cloud_id`, `project_id`, and mapping counts6152. If the Jira connection is linked to a context connection, exercise the real relink/confirm flow for the same Jira site/project pair6163. Otherwise, recreate the same Jira site/project pair and verify mapping/entity reuse even if the connection row itself is not revived by that flow6174. Trigger resync only after inbound webhook behavior is understood6185. Re-query `sync_connections`, `sync_entity_mappings`, local briefs, and local tasks619620**Pass criteria**:621622- In the linked-context relink flow, same-source Jira reconnect revives or reuses retained identity instead of minting unrelated history rows623- Existing Jira epic external IDs still resolve to the same Hamster brief IDs624- Existing Jira issue/subtask external IDs still resolve to the same Hamster task IDs625- No duplicate briefs/tasks appear for the same Jira external IDs after reconnect626627### 10. Jira Scope Drift and Label Loss628629**Goal**: Verify Jira entities leave scope cleanly when their hamster epic linkage disappears.630631**Steps**:6326331. Start from a mapped hamster-labeled Jira epic plus a mapped child issue6342. Remove the `hamster` label from the epic (or move the issue away from the hamster epic)6353. Wait for the webhook and inspect tmux + `sync_logs`6364. Re-query `sync_entity_mappings` and local entities637638**Pass criteria**:639640- Epic mapping becomes out of scope when the `hamster` label is removed641- Child issue/task mapping becomes deleted or out of scope when the hamster epic linkage disappears642- No replacement brief/task is minted during the out-of-scope transition643644### 11. Jira Personal Data Reporting645646**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.647648**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.649650**Prerequisites**:651652- A real Jira sync connection on the local account (same one used by scenarios 8-10)653- `.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 override654- 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`)655656**Steps**:6576581. **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.6592. **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.6603. **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.6614. **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`.6625. **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.6636. **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`.6647. **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`.6658. **Run the compliance spot-checks** from [jira-personal-data-reporting.md](references/jira-personal-data-reporting.md) — they must all return zero rows.666667**Pass criteria**:668669- 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)670- 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`671- A 429 branch stores `retry_after_until` and re-enqueues with a delay that respects `Retry-After` but does not exceed 24h672- `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`673- The reserved `unknown` accountId never appears in the reporting state table (DB CHECK) and never leaves the consumer in a request body674- No `sync_user_mappings` row with `external_user_id = 'unknown'` stores `external_email` or `external_display_name`675- 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 persisted676677### 12. Confluence Root Page Bootstrap678679**Goal**: Verify the per-space "Hamster" root page is created (or adopted) exactly once, and that680`provider_config.config.root_page_id` is populated before any outbound page write attempts.681682**Why this is mandatory683684…(truncated)
Run npx get-skill add gethamster/hamster-sync-local-testing in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
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. It is listed under Docs & Writing on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
gethamster (@gethamster) published this skill. Their other Agent Skills are listed on their SkillMD profile.