Skip to content

[Docs] ADR-MF-02 — Neutral Workflow / Claims (design gate for PR-2) #159

Closed

Description

@Rwanbt

Problem

Work management is currently GitHub-specific in terminology and policy. The
Multi-Forge architecture freezes a provider-neutral "Work Authority" model and a
claim protocol with durable local journaling, but that decision cluster exists only
in the external architecture document. It must be recorded as an accepted ADR
before the workflow/claims implementation (PR-2) starts.

Source: Multi-Forge v1.3.2-final §17, §45–54 (ADR-MF-02).

Expected outcome

An accepted ADR (decisions only) that freezes:

  • Terminology: Work Authority, WorkItem, ChangeRequest, WorkAuthorityRef.
  • Ownership: the skill/harness owns remote facts; ainative/forge.py owns a pure
    local resolver; observed candidates are diagnostic only.
  • Claim identity: principal <provider>:principal:<stable-provider-id>; event
    <provider>:<event-kind>:<stable-event-id>; V1 event kinds comment, note,
    assignment; UTC timestamps; winner ordering
    (created_at_utc, canonical_event_identifier).
  • ClaimAttempt journal under .ai-native/state/claim-attempts/: local, durable,
    non-authoritative, non-Verified; PENDING attempt written durably before the
    remote POST.
  • Outcomes: CONFIRMED, LOST, CONFLICT, UNCERTAIN, ABANDONED; refusal
    codes CLAIM_CONFLICT, CLAIM_UNCERTAIN, CLAIM_JOURNAL_UNAVAILABLE;
    ABANDONED is an explicit operator transition; a new claim is allowed only after
    explicit abandonment; no automatic re-POST of an uncertain attempt.
  • No leases, no heartbeat, no age-based expiry, no remote API clients.

Acceptance criteria

  • ADR written in docs/adr/ following the repository series format; decisions
    only; incorporates the frozen points above.
  • The local resolver contract is stated as pure (no network, no credential
    lookup, no writes, no provider API calls, no push authorization).
  • Journal-before-POST and fail-closed semantics for corrupted/unwritable
    journals are explicit.
  • Rejected alternatives recorded (leases/heartbeats, retry-on-uncertain,
    remote claim service, provider API clients in the neutral layer).
  • Accepted by the maintainer before PR-2 begins.
  • Issue [Feature] Add a designed stale-claim expiration for multi-agent issue claims #33 (stale claim lifecycle) and [MV-19] Managed Git guard hook file and authenticated local IPC #120 (managed Git guard / push
    mediation) remain independent and unchanged.

Out of scope

  • Implementing the workflow neutralization or the resolver (PR-2).
  • GitLab/GitHub WorkItem API clients (explicitly excluded architecture-wide).
  • Leases, heartbeats, expiration services.

Context

  • docs/GITHUB-WORKFLOW.md — current GitHub-specific policy.
  • skills/issue-to-implementation/ — current claim-resolution implementation.
  • Blocks PR-2 (with PR-1 green).

Dependencies

Activity

  1. added
    type:docsDocumentation work
    priority:P1Major user-facing defect or release blocker
    on Sep 16, 2026
  2. Rwanbt commented on Sep 16, 2026

    @Rwanbt
    OwnerAuthor

    Reopened: this work was merged into main by mistake. main has been restored to its pre-merge state (9301253); the tested work now lives on dev (merge commit 0721237). The Issue stays open until the final dev -> main promotion, once the whole plan is implemented and tested.

  3. reopened this on Sep 16, 2026
  4. Rwanbt commented on Sep 17, 2026

    @Rwanbt
    OwnerAuthor

    Done: the work is merged into main (squash 8f319ad via PR #176, full CI matrix green including the Production Gate). Closed as completed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P1Major user-facing defect or release blockertype:docsDocumentation work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions