Skip to content

Commit 31d524a

Browse files
JoeOakhartNavaJoeOakhartNava
committed
chore(w21-54wx): preplanning — 7 stories for dependency mgmt, sync, conflict resolution (merge worktree-20260319-164427)
2 parents 7a07a9a + 7e0a42f commit 31d524a

7 files changed

Lines changed: 258 additions & 0 deletions

File tree

‎.tickets/w21-05z9.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
id: w21-05z9
3+
status: open
4+
deps: [w21-6k7v, w21-8011]
5+
links: []
6+
created: 2026-03-20T05:07:27Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, divergent environments resolve ticket status conflicts deterministically
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:09:23Z**
18+
19+
## Description
20+
**What**: After sync rebase, detect divergent STATUS events from different environment IDs. Most-STATUS-events-wins heuristic (count net STATUS transitions, not raw events including reverts). Timestamp tiebreaker. Conflict log. Auto-unblock after resolution.
21+
**Why**: Without conflict resolution, sync produces arbitrary state from last-timestamp-wins. The informed session's work should take precedence.
22+
**Scope**:
23+
- IN: Conflict detection, most-STATUS-events-wins (net transitions), conflict log, auto-unblock after sync (reuse w21-8011 function), environment ID from dso-0k2k SC13
24+
- OUT: Conflict resolution for non-STATUS events (LTW is sufficient)
25+
26+
## Done Definitions
27+
- Divergent STATUS events from different env IDs are detected after sync ← Satisfies SC6
28+
- Most-STATUS-events-wins counts net transitions (not raw events) with timestamp tiebreaker ← Satisfies SC6 + adversarial review
29+
- Conflict log records every resolution (env IDs, event counts, winning state) ← Satisfies SC6
30+
- Auto-unblock check runs after conflict resolution using w21-8011 reusable function ← Satisfies SC3 (sync path)
31+
- Environment ID sourced from dso-0k2k SC13 (.env-id) ← adversarial review
32+
- Unit tests passing
33+
34+
## Considerations
35+
- [Reliability] Revert edge case documented: ticket reverted repeatedly accumulates STATUS events. Net-transition count mitigates this vs raw count.
36+
- [Reliability] Clock skew affects timestamp tiebreaker — documented as known limitation
37+
38+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

‎.tickets/w21-6k7v.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: w21-6k7v
3+
status: open
4+
deps: [w21-p1y3]
5+
links: []
6+
created: 2026-03-20T05:07:26Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, I can sync ticket events with remote environments without timeout risk
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:09:07Z**
18+
19+
## Description
20+
**What**: Split-phase ticket sync: fetch (no flock) → acquire flock → rebase (local, <2s) → release flock → push (no flock, retry). Last-timestamp-wins as default reducer.
21+
**Why**: Remote environments must exchange ticket events. Split-phase design ensures flock is never held during network I/O, preventing timeout.
22+
**Scope**:
23+
- IN: ticket sync command, split-phase design, retry with backoff, 30s network timeouts, pluggable reducer strategy interface
24+
- OUT: Conflict resolution heuristic (w21-05z9 plugs into reducer interface)
25+
26+
## Done Definitions
27+
- ticket sync pushes/pulls events via split-phase (flock only during local rebase) ← Satisfies SC5
28+
- Network phases have 30s individual timeouts with retry on non-fast-forward ← Satisfies SC5, SC9
29+
- flock held only during local operations (<2s) ← Satisfies SC9
30+
- Reducer exposes pluggable strategy interface for conflict resolution ← adversarial review (S4/S5 interface)
31+
- Unit tests passing
32+
33+
## Considerations
34+
- [Reliability] Window between flock release and push: events committed locally but not yet pushed. Next sync catches them.
35+
- [Maintainability] Pluggable reducer strategy must be clean enough for w21-05z9 to swap in most-STATUS-events-wins
36+
37+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

‎.tickets/w21-6llo.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
id: w21-6llo
3+
status: open
4+
deps: [w21-k2yz, w21-6k7v]
5+
links: []
6+
created: 2026-03-20T05:07:35Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, I can archive closed tickets without breaking dependency references
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:09:25Z**
18+
19+
## Description
20+
**What**: ticket archive command for closed tickets. Protect tickets with open dependents or children. Tombstones for archived tickets. Sync-before-compact precondition.
21+
**Why**: Without archiving, the event log grows without bound. Dependency-aware archiving prevents orphaned references.
22+
**Scope**:
23+
- IN: ticket archive, protection check (open dependents + children), tombstone file (ID, type, final status), sync-before-compact, skip tickets with remote SNAPSHOTs
24+
- OUT: Automatic scheduled archiving (future enhancement)
25+
26+
## Done Definitions
27+
- ticket archive removes closed tickets from active set ← Satisfies SC7
28+
- Tickets with open dependents or open children are protected from archiving ← Satisfies SC7
29+
- Archived tickets retain tombstone (ID, type, final status) queryable by dependency graph ← Satisfies SC7 + adversarial review
30+
- Compaction syncs before compacting and skips tickets with remote SNAPSHOTs ← Satisfies SC7
31+
- Unit tests passing
32+
33+
## Considerations
34+
- [Reliability] Inbound LINK references from other tickets must resolve against tombstones, not fail
35+
- [Reliability] sync-before-compact requires sync infrastructure (w21-6k7v) — dependency is set
36+
37+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

