flyloft 0.1.0__tar.gz

flyloft-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads the version from git tags
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ty check src
+
+  tests:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:18
+        env:
+          POSTGRES_PASSWORD: flyloft
+          POSTGRES_DB: flyloft_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      FLYLOFT_TEST_DATABASE_URL: postgresql://postgres:flyloft@127.0.0.1:5432/flyloft_test
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run pytest -q

flyloft-0.1.0/.github/workflows/python-publish.yaml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # trusted publishing: PyPI accepts this workflow's OIDC token, no API token
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads the version from the release tag
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

flyloft-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+src/flyloft/_version.py

flyloft-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

flyloft-0.1.0/AGENTS.md

@@ -0,0 +1,58 @@
+# Working on flyloft
+
+flyloft runs swarms of agents that conduct machine-learning experiments on a lab's Slurm clusters. Read `docs/VISION.md` for what it is and why, and `docs/ARCHITECTURE.md` for how it is shaped and staged. This file is about how to work on it.
+
+## The north star
+
+Clear, concise code and design. No overengineering. Staged implementation. End-to-end tests that recapitulate real use.
+
+This project can fall into a complexity spiral: agents solving imagined problems, adding generality nobody asked for, and building for stages that do not exist yet. Every rule below exists to stop that. When a rule and your instinct disagree, follow the rule and tell the human.
+
+## Rules
+
+1. **Know the stage.** `docs/ARCHITECTURE.md` names the current stage and its end-to-end scenario. Everything you build serves that scenario.
+2. **Build only what the scenario exercises.** If a change is not reachable from the current stage's scenario, do not make it. Not as a helper, not as a hook, not as preparation.
+3. **Generalize only along the shape list.** The architecture names the few decisions that may be general at cardinality one: identities, entry types, interfaces. Everything else is concrete. No interface with one implementation. No flag with one value in use. No handling for a failure nobody has observed.
+4. **Prefer deletion.** The smaller diff wins. Removing code is progress.
+5. **Solve encountered problems.** A problem counts when it has happened in a test, a live run, or a review. "It could happen" is not encountered.
+6. **Park ideas; do not build them.** When you see something the system will need later, add one line to the deferred list in `docs/ARCHITECTURE.md` and tell the human. Never build it quietly.
+7. **Test end to end.** Every stage has a scenario test that does what a researcher would do and checks what a researcher would check. Every feature is reachable from one. Unit tests are for intricate logic, not for coverage.
+8. **Design before code.** Brainstorm, present the design, get approval, write the plan, then build. Small tasks get a short design in chat; the approval gate does not shrink with the task.
+
+## The smell of the spiral
+
+Stop and reconsider when you notice any of these in your own work:
+
+- "While I'm here" or "for future use".
+- A class named Manager, Handler, Framework, Engine, or Base.
+- An abstract base class or protocol with one implementation.
+- A configuration option, environment variable, or flag with one value in use.
+- A retry, fallback, or recovery path for a failure that has never occurred.
+- A helper module that exists to be shared by code that does not exist yet.
+- A design section or plan task that cannot name the scenario it serves.
+- A test that exercises a branch no scenario reaches.
+
+## Documents
+
+- `docs/VISION.md`: what flyloft does and why. Approved; change only with the human.
+- `docs/ARCHITECTURE.md`: the spine, the subsystem boundaries, the stage plan, the shape list, the deferred list.
+- `docs/design/`: one design document per stage, written when the stage begins, never earlier.
+- `docs/plans/`: implementation plans, one per stage design.
+
+This branch is a fresh design. Documents stand alone and do not describe the system relative to any earlier flyloft implementation.
+
+## Setup and tests
+
+- `uv sync` installs everything. Run commands as `uv run ...`.
+- `uv run pytest` runs tiers one and unit tests. It starts a PostgreSQL container with Docker unless `FLYLOFT_TEST_DATABASE_URL` is set.
+- `FLYLOFT_LIVE=1 uv run pytest -m live` runs tier two against the configured cluster and test repository.
+- `uv run flyloft --help` lists the CLI.
+- Before committing: `uv run ruff format .`, `uv run ruff check .`, `uv run ty check src`. CI runs the same three plus the tests on every pull request.
+- Releases: publish a GitHub release tagged `vX.Y.Z`. The version comes from the tag, and the publish workflow uploads to PyPI.
+
+## Working with the human
+
+- One question at a time. Prefer questions with options.
+- Present a design and stop for approval before writing code, however small the change.
+- Report outcomes faithfully. Failing tests are reported with their output. Skipped steps are named.
+- Scope changes, budget changes, and anything that touches the vision go to the human. Do not decide them.

