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
docs: a change to an approved spec row reaches the person as a proposal
Corey Olson710ec4208740
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 55a998a3..d9d5e67b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,8 @@ Notable changes to Pullboard, for people using it. The format follows [Keep a Ch- Pull requests get a 'verified by a second agent' status that teams can require; a pull request made outside Pullboard shows as not verified. (#988)+- Agents can propose a change to an approved spec row, such as a moved gate file; it waits in Needs you with the old and new text until you approve or decline it. (#980)+- A test that needs a desktop runs only on a runner with a confirmed logged-in session; the runner checks again before it starts. (#1134)- You can pair a second phone or browser with the command the page shows. (#978)diff --git a/docs/api.md b/docs/api.mdindex 60c3ab20..fe580171 100644--- a/docs/api.md+++ b/docs/api.md@@ -189,6 +189,8 @@ For example: `flow: review wait average 61 min (1 measured; > 60 min); bottlenec`spec draft "<rule>" --doctrine --source "chat, 2026-10-16"` proposes a sourced doctrine row and returns a qualified `id`, such as `doctrine:DR1`, for the existing person approval commands. Resume adds `doctrineNotes`, an array of newly seen approved rules with `id`, `text` and `gate`; each checkout consumes its own notices. Drafts and pending applications are excluded. The shared approved doctrine also supplies frozen citations and stale-item comparisons in older checkouts.+`spec draft "<new text>" --revises <approved-id> --reason "why" [--gate "<check>"] [--status <status>]` records a board-only proposal at a distinct id. It preserves the exact old row and proposed replacement, including fields not changed. Omit the text for a gate-only or status-only change. `spec approve <proposal-id>` and `spec decline <proposal-id> --reason "why"` are person-only decisions. Approval remains pending `spec apply`; decline leaves the approved target unchanged. If the target changed meanwhile, approval refuses and a fresh proposal is required. The ordered row history retains the proposal, reason and person decision. A missing approved gate with a recorded Git rename names its current path and a literal revision command.+`hook pre-merge-commit` runs the same staged checks as `hook pre-commit` before Git creates an automatic merge commit. `init` and `hooks` install it; `doctor` names it when absent at Git's effective hook path. Lane ownership comes from `HEAD:pullboard.json`, so an unstaged configuration edit cannot grant a lane new folders. `lane add` writes the new lane to the working `pullboard.json` and returns `{ lane, owns }`; commit the file before the lane's ownership takes effect. `init` returns the lanes it proposes as `proposedLanes`, each `{ name, owns }`, and writes none of them. Lane-sensitive checks refuse a repository with `info/grafts` in its Git common directory because grafts alter ancestry even when replacement objects are disabled.`join` and `worktree` require a free-text `--model` label or `PULLBOARD_MODEL` environment value; labels are not inferred from a provider or family. Rejoining the same worktree preserves its agent id; the model label is required on every join, and omitting the optional `--family` preserves its prior declaration. `pullboard.json` may set `agents.names` to `suffix` (the default, `web-1 (Claude)`) or `prefix` (`claude-web-1`). CLI `agent` fields remain stable ids; `displayName` shows the chosen style. `resume.me` and API state `agents[]` carry `model` and `displayName`; older agents with no model display `unknown`. Each event records the actor model in `event_detail.model` for a registered agent, with `unknown` for legacy agents without a declaration. `show` includes `item_builder_family` and each verdict's `verdict_verifier_family`. These family fields are `null` when the agent did not declare a family, and later declarations do not rewrite prior submissions or verdicts.diff --git a/docs/formats.md b/docs/formats.mdindex c25b0500..911a951c 100644--- a/docs/formats.md+++ b/docs/formats.md@@ -168,6 +168,8 @@ Engine 52 reopens an accepted item that conflicts with the trunk for a main mergEngine 55 (`ROW_DRAFT_ENGINE`) adds `draftSpecRow`: an agent in a lane worktree records a drafted spec row on the board, since SPEC.md is the coordinator's file and a lane cannot write it. The move carries `row: {id, text, gate, tier, section, target}` and `written`. Every writer of a new row reserves its id with this move, in one write transaction, before any file names the id: a lane's spec draft, the main checkout's spec draft and doctrine rulings, Rigor and blueprints. The sender plans the id from its files; the board takes that id or the next number after it that no draft holds, so writers that planned the same id at the same moment get distinct ids, and the same row again keeps the id it reserved. `written: true` marks a writer that puts the row in its own file now; only unwritten spec drafts, which come from lanes, are written by spec apply. Until spec apply writes it, the commit-msg hook and `spec check` read a board draft as a draft row, so a lane cites the returned id at once and its worktree stays clean. The coordinator's `spec apply` writes each pending board draft into SPEC.md at its own id, and the person approves it there as before; a draft counts as applied once SPEC.md has its id. A move carrying `draftSpecRow` requires engine 55, and older engines refuse it before changing their board or cursor. Engine 54 is the strong-rejection notice above; engine 53 was reserved for unshipped board watches, now allocated engine 56 because engines 54 and 55 shipped first.+Approved-row revision proposals use `row_drafts` entries with `revises`, `file`, exact `source` and `replacement`, proposed `status`, and `reason`; they are never materialized as new SPEC rows. The `decideSpecRevisions` operation accepts only the authenticated person channel and the exact pending proposal. An approval records a normal target-row decision with a canonical signed `revision` reference (proposal id, target, file, source, replacement, reason and proposer). A decline records the disposition without replacing the target's existing approval. Proposal dispositions retain their decision event and person attribution. Revision-bearing drafts and decisions, and the new disposition operation, negotiate the revision engine floor; older readers refuse before changing the board or cursor. Ordinary historical row-decision signatures keep their original canonical bytes.+Engine 56 (`BOARD_SENTINEL_ENGINE`) adds board-owned watch proposals, exact person approve/decline decisions, ordered due-run claims and completed run receipts. Approval binds the entire execution definition; changing it creates a pending proposal. Replay records history without executing commands. Every non-cancelled red run records `sentinel:<name>` for Rigor; feed notices only mark failure and recovery transitions. Older engines refuse these operations and this new cause form before replay. Published engine-55 readers reject these moves by their newer engine number before interpreting an operation.The board's committed `flakes.rerun` setting defaults off. Off retains released execution, including landing's whole-file diagnosis and first legacy `landing_flake`; the new ledger still records the original failure. On permits one exact-target diagnostic for a supported structured Node test at unchanged source, never green-by-retry. Built-in `node --test` is supported; a `bin/run-tests.js` script is recognized only when its committed bytes on candidate and pinned main match the bundled Native runner. Its filename alone does not establish selector support, and a probe that executes other targets remains unclassified. A pinned green main marks a possible regression, not a flake. Unknown selectors, source changes or unsupported remote execution evidence remain unclassified; no local substitute is run for a remote admission. A confirmed second sighting drafts an ordinary strong repair item, not an approved spec or doctrine row. A landed repair reads fixed until another sighting. Enabled landing consumes its captured pair without another legacy diagnosis or first-sighting legacy defect; saved typed relationships prevent remeasurement on adoption. Diagnostic-recording failures are reported while the original red and completed evidence remain retained. Older engines refuse the new operation and typed landing relationships before changing rows or the replay cursor; legacy `landing_flake` meaning and the schema/event-log versions are unchanged.