‎.tickets/w21-8011.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: w21-8011
3+
status: open
4+
deps: [w21-k2yz]
5+
links: []
6+
created: 2026-03-20T05:07:24Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, closing a ticket automatically reports which blocked tickets are now ready
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:08:44Z**
18+
19+
## Description
20+
**What**: When ticket transition closes a ticket, automatically identify newly unblocked tickets and include them in output. Extract unblock logic as reusable function for sync (w21-05z9).
21+
**Why**: Agents need proactive notification of unblocked work, not just polling.
22+
**Scope**:
23+
- IN: Unblock detection on close, output format, reusable function with event-source parameter (local vs sync)
24+
- OUT: Sync-triggered unblock (w21-05z9 reuses this function)
25+
26+
## Done Definitions
27+
- Closing a ticket reports newly unblocked tickets in command output ← Satisfies SC3
28+
- Unblock logic is a reusable function accepting event-source parameter (local-close vs sync-resolution) ← adversarial review
29+
- Burst scenarios (closing many tickets) batch graph queries rather than calling per-ticket ← adversarial review
30+
- Unit tests passing
31+
32+
## Considerations
33+
- [Reliability] Unblock function must work for both local close and remote sync contexts
34+
- [Performance] Batch graph traversal in burst scenarios
35+
36+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

‎.tickets/w21-goqp.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
id: w21-goqp
3+
status: open
4+
deps: []
5+
links: []
6+
created: 2026-03-20T05:07:35Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, agents are prevented from directly editing ticket event files
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:09:31Z**
18+
19+
## Description
20+
**What**: PreToolUse hook that blocks Edit/Write/Bash modifications to .tickets-tracker/ files. Redirects agents to ticket commands. Allowlist for ticket CLI patterns.
21+
**Why**: The event sourcing model requires writes go through ticket commands to maintain invariants. Direct edits would corrupt the event log.
22+
**Scope**:
23+
- IN: PreToolUse hook, pattern matching on command strings, allowlist for ticket CLI commands (ticket create, ticket sync, etc.), redirect error message
24+
- OUT: Blocking Read access (intentionally allowed for debugging)
25+
26+
## Done Definitions
27+
- PreToolUse hook blocks Edit/Write/Bash modifications targeting .tickets-tracker/ ← Satisfies SC8
28+
- Ticket CLI commands (ticket *) are allowlisted and not blocked ← Satisfies SC8
29+
- Blocked attempts show clear error message redirecting to ticket commands ← Satisfies SC8
30+
- Unit tests passing
31+
32+
## Considerations
33+
- [Maintainability] Hook must pattern-match on command strings — use allowlist approach (block all .tickets-tracker/ references except ticket * commands)
34+
35+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

‎.tickets/w21-k2yz.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
id: w21-k2yz
3+
status: open
4+
deps: []
5+
links: []
6+
created: 2026-03-20T05:07:23Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, I can track dependencies between tickets and query which are ready to work
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:08:37Z**
18+
19+
## Description
20+
**What**: LINK/UNLINK events for dependency relations (blocks, depends_on, relates_to). ticket deps command with ready_to_work. Cycle detection.
21+
**Why**: Foundation for multi-agent orchestration — agents need to know which tickets are ready.
22+
**Scope**:
23+
- IN: ticket link, ticket unlink, cycle detection (dependency edges only, not hierarchy), ticket deps, graph cache, tombstone-awareness for archived tickets
24+
- OUT: Auto-unblock (w21-8011), sync (w21-6k7v), archiving (w21-6llo)
25+
26+
## Done Definitions
27+
- ticket link/unlink create LINK/UNLINK events ← Satisfies SC1
28+
- ticket deps returns graph with ready_to_work boolean (direct blockers only) ← Satisfies SC2
29+
- Cycle detection rejects circular dependencies (dependency edges only, not hierarchy) ← Satisfies SC1 + adversarial review
30+
- Graph traversal <2s at 1,000 tickets (per-call SLA; burst callers batch/debounce) ← Satisfies SC9 + adversarial review
31+
- Graph is tombstone-aware for archived tickets ← adversarial review
32+
- Unit tests passing
33+
34+
## Considerations
35+
- [Performance] Dense graphs need dedicated graph cache
36+
- [Reliability] LINK events must survive compaction
37+
- [Maintainability] Visited-set in traversal prevents infinite loops
38+
39+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

‎.tickets/w21-p1y3.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: w21-p1y3
3+
status: open
4+
deps: []
5+
links: []
6+
created: 2026-03-20T05:07:25Z
7+
type: story
8+
priority: 1
9+
assignee: Joe Oakhart
10+
parent: w21-54wx
11+
---
12+
# As a developer, all my worktrees see the same ticket state instantly via shared storage
13+
14+
15+
## Notes
16+
17+
**2026-03-20T05:08:49Z**
18+
19+
## Description
20+
**What**: All worktrees on same machine share .tickets-tracker/ via symlinks. Commands resolve to canonical real path before flock.
21+
**Why**: Multiple agent sessions on the same machine must see consistent ticket state instantly.
22+
**Scope**:
23+
- IN: Symlink creation during worktree setup, canonical path resolution, auto-detect existing worktree via git worktree list
24+
- OUT: Remote sync (w21-6k7v), conflict resolution (w21-05z9)
25+
26+
## Done Definitions
27+
- All worktrees see same ticket state via shared .tickets-tracker/ symlinks ← Satisfies SC4
28+
- All commands resolve .tickets-tracker/ to canonical real path before flock ← Satisfies SC4 + adversarial review
29+
- Auto-detect existing .tickets-tracker/ worktree before creating new one ← Satisfies SC4
30+
- Unit tests passing
31+
32+
## Considerations
33+
- [Reliability] Symlink creation must handle existing real directory (auto-init ran before symlink setup)
34+
- [Reliability] Canonical path resolution prevents flock inconsistency between symlink and real path
35+
36+
**Escalation policy**: Proceed unless a significant assumption is required to continue. Escalate only when genuinely blocked. Document all assumptions.

0 commit comments

Comments
 (0)