flyloft-0.1.0/CLAUDE.md

@@ -0,0 +1,3 @@
+All instructions for working in this repository are in AGENTS.md. Read and follow it.
+
+@AGENTS.md

flyloft-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: flyloft
+Version: 0.1.0
+Summary: Agent swarms for empirical research on Slurm clusters
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp>=2
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12

flyloft-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,265 @@
+# flyloft Architecture
+
+Status: approved 2026-09-21. Stage 1 complete on 2026-09-23 (see [design/stage-1.md](design/stage-1.md)); stage 2 complete on 2026-09-23 (tiers one, two, and three passed; see [design/stage-2.md](design/stage-2.md)). Current stage: 3, not yet designed.
+
+This document settles the shape of flyloft: the record that holds its state, the lifecycle and authority rules, the agent turn, the subsystem boundaries, and the stages by which the system grows. It fixes what is expensive to change later and leaves everything else to the design document of the stage that needs it. [VISION.md](VISION.md) says what flyloft is for; [AGENTS.md](../AGENTS.md) says how to work on it. This document is the bridge between them.
+
+## 1. Context and constraints
+
+**What flyloft is.** A research service operated by one lab. It runs agents that turn scientific questions into experiments on the lab's Slurm clusters, holds the record of what was tried and learned, and returns evidence researchers can inspect and steer. The full account is in the vision. The smallest campaign uses one implementing agent; the largest is a swarm of tens.
+
+**Where things run.**
+
+| Component | Where |
+|---|---|
+| Service, PostgreSQL, tool surface, dashboard | The lab-operated flyloft host |
+| Agent processes, coding harnesses, worktrees | The flyloft host, as local processes |
+| Experiments | Any Slurm cluster the lab can reach, local or cloud-hosted |
+| Model inference | Wherever a campaign's configuration points: an institutional endpoint or a hosted provider |
+
+flyloft hosts the agents. This rules out vendor-hosted agent runtimes, in which a provider runs the loop and a sandbox on its own servers, for three reasons. The record must be the only state, and a hosted session store would be a second one. Every action must pass through granted tools, and a vendor sandbox's built-in tools would not. Code and data stay under lab control, with only prompt content leaving the host. Model choice is unconstrained by this boundary, and the per-campaign rule holds: a campaign configured for institutional inference never falls back to a hosted model.
+
+**Standards.** There is no standard for the shared-record layer, and no lab has published one; each has rolled its own. MCP is the standard for how agents call tools, and flyloft's tool surface is an MCP server. The record's schema is flyloft's own. Everything else in the coordination layer is chosen on merit.
+
+**Lineage.** The hypothesis board is a blackboard in the sense of Hearsay-II: roles are knowledge sources posting to a shared structure, and the orchestrator with its attention queue is BB1's control blackboard. Two 2026 papers on governed shared memory name provenance collapse, stale propagation, and lost dissent as the failure modes of agent coordination layers. Those are the failure modes the vision's currency, contradiction, and reconstructability requirements exist to prevent. References are at the end.
+
+**Stack.** Python 3.12, uv, pydantic v2, typer, psycopg, the official MCP Python SDK, and PostgreSQL with numbered SQL migrations.
+
+## 2. The record
+
+All state lives in PostgreSQL in four kinds of table. All identities are UUIDs.
+
+**Entries** are append-only. Every communication and every state change is an entry with a campaign, a kind, an author, a time, a mandatory summary, and a typed body validated against the schema for its kind. The author is an agent or a human. Nothing is updated or deleted.
+
+**Links** connect an entry to another entry or to an entity, with a named relation such as tests, refutes, reviews, or supersedes. Provenance is a walk over links: a finding's chain to its hypothesis, runs, commits, and artifacts is this table.
+
+**Entities with state** are campaign, agent, hypothesis, and run. Each carries a current-state column. State changes only by posting an entry, and the column is updated in the same transaction. The entry is the truth; the column is a convenience that must equal what the entries imply, and a test enforces that equality. A finding is also an entity, created by a finding entry; at stage one it has nothing to transition and carries no state column, and stage two adds one.
+
+At least these columns:
+
+- *campaign*: project, question, success criterion, baseline, constraints, submission cap, state.
+- *agent*: campaign, role, substrate, workspace path, state, last turn.
+- *hypothesis*: campaign, state, the proposal entry.
+- *run*: hypothesis, tested commit, cluster, job identity, application state, raw scheduler state, last observed, run directory.
+- *finding*: campaign, hypothesis, the finding entry.
+
+**Turns** record one row per agent turn: agent, role, substrate, the path of the rendered assignment on disk, the entry identities assembled into its context, exit status, duration, and tokens and cost where the substrate reports them. Entries carry the turn that produced them. This is how any decision can be reconstructed: what the agent was given is on disk, which entries it saw is in the row, and what it produced is a query.
+
+**Entry kinds at stage one.** Seven.
+
+| Kind | Author | Effect |
+|---|---|---|
+| proposal | agent | Creates a hypothesis |
+| run_request | agent | Creates a run against a hypothesis and a commit |
+| result | system | Evidence or failure diagnostics for a finished run |
+| assessment | agent | Reads a result that did not support the hypothesis, moves its state, states the next step |
+| finding | agent | A supported claim with provenance; creates a finding and moves the hypothesis to supported |
+| question | agent | Asks a human |
+| steering | human | An instruction or decision for the campaign |
+
+An assessment must link to the run whose result it judges. It exists so an agent has a typed place to say what a result means and what it will try next, without a free-form note kind that would drift toward chat. Later roles add kinds such as critique, digest, and decision. The tables do not change.
+
+**Two kinds of state.** The record holds decisions and evidence. Observed external state, meaning Slurm job status and pull request status, lives on the entity row with a last-observed timestamp. Posting an entry per queue poll would drown the record; the system posts one result entry when a run reaches a terminal state. The timestamp satisfies the vision's currency requirement with one column.
+
+## 3. Lifecycle and authority
+
+**Hypothesis lifecycle at stage one.**
+
+| State | Entered by |
+|---|---|
+| proposed | a proposal entry |
+| testing | a run_request entry |
+| supported | a finding entry |
+| refuted, inconclusive, unexecuted | an assessment |
+| abandoned | the campaign stopping or concluding with the hypothesis open |
+
+Stage two changes the last step: a finding entry leaves the hypothesis in testing, and a critique that accepts the finding moves it to supported. Later stages insert screened and admitted between proposed and testing, and replicated before review. States are text and transitions are code, so this growth is not shape.
+
+**Run lifecycle.** preparing, queued, running, finished, failed, canceled, unknown. The application state is derived from observed scheduler state. A job missing from the queue is unknown until confirmed, never assumed finished. A finished job without its expected result files yields an incomplete result, not a conclusion.
+
+**Campaign lifecycle.** active, blocked, stopped, done. Blocked means a human is needed: an agent asked a question or a turn failed. Stopped means a human stopped new work; outstanding runs finish and are collected.
+
+**Agent state.** idle, active, blocked. The active state is the claim that prevents a second concurrent turn for the same agent. It lives on the agent, not the campaign.
+
+**Authority** is a mapping from role to entry kinds, enforced at one place: the tool surface. An agent's tool server is launched for its turn with its role's tool list, so an implementer cannot post steering because no such tool exists in its session.
+
+| Role | May post |
+|---|---|
+| implementer | proposal, run_request, assessment, finding, question |
+| critic | critique |
+| system | result |
+| human | steering; and campaign creation, stop, and run cancellation through the CLI |
+
+The question, success criterion, and baseline are campaign columns written at creation, with no tool that changes them. An agent that disagrees with them posts a question. This is the whole enforcement of the vision's most important guard.
+
+## 4. The turn
+
+A turn is one disposable process. The system assembles context, launches the agent through its substrate, the agent acts through tools, the process exits, and the system records what happened. No agent process exists while the cluster is working.
+
+**Wake rule.** An agent gets a turn when its campaign is active, it is idle, and an entry it did not author has appeared since its last turn. A turn counts toward the wake rule when it posts an entry, whatever its exit status; a turn that posted nothing leaves what it saw still new to the agent. At stage one that means campaign start, a result, or steering. The same rule later serves inboxes and digests, since those are entries.
+
+**Assembly** is a function of role, agent, and campaign that produces one rendered assignment, written to disk and referenced from the turn row. At stage one it renders the campaign's question, criterion, baseline, and constraints; the project's research brief from its repository; the submissions remaining; and the whole record so far: hypotheses with states, runs with results, findings, assessments, and steering. A single campaign's record fits in a turn's context, so there is no read tool. Run directories are on the same host, so the assignment names them and the agent reads logs from disk.
+
+**Tools.** The implementer's MCP server exposes five tools, one per entry kind it may post: propose, request_run, assess, post_finding, ask. Each validates its body against the kind's schema and returns errors in the turn, so the agent corrects mistakes before it exits. Two rules live in request_run: the worktree must be clean and HEAD is recorded as the tested commit; and one run may be outstanding per campaign. The tool records intent and returns a run identity. Staging and submission happen after the turn, and the agent learns the outcome from the result entry in its next turn. SSH latency and submission failures never enter the agent's process.
+
+**Substrates.** A substrate executes a turn: run this assignment with these tools and report exit status. Two exist at stage one, which is what justifies the interface. The coding-harness substrate launches a harness headless in the worktree with the assignment as its prompt and the tool server configured. The scripted substrate, used in tests, connects to the same tool server and issues tool calls from a script. Every role runs in a coding harness or the scripted substrate; a role that does not edit code runs under a read-only tool policy. A native tool-calling loop is deferred until a role's harness overhead or a subscription's limits are observed to be a problem.
+
+**Workspace.** One git worktree per agent off the campaign branch. The agent commits its own changes. Publication pushes the branch and opens or updates the pull request when a critic accepts a finding.
+
+**Ending.** A turn ends when the process exits. A turn that exits without posting anything blocks the campaign with diagnostics. There is no conclude action: when the agent believes the campaign is finished, it asks, and the human's steering stops the campaign. The end decision stays with a person until the orchestrator exists at stage five.
+
+## 5. Subsystems and process shape
+
+One Python application. Subsystems are modules with owned responsibilities, not services.
+
+| Module | Owns | Stage |
+|---|---|---|
+| record | The four kinds of table, entry schemas, links, state transitions. The only code that touches PostgreSQL. | 1 |
+| tools | The MCP server: per-role tool lists, validation, calls into record. | 1 |
+| turns | The wake rule, assembly, substrates, turn rows. | 1 |
+| workspace | Clone and worktree per agent, clean-tree check, branch push. | 1 |
+| runs | Staging, Slurm submission, observation, collection, result entries. | 1 |
+| publication | Pull request create and update from findings. | 1 |
+| cli | Register a project, start a campaign, status, steer, stop, cancel. | 1 |
+| config | Projects, clusters, harnesses, credentials. | 1 |
+| service | The tick: reap, wake, submit, observe, cancel, publish; startup reconciliation. | 1 |
+| web | Read API and dashboard over record. | 3 |
+| budget | Ledger and admission beyond a submission cap. | 3 |
+| evaluation | Replication policy, promotion. | 4, 6 |
+| knowledge | Proximity, cross-campaign memory. | 4 |
+| direction | Islands, orchestrator, librarians, decisions. | 5 |
+| recovery | Reconciliation after interruption. | When a stage loses work |
+
+**Dependency rules.** Only record writes to the database. Only runs calls the cluster. Only workspace and publication call git and GitHub. No agent path reaches any of them directly.
+
+**Process shape at stage one.** Three kinds of process share PostgreSQL through the record module.
+
+```mermaid
+flowchart LR
+    R[Researcher] --> CLI
+    CLI --> PG[(PostgreSQL)]
+    S[Service] <--> PG
+    S -->|launch turn| H[Harness]
+    H -->|stdio| T[Tool server]
+    T --> PG
+    H --> M[Model endpoint]
+    S -->|ssh| C[Slurm clusters]
+    S --> G[GitHub]
+```
+
+- **The service.** One long-running process whose tick wakes agents, launches turns, stages and submits runs, observes jobs, and publishes.
+- **Per-turn processes.** The harness, and the tool server it launches as a stdio subprocess with the agent and turn identity in its environment. The server writes entries through record.
+- **The CLI.** Short-lived. It reads the record for status and posts steering entries.
+
+Two processes write to the record from the first turn, the service and the tool server, so PostgreSQL is a stage-one necessity rather than preparation.
+
+**The record is the control channel.** Human commands are steering entries. Stop transitions the campaign in the same transaction. Cancel marks the run, and the service issues the cancellation on its next observation. There is no control socket, and every intervention is in the record by construction.
+
+## 6. How the system grows
+
+**Shape versus features.** The system can fail in two ways: from identities baked in wrong early, and from complexity nobody needed. Both are avoided by one rule. The *shape* of the system, its identities and interfaces, is right from the start even at cardinality one. *Features* are built only when a stage's scenario requires them. The following is the closed list of what may be general at cardinality one. Everything not on it is concrete.
+
+1. An agent is an entity distinct from its campaign, and has a role.
+2. All inter-turn state is typed entries; entity state columns are derived.
+3. Provenance is a links table.
+4. Every turn records the context it was given.
+5. UUID identities.
+6. Agents act only through the tool surface, with tool lists per role.
+7. A substrate interface, justified by two implementations.
+8. A worktree per agent.
+9. PostgreSQL with numbered SQL migrations.
+10. Question, criterion, and baseline are immutable campaign columns.
+11. Observed external state lives on entity rows with a last-observed timestamp.
+12. Human actions are entries; the record is the control channel.
+
+**Stages.** Each stage is a system a researcher could use for real work. Its end-to-end scenario is its only acceptance. Each stage gets one design document in `docs/design/`, written when the stage begins, and one plan in `docs/plans/`.
+
+**Stage 1: one implementer.** A researcher registers the toy project and starts a campaign with a question, criterion, baseline, and submission cap. The agent establishes the baseline, proposes a change, runs it, assesses the result, posts a finding, and a pull request appears carrying the finding and its provenance. The researcher posts an instruction and the next turn honors it. The researcher stops the campaign and the open hypothesis is abandoned. Failure paths in scope: a failed job yields unexecuted, an agent that exits without posting blocks the campaign, missing metrics yield an incomplete result.
+
+**Stage 2: a critic.** A finding is a candidate until a critic, running in a harness under a read-only tool policy, accepts it or blocks it with a demand for more runs. Only accepted findings reach the pull request. Adds the critique kind, finding state, per-role harness and model selection, and role wake filters. First communication between roles through the record.
+
+**Stage 3: several implementers.** Hypotheses in flight in parallel, each in its own worktree, admitted up to a concurrency limit. An integrator merges accepted implementations and keeps the branch runnable. A read-only web view shows the board. The same question runs with one and several implementers, reporting verified improvement and cost: the first control arm. Adds the budget ledger and moves the tool server to HTTP with per-turn tokens.
+
+**Stage 4: a population.** Generators with distinct framings propose. Proximity merges duplicates and flags repeats from earlier campaigns. A coordinator admits under a posture and orders replication. Adds the decision kind, the screened and admitted states, replication policy, and the knowledge module.
+
+**Stage 5: islands.** The orchestrator proposes a decomposition and the researcher approves it. Two islands run opposing bets on their own branches. Librarians write digests that preserve disagreement. The orchestrator shifts budget and may conclude a bounded campaign. The dashboard gains steering and intervention, the attention queue, and notifications. The reporter writes the account.
+
+**Stage 6: indefinite campaigns.** A direction criterion and a node envelope. Promotion by policy, reports on a cadence, re-decomposition when dry, ended only by a person.
+
+Recovery is built when a stage loses work, most likely stage three, when a service restart first interrupts many turns at once. It is not scheduled.
+
+**Known stage-one limitation.** The tool server is a stdio subprocess launched by the harness, so database credentials are in the harness's environment and a misbehaving agent could bypass the tool surface. With one trusted agent on a lab host this is accepted. Stage three closes it, when agents become mutually untrusted.
+
+## 7. Testing
+
+Every stage's scenario is exercised end to end, doing what a researcher would do and checking what a researcher would check: the record, the runs, the pull request. Unit tests cover intricate logic, not coverage.
+
+**Fixtures.**
+
+- A toy research project: a small model that trains in seconds on CPU, a real metric, and a configuration knob that is an obvious improvement. Campaigns in tests run against it.
+- The scripted substrate: an agent whose behavior is a deterministic script, issuing real tool calls to the real tool server.
+- A test repository on GitHub for publication.
+
+**Tiers.**
+
+1. Fast end-to-end on every change, with fakes at the Slurm and GitHub boundaries and the scripted substrate. The real record, tool server, workspace, and scheduler.
+2. Real-infrastructure end-to-end on demand, against the local Slinky cluster and the test repository, still with the scripted substrate.
+3. Live acceptance by hand at the close of each stage, with a real model on the harness substrate.
+
+The architecture is demonstrated when stage one's scenario passes all three tiers.
+
+## 8. Deferred
+
+Ideas that have arrived before their stage. Adding a line here is how an impulse to build is discharged. Nothing on this list is built until its stage begins or the encountered problem it names occurs.
+
+| Item | Picked up |
+|---|---|
+| Native tool-calling substrate | When a role's harness overhead or a subscription's limits are observed to be a problem |
+| Campaign-wide default harness and model with per-role overrides | When the role count makes per-role listing tedious |
+| A critic that asks the researchers directly; today the implementer is the only role that talks to humans | When a critic's block cannot express what it needs |
+| Several critics with different framings per candidate finding | When one critic's acceptance proves a rubber stamp, expected by stage 4 |
+| Integrator role; run admission with per-campaign slots | Stage 3 |
+| Budget ledger for tokens, GPU-hours, and cost; a budget query tool | Stage 3 |
+| HTTP tool server with per-turn tokens | Stage 3 |
+| Read-only web API and dashboard; AG-UI as the streaming format, decided in that design | Stage 3 |
+| Control-arm configuration and reporting | Stage 3 |
+| Read and search tools; per-role context filtering | When a campaign's record no longer fits in a turn's context, expected at stage 3 |
+| Decision kind; screened and admitted states; coordinator role; risk posture | Stage 4 |
+| Replication policy | Stage 4 |
+| Proximity role; knowledge module; cross-campaign memory; full-text search | Stage 4 |
+| Island entity and island column on entries; digest kind; librarian, orchestrator, and reporter roles | Stage 5 |
+| Addressing an entry to an agent's inbox | Stage 5 |
+| Campaign feed and human-visibility flag; attention queue; notifications; dashboard interventions | Stage 5 |
+| Conclude as an orchestrator decision | Stage 5 |
+| Promotion policy; footprint budgets; cadence reporting; pre-authorized posture changes | Stage 6 |
+| Recovery and reconciliation; durable-execution libraries evaluated then | When a stage loses work |
+| Role registry and prompt versioning | When a second campaign must be reproducible under changed prompts |
+| Artifact fetch tool | When an agent needs an artifact not on the host |
+| Provider rate limiting | When a provider limit is hit |
+| Remote executors; a second host; worker processes; a message broker | When one host saturates |
+| Embedding index | When full-text search proves insufficient for proximity |
+| OpenTelemetry GenAI span names | When tracing is added |
+| A2A-compatible task states | If an external agent ever needs a bridge |
+| Artifact retention and garbage collection; W&B synchronization | When storage fills or a project asks |
+| Cost estimate on proposals | Stage 4 |
+| Harness environment scrubbed of git and cluster credentials | Stage 3, with per-turn credentials |
+| Observation of pull request state | When something reads it |
+| Timeout for runs in unknown | When one is encountered |
+| Projects registry in the repository | Not planned; the configuration directory serves |
+| Metric formatting in the pull request body and `campaign show` (dict text today); Limitations line joins the Commits line | Stage 3, with the web view |
+| Turn duration is quantized to the tick interval (end time stamped at reap) | When anyone needs finer timing |
+| Per-project container image override (cluster-level image today) | When a project needs its own image |
+| A stage-one campaign that runs out of submissions has no explicit end; the agent asks and a human stops it | Stage 5, with decisions |
+| Session resume for harness substrates | Not planned; fresh turns are the design |
+| Frozen retrieval corpus | Not planned |
+| A critic launched with no candidate finding (a same-turn withdrawal, or two candidates at once) | When a harness implementer produces it |
+| Finding state when the campaign stops | When a stopped campaign's pull request misleads a reader |
+
+## References
+
+- Erman, Hayes-Roth, Lesser, and Reddy. "The Hearsay-II Speech-Understanding System." *Computing Surveys* 12(2), 1980.
+- B. Hayes-Roth. "A Blackboard Architecture for Control." *Artificial Intelligence* 26, 1985.
+- Nii. "Blackboard Systems," parts one and two. *AI Magazine* 7, 1986.
+- "Governed Shared Memory." arXiv 2606.24535, June 2026.
+- "Governance Gaps." arXiv 2606.31498, June 2026.
+- Model Context Protocol specification, 2026-07-28. https://modelcontextprotocol.io/specification/2026-07-28