Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

docs(offers): publish consumer authority and receipt ports [H3,H16]

Corey Olson9b47591cad0e
diff --git a/docs/api.md b/docs/api.md
index 34edf335..6fc50b2a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -673,3 +673,12 @@ When `publish.pullRequest` is enabled, `pullboard publish` reconciles the GitHub
A board-recorded item merge covers its introduced commits only when its exact submitted commit has that receipt and is an ancestor of the recorded merge. `Pullboard-Companion: #N` is covered only on a board-recorded trunk containing item N's landing. Unreceipted commits, including release bumps and synthetic publication commits, remain unverified. An outside PR is allowed and initially reads `not verified`; the JSON result's `verification[].intake` names the existing `pullboard intake` command that files it for review. Outside intake can cover only its exact accepted head, never its earlier commits by inference.
The JSON result includes `verification` entries with PR number, exact head, state, assurance, receipt identities, and any unverified commit IDs. GitHub statuses are shared by PRs with the same head: if an outside or unproven PR shares a commit with a proven proposal, the shared status stays red rather than lending the proposal's green status to it. Publishing observes and posts statuses; it never merges a PR or requires outside authors to use Pullboard.
+
+
+## Cross-board offer and private receipt contracts
+
+`src/item-offer.js` exposes `acceptItemOffer`, `declineItemOffer`, `itemOfferAnnouncement`, `recordItemOfferResult` and `readItemOffer`. An `ItemOffer` has exactly `{ version: 1, offerId, sourceBoardId, parentItem, destinationBoardId, proposedContent, disposition, childRef, reason }`. Pending offers have null child/reason; accepted results name `{boardId,item}` on the destination; declines carry a reason. Disclosed proposal fields are `lane`, `title`, and optional `criterion`, `specIds`, `brief`, `route`, `check`; a foreign parent never becomes a destination-local parent. State announcements omit `proposedContent` entirely. The destination stores only a request digest and state result, and retries return the same child after reopening SQLite. Different content or dispositions under the same source/offer id conflict.
+
+Consumers supply the existing canonical resolver as `resolveBoardRef(id) -> {boardId}` without alias normalization here, their local `boardId`, and a synchronous authenticated `authorize({action,boardId,document})` port. Actions are `accepted`, `declined`, and `receive-result`. The port must verify the appropriate source/destination authority for the exact document; there is no permissive default. The destination's synchronous `createChild(content)` port must perform its native child move on this same board and return its item id. Invoke these contracts inside the consumer's ordered move: child creation and the destination retry record share one SQLite transaction. Source result delivery is a separately authorized, idempotent transaction. These contracts add no offer orchestration, two-board transaction or landing sequencer.
+
+`minimalItemReceipt(fields,{sign})` accepts only `{version:1,sourceBoardId,item,commit,verifier,verdict}` and appends `integrity:{digest,signature}` over canonical permitted bytes. `verifyItemReceipt(receipt,{resolveBoardRef,verify},expected)` requires all expected references to match, checks the digest, and calls `verify(bytes,signature,sourceBoardId)` against the consumer's established source trust. Signatures are supplied through the existing authority adapter; a digest alone proves no authority. Titles, criteria, notes and unknown fields are refused even on verification. Private landing consumers still establish the real landing and verdict before issuing this reduced envelope.
diff --git a/src/next-step-defaults.js b/src/next-step-defaults.js
index e75f3dca..6e630edd 100644
--- a/src/next-step-defaults.js
+++ b/src/next-step-defaults.js
@@ -1,5 +1,9 @@
/** General CLI recovery text; operation-owned codes live in src/moves/ [P4,C7]. */
export const DEFAULT_NEXT_STEPS = Object.freeze({
+ "ITEM_OFFER": "refresh the offer using its exact permitted fields and canonical source and destination references",
+ "OFFER_AUTHORITY": "obtain the source or destination authority for this exact offer action on its actual board",
+ "OFFER_CONFLICT": "use the original offer and recorded disposition, or create a new offer id for different content",
+ "ITEM_RECEIPT": "obtain the exact minimal source receipt and verify its item, commit and verifier/verdict through the established trust port",
"GIT_SYNC_LOG": "restore the append-only refs/pullboard/board history on origin before running pullboard sync",
"GIT_SYNC_REMOTE": "restore read/write access to origin, then retry the original command or run pullboard sync; keep its pending sealed move",
"GIT_SYNC_LOCAL_CHANGED": "run pullboard export to preserve local moves, then ask the coordinator to reconcile the local and remote prefixes before syncing",