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.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(merge): every seat has an address, so an outside agent [H2,H16,N26]
Corey Olson8f41bc4a8318
diff --cc docs/api.mdindex 31b8ee73,6011e4be..c2ff47a8--- a/docs/api.md+++ b/docs/api.md@@@ -678,46 -674,6 +678,50 @@@ A board-recorded item merge covers itsThe 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.+`pullboard why <file>[:<line>] --json` uses the `why file` catalog shape; this names the file form, not a literal `file` argument. It traces commits on the repository's actual primary branch, then resolves their item trailers, served row IDs and answered decisions in one board query. The legacy `why <id>` shape is unchanged. Answered decisions carry their recorded origin, statement, rationale, decider and relayer; absent historical provenance remains `unknown`. Row and item origins are also `unknown` unless recorded, rather than inferred from a related decision. An agent may label a relayed or inherited answer but cannot use that label to mint a person-origin record. Unproven original decider identities remain unknown, with the answering relay seat recorded separately.+++### Cross-board decision handoffs++`decisionHandoffs(db, { boardId, authorize })` in `src/decision-handoff.js` is+an I-D persistence port, not an aggregation CLI or a board-name resolver.+Each participant supplies its own SQLite connection, opaque immutable board ID,+and existing authority adapter. Call mutations inside the caller’s ordered+write boundary. No transaction or database connection spans boards.++`deliver(handoff, options)` checks the exact version-1 wire shape and original+option-set digest, then asks `authorize("disclose", handoff)` and, for answers,+`authorize("answer", handoff)`. The adapter must authenticate the requester,+source decision, destination, question, option digest and answer; a supplied+opaque authority value alone grants nothing. Accepted deliveries persist before+returning. Transport retries the returned wire independently at the other board.+Changed correlation or a conflicting answer refuses; late questions preserve+answers. `optionsDigest(options)` hashes a unique option set independent of order.++`query(source, participants, authority)` requires source-board read authority+for the exact namespaced reference and participant set. It returns+`{ complete, agreed, answers }`; callers must not act on an incomplete or+disagreeing result. Each destination contributes at most one answer, and a+query cannot omit a destination already recorded for that source decision.+This contract stores and returns answers to the source/requester’s authorized+query; it does not execute the decision or grant cross-board authority.+++## 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.+## Agent lifecycle nudges++`init` merges project-local Claude Code `.claude/settings.json` and Codex `.codex/hooks.json` handlers for `SessionStart` and `Stop`, preserving other handlers and settings. Each installed line resolves the local, main-checkout or PATH executable and calls `pullboard hook <event>`; a missing executable exits successfully without output. `init --no-hooks` skips these agent nudges. Existing Git gate hooks are independent. `hooks uninstall` removes only Pullboard's exact agent-handler lines.++`SessionStart` returns the normal resume card as `hookSpecificOutput.additionalContext`. `Stop` returns a `systemMessage` when this seat has committed, unsubmitted work. A local error or two-second worker timeout returns a warning and exit zero, with no blocking decision. Unknown events are silent no-ops. These shapes follow the current [Codex hooks](https://learn.chatgpt.com/docs/hooks) and [Claude Code hooks](https://code.claude.com/docs/en/hooks) contracts.++`doctor --json` adds `agentHooks`, with each vendor's `configured` flag, installed `events`, and `trust`. Codex trust is `unverified`: file installation never grants vendor trust, and the Stop reminder may be off until the person reviews the exact definitions with `/hooks`. Text doctor output reports configured hooks; with no agent-hook files it retains its existing one-line clean-board result.+++ ### Seat addresses++ `whoami.address` and each `agents` entry expose `pullboard:<board-id>:<percent-encoded-seat-id>`. The address uses the persistent board identity and registered seat id, not its checkout path. Send with `pullboard shout <address> "<text>"` from a checkout linked to that board with the sender’s own grant; the existing sealed relay authenticates the sender and orders the ordinary shout. Another board’s address is refused with `SEAT_ADDRESS_BOARD`. An address grants no access, and revoked credentials cannot deliver a message.diff --cc src/commands/shout.jsindex 1fa988fa,a30f238e..06e34a83--- a/src/commands/shout.js+++ b/src/commands/shout.js@@@ -1,6 -1,7 +1,8 @@@+ import { Refused } from '../refused.js';+ import { addressedSeat } from '../seat-address.js';/** The pullboard shout command, in its own module so an item adding another command never edits these lines. */import * as store from '../board.js';+import { requireReadableShout } from '../shout-readable.js';import {COORDINATOR,} from '../config.js';@@@ -21,12 -22,16 +23,17 @@@ importexport async function run(io, { first, second, rest, values }) {const act = (work) => actOn(io, work);return act(async (ctx, board, me) => {+ const recipient = addressedSeat(first, store.boardId(board));+ const addressed = typeof first === 'string' && first.startsWith('pullboard:');+ if (addressed && values.item !== undefined) throw new Refused('USAGE', 'use either a seat address or --item, not both');const evidence = values.evidence === undefined ? null : evidenceFrom(ctx, values);- const recipients = ['all', 'person', ...laneNames(ctx.config), ...board.db.prepare('SELECT agent_id FROM agent').all().map((agent) => agent.agent_id)];- const hasRecipient = first && recipients.includes(first) && (values.item === undefined || second !== undefined);- const to = values.item !== undefined ? `item:${values.item}` : hasRecipient ? first : values.decision ? (me.id === COORDINATOR ? 'person' : COORDINATOR) : first ?? '';+ const seatIds = board.db.prepare('SELECT agent_id FROM agent').all().map((agent) => agent.agent_id);+ if (addressed && recipient !== COORDINATOR && !seatIds.includes(recipient)) throw new Refused('NO_READER', 'copy the address of a joined seat from pullboard agents');+ const recipients = ['all', 'person', ...laneNames(ctx.config), ...seatIds];+ const hasRecipient = first && (addressed || recipients.includes(first)) && (values.item === undefined || second !== undefined);+ const to = values.item !== undefined ? `item:${values.item}` : hasRecipient ? recipient : values.decision ? (me.id === COORDINATOR ? 'person' : COORDINATOR) : first ?? '';const text = [hasRecipient ? second : first, ...(hasRecipient ? rest : [second, ...rest])].filter(Boolean).join(' ');+ requireReadableShout(text);const id = await ordered(ctx, board, 'shout', [{ from: personShout(io, me) ? store.PERSON : me.id, to, text, ...(values.item !== undefined ? { item: Number(values.item) } : {}), lanes: laneNames(ctx.config), decision: Boolean(values.decision), ...(values.news ? { news: true } : {}), evidence }]);io.result?.({ id, decision: Boolean(values.decision) });const agents = store.listAgents(board);diff --cc src/next-step-defaults.jsindex 1242eea5,c9959188..7475f2b0--- a/src/next-step-defaults.js+++ b/src/next-step-defaults.js@@@ -1,13 -1,6 +1,14 @@@/** General CLI recovery text; operation-owned codes live in src/moves/ [P4,C7]. */export const DEFAULT_NEXT_STEPS = Object.freeze({+ "SHOUT_SPACES": "rewrite the shout with spaces between words, then send it again",+ "DECISION_HANDOFF_BINDING": "use the exact versioned handoff, namespaced source decision and original option set",+ "DECISION_HANDOFF_AUTH": "obtain authority for this exact question, answer or source query",+ "DECISION_HANDOFF_CONFLICT": "use the recorded answer or create a new source decision",+ "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",+ "SEAT_ADDRESS_BOARD": "open a linked checkout of the addressed board with your own grant, then run pullboard shout <address> <text>","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",