Repository navigation
[Docs] ADR-MF-02 — Neutral Workflow / Claims (design gate for PR-2) #159
Copy link
Copy link
Closed
Labels
priority:P1Major user-facing defect or release blockerMajor user-facing defect or release blockertype:docsDocumentation workDocumentation work
Description
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.pyowns 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 kindscomment,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
codesCLAIM_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
- None. Blocks PR-2 ([Feature] Neutral workflow, Work Authority and claim journal (PR-2) #163).
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
priority:P1Major user-facing defect or release blockerMajor user-facing defect or release blockertype:docsDocumentation workDocumentation work
Activity
docs(adr): ADR-MF-02 - neutral workflow, work authority and claims (R…
Rwanbt commentedon Sep 16, 2026
Reopened: this work was merged into
mainby mistake.mainhas been restored to its pre-merge state (9301253); the tested work now lives ondev(merge commit 0721237). The Issue stays open until the finaldev->mainpromotion, once the whole plan is implemented and tested.feat: Multi-Forge v1 — production promotion (dev -> main) (#176)
Rwanbt commentedon Sep 17, 2026
Done: the work is merged into
main(squash 8f319ad via PR #176, full CI matrix green including the Production Gate). Closed as completed.