follow architecture gate requirements from sprint plan

keep changes deterministic and test backed

existing editor src modules and mcp toolchain

whetstone mcp stable binary and workspace config

datasets project benchmarks challenging fullstack multifile 2026 02 26 jsonl

no regression in existing mcp tool behavior

generated task queue is ready or blockers are explicit

All sprint step tests pass

No regression in existing MCP tool behavior

Generated task queue is ready or blockers are explicit

Follow architecture gate requirements from sprint plan

Keep changes deterministic and test-backed

Existing editor/src modules and MCP toolchain

whetstone_mcp stable binary and workspace config

Goals

Constraints

Dependencies

Acceptance Criteria

Semantic Planning Packet (Auto-Extracted)

compatibility concurrency contract high_confidence_clear_path migration performance raw_structural_projection replay risk rollout security semantic transaction

Intake Foundation Primary


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

compatibility concurrency contract depends_on_prior_tasks migration performance raw_structural_projection replay risk rollout security semantic transaction

Execution Readiness Primary


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

Intake Foundation Primary [whetstone_generate_taskitems]


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

Execution Readiness Primary [whetstone_queue_ready]


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

Intake Foundation Primary [whetstone_validate_taskitem]


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

Execution Readiness Primary [whetstone_generate_taskitems]


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

Intake Foundation Primary


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria

Execution Readiness Primary


All sprint step tests pass

Goals

Constraints

Dependencies

Acceptance Criteria


add 5 attribution columns to registry table db v12 migration derived from prior art license author node ids attribution version

implement get apiary tool name attribution returning authorship metadata json

implement post apiary tool name attribution with patch semantics for updating attribution fields

implement get apiary tool name download returning tool source as application x tar tarball

update ingestion agent py to parse attribution json from tool submissions write stub if not found

register whetstone as founding tool via orchestrator register whetstone py script

write 5 pytest integration tests in tests test s20 attribution py

python 3 9 compatible no x y union types no walrus operator

db migration must use alter table idempotent guard if not exists pattern where supported

get download must handle missing repo path with 404 not unhandled exception

post attribution has patch semantics only update fields present in request body

ingestion must write a stub attribution json when none found in repo path

no hardcoded paths use registry repo path from db

s18 contributions table exists for future attribution credit flow

s19 hypergraph tables exist problem type linkage

existing registry table in jobs queue db columns tool name repo path language capabilities required

existing ingestion agent py mqtt handler for borg registry commit topic

db v12 migration runs without error all 5 new columns present on registry table

get apiary test tool attribution returns valid json with fields tool name author node ids derived from prior art license attribution version

post attribution updates only specified fields get reflects changes without clobbering unspecified fields

get download returns content type application x tar with schema json inside the archive

unknown tool returns 404 on get attribution and get download

ingesting a tool with attribution json stores parsed author node ids derived from license correctly

Architect Review — S20 Apiary Attribution


add 5 attribution columns to registry table db v12 migration derived from prior art license author node ids attribution version

implement get apiary tool name attribution returning authorship metadata json

implement post apiary tool name attribution with patch semantics for updating attribution fields

implement get apiary tool name download returning tool source as application x tar tarball

update ingestion agent py to parse attribution json from tool submissions write stub if not found

register whetstone as founding tool via orchestrator register whetstone py script

write 5 pytest integration tests in tests test s20 attribution py

python 3 9 compatible no x y union types no walrus operator

db migration must use alter table idempotent guard if not exists pattern where supported

get download must handle missing repo path with 404 not unhandled exception

post attribution has patch semantics only update fields present in request body

ingestion must write a stub attribution json when none found in repo path

no hardcoded paths use registry repo path from db

s18 contributions table exists for future attribution credit flow

s19 hypergraph tables exist problem type linkage

existing registry table in jobs queue db columns tool name repo path language capabilities required

existing ingestion agent py mqtt handler for borg registry commit topic

db v12 migration runs without error all 5 new columns present on registry table

get apiary test tool attribution returns valid json with fields tool name author node ids derived from prior art license attribution version

post attribution updates only specified fields get reflects changes without clobbering unspecified fields

get download returns content type application x tar with schema json inside the archive

unknown tool returns 404 on get attribution and get download

ingesting a tool with attribution json stores parsed author node ids derived from license correctly

Architect Review Final — S20 Apiary Attribution


extend accounts table with display name account type bio public key columns db v13

create prior art table for founding contributions

implement post accounts and get accounts node id with sufficiency bracket calculation

implement get accounts node id contributions paginated 3 table join with contributions registry jobs

implement get accounts node id credits lightweight bracket summary

implement post prior art with idempotent ecu bonus award on first registration

implement get prior art with node id and verified query filters

implement calculate bracket as a pure function no db access

insert 7 governance params on migration founding contribution bonus ecu sufficiency threshold 1 sufficiency threshold 2 account weighting exponent individual account weighting exponent cooperative account weighting exponent nonprofit account weighting exponent enterprise

python 3 9 compatible no x y union types no walrus operator

calculate bracket must be a pure function with no side effects and no db access

post prior art must be idempotent same title node id combination never double credits ecu

post accounts upsert uses insert or replace semantics on node id

weighting exponent must vary by account type sourced from governance params

no new tables beyond v13 additions do not alter tables from s18 s19

s18 contributions table exists for contribution history join

s21 prior art and accounts tables are prerequisites for s24 founding contributions script

existing accounts table created in migrate v3 sql

db v13 migration runs without error prior art table exists accounts has 4 new columns

post accounts creates account get accounts id returns weighting exponent matching account type governance param

get accounts id credits returns bracket normal for zero balance

ecu award causes bracket to transition correctly at sufficiency threshold 1 10000 and sufficiency threshold 2 50000

get accounts id contributions returns paginated list with fields contribution id tool name job type ecu amount track created at

post prior art awards founding contribution bonus ecu ecu second call with same title node id is idempotent

get prior art filters correctly by node id query param

Architect Review — S21 Account System


extend accounts table with display name account type bio public key columns db v13

create prior art table for founding contributions

implement post accounts and get accounts node id with sufficiency bracket calculation

implement get accounts node id contributions paginated 3 table join with contributions registry jobs

implement get accounts node id credits lightweight bracket summary

implement post prior art with idempotent ecu bonus award on first registration

implement get prior art with node id and verified query filters

implement calculate bracket as a pure function no db access

insert 7 governance params on migration founding contribution bonus ecu sufficiency threshold 1 sufficiency threshold 2 account weighting exponent individual account weighting exponent cooperative account weighting exponent nonprofit account weighting exponent enterprise

python 3 9 compatible no x y union types no walrus operator

calculate bracket must be a pure function with no side effects and no db access

post prior art must be idempotent same title node id combination never double credits ecu

post accounts upsert uses insert or replace semantics on node id

weighting exponent must vary by account type sourced from governance params

no new tables beyond v13 additions do not alter tables from s18 s19

s18 contributions table exists for contribution history join

s21 prior art and accounts tables are prerequisites for s24 founding contributions script

existing accounts table created in migrate v3 sql

db v13 migration runs without error prior art table exists accounts has 4 new columns

post accounts creates account get accounts id returns weighting exponent matching account type governance param

get accounts id credits returns bracket normal for zero balance

ecu award causes bracket to transition correctly at sufficiency threshold 1 10000 and sufficiency threshold 2 50000

get accounts id contributions returns paginated list with fields contribution id tool name job type ecu amount track created at

post prior art awards founding contribution bonus ecu ecu second call with same title node id is idempotent

get prior art filters correctly by node id query param

Architect Review Final — S21 Account System


implement localtoolcache c class in drone include local tool cache h 600 lines max

implement sync to fetch get apiary index and download matching tools as tarballs

implement find tool to scan cache dir subdirectories for schema json with matching job type field

implement execute to run run tool sh subprocess with payload validation against schema json

implement post observation to post results to nexus observations with solved locally true

implement inventory returning json of cached tools for mqtt publish

wire localtoolcache into job poller h cpp constructor takes optional localtoolcache nullptr disabled

call cache sync on startup in on job ready check cache before nexus claim

add no local cache flag to main cpp default cache enabled dir hivemind dir tools

publish hivemind nodes id tool cache mqtt retained message after sync with tool count and synced at

c 20 cmake build zero compilation warnings

localtoolcache header must not exceed 600 lines

