Skip to content

feat: persist resumable audit runs and queue explicit idempotent GitHub sync #296

Description

@bearmug

Audit baseline: aa595438650cfbaa6db310792929c6219cc003b2 (origin/main at audit start).

Problem

Long audits and subagent fan-outs can finish useful local work while connectivity or GitHub authentication is unavailable. There is no durable audit run ledger, resumable work graph, or local issue outbox, so a terminal/network interruption risks lost work or duplicate external writes.

This is related to future Forge lifecycle #102 but is not duplicate: #102 does not specify offline checkpoints, queued GitHub drafts, idempotent reconnect sync, or ambiguity-after-timeout handling.

Proposed MVP

Persist a versioned run directory keyed by repository and run ID containing:

  • baseline SHA/repository/phase/status and last checkpoint;
  • stable work-item IDs, inputs, dependencies, attempts, output artifact paths/hashes;
  • normalized finding IDs and dedupe evidence;
  • GitHub issue drafts with idempotency key, draft|pending|synced|conflict|failed, attempts, last error, and resulting issue number/URL.

Use atomic local writes. Resume skips completed work with matching hashes and reruns only incomplete/invalidated items.

Expose explicit status/resume/sync actions. Sync must be user-invoked after network/auth returns, query stored numbers/idempotency markers before creation, mark ambiguous already-created issues as synced, and stop on conflicts.

Safety / non-goals

  • No hidden background GitHub writes or auto-sync merely on reconnect.
  • No credentials/tokens in run state.
  • No push, merge, release, tag, or npm publish behavior.
  • Existing approval requirements remain in force.

Acceptance criteria

  • Kill/restart resumes a multi-work-item audit without rerunning completed items.
  • Offline/auth failure leaves inspectable drafts and loses no findings.
  • Repeated explicit sync after timeout creates at most one issue per idempotency key.
  • Conflicts and permanent auth failures remain queued with actionable status.
  • Fake-adapter tests cover offline, timeout-after-create, reconnect, duplicate, conflict, and interrupted sync.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions