Claims and Packets

Conditional claims

A conditional claim is a shared operation that can reject a competing holder. The claim ID names the work, not the agent. Choose the work's natural identity and period so independent workers compute the same key.

A generic lease record can contain claim_id, agent, status, claimed_at, expires_at, note and result_ref. The documented database example uses a condition equivalent to attribute_not_exists(claim_id) OR expires_at < :now. The worker must inspect and honor a refusal, renew while active and reconcile the destination before retrying an external action.

Expiry must be checked by the claim logic rather than assumed from eventual cleanup of an old row. Choose the lease duration to suit the job. The database example's lease is a separate protocol from the file packet tool's 12-hour claim-freshness rule; do not substitute one for the other.

A file convention can reveal known ownership but is not automatically a shared atomic lease. To claim exclusion, test simultaneous claims, expiration, renewal failure, stale owners and checks at the actual write boundary. Keep storage outages read-only or reversibly isolated until ownership and authorization are known.

Packet schema and commands

The documented implementation uses a Markdown file per packet, with YAML front matter and seven body sections. It is an implementation reference, not a bundled installed command-line tool. Verify the available version's help and behavior before use.

Fictional packet template; replace placeholders before use:

---
id: JP-YYYY-MM-DD-example-task
title: Example training summary
state: CLAIMED
owner: assigned-coordinator
function: documentation
requester: authorized-requester
surface: authorized-workspace
opened: YYYY-MM-DDTHH:MMZ
recheck: YYYY-MM-DD
class: internal-note
qa_required: L0
bakeoff: no
deliver_to: requester
visibility: team
related: []
---

## Ask (verbatim)
<The requester's exact words>

## Decisions
<Time, decision-maker, decision and reason>

## Checkpoints
<Time, worker, action, artifact revision and evidence>

## QA
<Rung, reviewer, time, PASS/FAIL/WAIVED and what was opened>

## Artifacts
<Paths, URLs or hashes; never secret values>

## Next click
<One bounded next action and owner>

## Verified
<What was opened, what was observed, when; or NO and the gap>

Packet states are OPEN, CLAIMED, QA, DONE, PARKED. An OPEN packet has no owner. PARKED needs a dated recheck. Documented classes are internal-note, repo-change, shared-rule, publish, partner-deliverable, client-deliverable and money-credentials-delete. The class determines the minimum rung; a packet can raise it, not quietly lower it.

The source-inspected command set is: find, new, claim, checkpoint, decide, qa, handoff, award, receipt, note, park, close, now-row, board, lint.

The external-record checks have a recorded --ack "<reason>" override. It can bypass normal record refusals; it does not supply authority, complete a missing review or prevent the actual external action. A failed review should reopen the affected work operationally, but the documented qa FAIL transition only changes QA to CLAIMED. A packet already DONE requires explicit state reconciliation through the authorized workflow; do not assume the command reopened it.

The inspected QA acceptance function uses the highest historical PASS or WAIVED in the packet, without invalidating it after a later FAIL or binding it to the current artifact revision. Its minimum-rung acceptance therefore does not prove fresh independent review or that every compounded rung was completed; verify those separately before delivery and closure.

The documented file-tool claim freshness is 12 hours; a claim without a checkpoint for 3 days produces a warning; the maximum recheck is 30 days. These are implementation defaults, not the separate conditional-store lease duration. Takeover still requires reconciliation of live work and prior actions.

A packet can record permission and evidence but cannot create them. Enforcing a send requires a pre-action gate in the actual executor, tested with competing claims and bypass paths. No such end-to-end installation is certified by this guide.