localtoolcache constructor takes optional localtoolcache nullptr disabled no crash

payload validation checks required fields from schema json only no full json schema validation

execute timeout sourced from governance params local tool max timeout s default 120

ecu cost computed from duration s times profile rate no external api call

no hardcoded paths cache dir and nexus url from config passed to constructor

s20 get apiary tool download endpoint must exist tarball download

existing job poller h cpp and main cpp structure in drone

existing nexus observations post endpoint

existing mqtt broker connection in drone

localtoolcache compiles with zero errors and zero warnings

sync called against running nexus populates cache dir with downloaded tool tarballs

find tool returns populated cachedtool when matching schema json present in cache dir

mqtt tool cache retained message appears on broker after sync

execute runs a test shell tool and returns toolresult with success true and duration s populated

job matching cached tool drone logs executing locally no nexus claim request sent observation at get observations

job not matching cached tool drone proceeds with normal nexus claim flow

3 3 shell integration tests pass cmake build exits 0

Architect Review — S22 Drone Local Cache


implement localtoolcache c class in drone include local tool cache h 600 lines max

implement sync to fetch get apiary index and download matching tools as tarballs

implement find tool to scan cache dir subdirectories for schema json with matching job type field

implement execute to run run tool sh subprocess with payload validation against schema json

implement post observation to post results to nexus observations with solved locally true

implement inventory returning json of cached tools for mqtt publish

wire localtoolcache into job poller h cpp constructor takes optional localtoolcache nullptr disabled

call cache sync on startup in on job ready check cache before nexus claim

add no local cache flag to main cpp default cache enabled dir hivemind dir tools

publish hivemind nodes id tool cache mqtt retained message after sync with tool count and synced at

c 20 cmake build zero compilation warnings

localtoolcache header must not exceed 600 lines

localtoolcache constructor takes optional localtoolcache nullptr disabled no crash

payload validation checks required fields from schema json only no full json schema validation

execute timeout sourced from governance params local tool max timeout s default 120

ecu cost computed from duration s times profile rate no external api call

no hardcoded paths cache dir and nexus url from config passed to constructor

s20 get apiary tool download endpoint must exist tarball download

existing job poller h cpp and main cpp structure in drone

existing nexus observations post endpoint

existing mqtt broker connection in drone

localtoolcache compiles with zero errors and zero warnings

sync called against running nexus populates cache dir with downloaded tool tarballs

find tool returns populated cachedtool when matching schema json present in cache dir

mqtt tool cache retained message appears on broker after sync

execute runs a test shell tool and returns toolresult with success true and duration s populated

job matching cached tool drone logs executing locally no nexus claim request sent observation at get observations

job not matching cached tool drone proceeds with normal nexus claim flow

3 3 shell integration tests pass cmake build exits 0

Architect Review Final — S22 Drone Local Cache


add get health endpoint returning ok true ts iso without hitting the db

add get status endpoint with 11 runtime fields status nexus version started at uptime s db path db schema version mqtt host active jobs count pending jobs count registered nodes count active inference last run

add sigterm and sigint graceful shutdown handlers in lifespan context using signal module

add shutting down module level boolean flag not per request

add 503 guard on post jobs id claim when shutting down is true

add log startup banner function printing version db path schema version mqtt host listen address

add rotate log if needed log rotation on startup truncate to last 1000 lines if file exceeds 10mb

write deploy install nexus daemon sh idempotent launchd install script for macos borgswarm

python 3 9 compatible no x y union types no walrus operator

get health must never hit the db under any circumstances pure liveness probe

get status must return all 11 specified fields with correct types int for counts iso string for timestamps

shutting down flag is module level not stored per request or per connection

log rotation must execute before logger initialization not after

install nexus daemon sh must be idempotent unload before load safe to run multiple times

existing nexus api py lifespan context asynccontextmanager pattern already in place

existing governance params key last inference run at written by active inference py

orchestrator com hivemind nexus plist already exists at correct path

get health returns ok true ts iso datetime with http 200

get health returns ok false error db unreachable with http 503 when db file missing

get status returns all 11 fields status nexus version started at uptime s db path db schema version mqtt host active jobs count pending jobs count registered nodes count active inference last run

uptime s value increases between two consecutive get status calls

post jobs id claim returns 503 when shutting down is true

post jobs id claim returns 200 normal behavior when shutting down is false

install nexus daemon sh is executable idempotent exits 0 when nexus becomes healthy within 10s

4 4 pytest tests pass all testable without launchd

Architect Review — S23 Nexus Daemon


add get health endpoint returning ok true ts iso without hitting the db

add get status endpoint with 11 runtime fields status nexus version started at uptime s db path db schema version mqtt host active jobs count pending jobs count registered nodes count active inference last run

add sigterm and sigint graceful shutdown handlers in lifespan context using signal module

add shutting down module level boolean flag not per request

add 503 guard on post jobs id claim when shutting down is true

add log startup banner function printing version db path schema version mqtt host listen address

add rotate log if needed log rotation on startup truncate to last 1000 lines if file exceeds 10mb

write deploy install nexus daemon sh idempotent launchd install script for macos borgswarm

python 3 9 compatible no x y union types no walrus operator

get health must never hit the db under any circumstances pure liveness probe

get status must return all 11 specified fields with correct types int for counts iso string for timestamps

shutting down flag is module level not stored per request or per connection

log rotation must execute before logger initialization not after

install nexus daemon sh must be idempotent unload before load safe to run multiple times

existing nexus api py lifespan context asynccontextmanager pattern already in place

existing governance params key last inference run at written by active inference py

orchestrator com hivemind nexus plist already exists at correct path

get health returns ok true ts iso datetime with http 200

get health returns ok false error db unreachable with http 503 when db file missing

get status returns all 11 fields status nexus version started at uptime s db path db schema version mqtt host active jobs count pending jobs count registered nodes count active inference last run

uptime s value increases between two consecutive get status calls

post jobs id claim returns 503 when shutting down is true

post jobs id claim returns 200 normal behavior when shutting down is false

install nexus daemon sh is executable idempotent exits 0 when nexus becomes healthy within 10s

4 4 pytest tests pass all testable without launchd

Architect Review Final — S23 Nexus Daemon


write orchestrator register founding contributions py as a standalone idempotent script

implement dry run flag that prints what would be registered without modifying any state

implement verify only flag that checks db state and exits 0 if all conditions met

step a upsert founder account via post accounts with node id founder

step b seed 17 canonical problem types via post problems insert or ignore semantics

step c register 5 founding prior art works via post prior art idempotent by title node id

step d seed hypergraph nodes for all 17 problem types with founded by edge type

step e print summary table of founder ecu balance prior art count problem types seeded hypergraph nodes created

add founding contribution decay rate governance param default 0 95

python 3 9 compatible no x y union types no walrus operator

script must be idempotent running twice produces identical db state with no double credits

uses only existing api endpoints post accounts post prior art post problems no direct db access

no new api endpoints needed for this sprint

no db migration needed uses tables created in s21

dry run must not create update or delete any db state

s21 prior art table post accounts endpoint post prior art endpoint must exist

s19 hypergraph nodes and hypergraph edges tables must exist

nexus must be running at nexus url environment variable for api calls

dry run prints registration plan with all 5 works and 17 problem types without modifying db

founder account with node id founder exists after first run

17 problem types present in problem types table after run

5 prior art entries present in prior art table after run second run leaves count at exactly 5

hypergraph has nodes for at least 10 of the 17 problem types after run

founder account ecu balance is at least 5 times founding contribution bonus ecu

verify only exits with code 0 when all 5 prior art entries and 17 problem types are present

Architect Review — S24 Founding Contributions


write orchestrator register founding contributions py as a standalone idempotent script

implement dry run flag that prints what would be registered without modifying any state

implement verify only flag that checks db state and exits 0 if all conditions met

step a upsert founder account via post accounts with node id founder

step b seed 17 canonical problem types via post problems insert or ignore semantics

step c register 5 founding prior art works via post prior art idempotent by title node id

step d seed hypergraph nodes for all 17 problem types with founded by edge type

step e print summary table of founder ecu balance prior art count problem types seeded hypergraph nodes created

add founding contribution decay rate governance param default 0 95

python 3 9 compatible no x y union types no walrus operator

script must be idempotent running twice produces identical db state with no double credits

uses only existing api endpoints post accounts post prior art post problems no direct db access

no new api endpoints needed for this sprint

no db migration needed uses tables created in s21

dry run must not create update or delete any db state

s21 prior art table post accounts endpoint post prior art endpoint must exist

s19 hypergraph nodes and hypergraph edges tables must exist

nexus must be running at nexus url environment variable for api calls

dry run prints registration plan with all 5 works and 17 problem types without modifying db

founder account with node id founder exists after first run

17 problem types present in problem types table after run

5 prior art entries present in prior art table after run second run leaves count at exactly 5

hypergraph has nodes for at least 10 of the 17 problem types after run

founder account ecu balance is at least 5 times founding contribution bonus ecu

verify only exits with code 0 when all 5 prior art entries and 17 problem types are present

Architect Review Final — S24 Founding Contributions


create db v14 migration with federation peers table id peer url peer id shared resources last sync at first seen at active

add 4 federation governance params federation sync interval minutes 15 federation max peers 10 federation job offer timeout s 30 this swarm id generated uuid

implement post federation peers verifying peer reachability via get peer url health before insert

implement get federation peers listing all peers with sync status

implement delete federation peers id performing soft delete sets active 0

implement get federation apiary delta since iso returning tools modified after timestamp metadata only no source

implement post federation job offers checking local node capabilities against requirements create local job copy if accepted

implement get federation observations delta since iso returning aggregated observation stats never raw content

implement run federation sync async background task running in lifespan loop

python 3 9 compatible no x y union types no walrus operator

get federation observations delta must never return raw observation content only aggregates

post federation peers must verify peer reachability before inserting reject with error if unreachable

delete federation peers sets active 0 soft delete only never hard delete from table

this swarm id must be auto generated uuid on first run if not already in governance params

run federation sync background loop must not block lifespan startup

federation is opt in per resource type apiary job offers observations in shared resources json

s20 get apiary tool download and updated at column on registry for delta sync

s23 get health endpoint on nexus used by peer reachability check before registration

s24 attribution data present in registry for apiary delta content

httpx async http client available in python environment

db v14 migration runs without error select from federation peers returns empty table

post federation peers rejects unreachable peer url with connection refused error does not insert

get federation apiary delta returns only tools where updated at is after the since parameter

post federation job offers returns accepted true local job id when matching node capability exists

post federation job offers returns accepted false reason when no matching node capability

two nexus instances on different ports register as peers register tool on a trigger sync tool appears on b

run federation sync background task starts and logs completion within sync interval

Architect Review — S25 Federation


create db v14 migration with federation peers table id peer url peer id shared resources last sync at first seen at active

add 4 federation governance params federation sync interval minutes 15 federation max peers 10 federation job offer timeout s 30 this swarm id generated uuid

implement post federation peers verifying peer reachability via get peer url health before insert

implement get federation peers listing all peers with sync status

implement delete federation peers id performing soft delete sets active 0

implement get federation apiary delta since iso returning tools modified after timestamp metadata only no source

implement post federation job offers checking local node capabilities against requirements create local job copy if accepted

implement get federation observations delta since iso returning aggregated observation stats never raw content

implement run federation sync async background task running in lifespan loop

python 3 9 compatible no x y union types no walrus operator

get federation observations delta must never return raw observation content only aggregates

post federation peers must verify peer reachability before inserting reject with error if unreachable

delete federation peers sets active 0 soft delete only never hard delete from table

this swarm id must be auto generated uuid on first run if not already in governance params

run federation sync background loop must not block lifespan startup

federation is opt in per resource type apiary job offers observations in shared resources json

s20 get apiary tool download and updated at column on registry for delta sync

s23 get health endpoint on nexus used by peer reachability check before registration

s24 attribution data present in registry for apiary delta content

httpx async http client available in python environment

db v14 migration runs without error select from federation peers returns empty table

post federation peers rejects unreachable peer url with connection refused error does not insert

get federation apiary delta returns only tools where updated at is after the since parameter

post federation job offers returns accepted true local job id when matching node capability exists

post federation job offers returns accepted false reason when no matching node capability

two nexus instances on different ports register as peers register tool on a trigger sync tool appears on b

run federation sync background task starts and logs completion within sync interval

Architect Review Final — S25 Federation