{ "label": "Coordination Surface", "summary": "A package that lets several LLM agents work in one codebase at once: a board where each agent keeps one record, venues that hold a decision open until every agent taking part has signed it, and a pipeline of checks that enforces the package's own coordination rules.", "maturity": "experimental", "entries": [], "selfGoverned": {"checker": "govern", "paths": "config/surface.config.ts", "tests": "test"}, "domains": [ {"meta": "ai", "sub": "agents-orchestration"}, {"meta": "developer-tooling", "sub": "linting-quality"} ], "ecosystem": "typescript", "visibility": {"private": true, "hidden": false}, "repoMetrics": true, "capabilities": [ "multi-agent-coordination-board", "fenced-record-and-item-addressing", "permanent-seat-identity-allocation", "role-declaration-per-concern", "blocking-venue-convergence-and-archival", "history-accumulation-before-removal", "self-registering-governance-pipeline", "placement-and-naming-taxonomy", "slot-based-host-adaptation", "projection-channel-for-bounded-invocations" ], "governedBy": [ "rule-as-code", "central-config", "single-owner", "explicit-retention", "enforced-feedback", "regex-usage" ], "governance": {"principles": [ "single-source-of-truth", "separation-of-concerns", "open-closed", "fail-fast" ]}, "docs": { "overview": "Coordination Surface is a package that lets several LLM agents work in one codebase at the same time without overwriting each other's work. It contains the shared files the agents write to, a template for each of them, and a TypeScript toolchain that checks those files on every run. Each agent works under a letter, such as A or B, which the package calls its seat. The shared files are:\n\n- the board (`collab.comms.active`), where each agent keeps one record and posts items addressed to other agents;\n- the agent index (`_agent-index.md`), which binds each letter to a role;\n- venues, files in which the agents argue one decision until every agent taking part has signed it, after which the venue moves to the archive folder;\n- the history file (`_changelogs.txt`), where the lasting part of anything removed from the other files is written first;\n- folders for role documents, planning checklists, models and findings.\n\nThe agents write to these files through one command, which writes only inside the calling agent's record, then waits for the next write by another agent and shows what changed. The checks run as one pipeline, and each rule is a file in `tools/rules`, so a rule is added or removed without editing the pipeline. Every fact about the host project is a setting in `config/surface.config.ts`. An install sets the project root, and adoption renames the `.{provider}` folder to the name the agent runtime reads, as `BOOTSTRAP.md` describes.", "whenToUse": [ "Several agents work in one codebase at once, and two of them may edit the same file. Each agent writes only inside its own record, and the write command reads the file again just before writing and refuses when it changed in between.", "The agents need to reach a decision together before the work goes on. A venue holds the decision open until every agent taking part has stated its needs and signed, and the checks report the venue as blocking until then.", "The coordination files grow faster than the agents clear them. The board holds only what is current: the agent that handled an item removes it after writing its lasting part to the history file, and a check fails the board when a record grows past what one read holds.", "You want each coordination rule backed by a check. Each rule in `AGENTS.md` names the check that enforces it, or states that no check can observe it, and a coverage check fails a rule that does neither." ], "whenNotToUse": [ "One agent works on the codebase alone. The records and the wait protect agents from each other, so with one agent they add steps and protect nothing. A single-agent project sets `project.coordination_board` to absent.", "You need a task tracker. A planning checklist lists only the work that remains, and a finished task is deleted rather than marked done, so the package keeps no record of completed work outside the history file.", "You need your own code linted or type-checked. The checks read the coordination files, the rules and the package's own tools. A project connects its own quality toolchain through `execution.quality_command`, so one pipeline runs both." ], "install": "1. Copy this folder into your project. The folder name does not matter.\n2. In `config/surface.config.ts`, set `project.root` to the path of your project root, relative to this folder. The default, `..`, fits a folder placed directly in the project root.\n3. Choose how you take part, with `convention.operator_mode`:\n - `overseer`, the default: the agents do not stop to ask you. You write an entry anywhere in a venue, in any form, and each agent receives it with the changes its next wait shows. The agents address you only when they cannot go on.\n - `interactive`: the agents bring each decision to you and wait for your answer.\n4. The package keeps its rules, skills and agent files in one folder named `.{provider}`, which each agent runtime expects under its own name, such as `.claude` or `.codex`. Ask your agent to follow `BOOTSTRAP.md`: the agent is asked to rename that folder, point the configuration at it, and load `AGENTS.md` into its instructions.\n5. Run `npm install`, then run `npm run govern` until two runs in a row report the same result; that result is the verdict. The first run repairs what it can, such as the generated binding, and each check that reads the previous run's report needs one more run to see the repair.\n6. Set any further setting your project has, such as a history file or a quality command. A setting left absent turns off the check that depends on it, and the report says so.", "quickStart": [ {"intent": "Run every check once, with repairs on", "lang": "bash", "code": "npm run govern"}, { "intent": "Wait for the next write by another agent, then see what changed", "lang": "bash", "code": "npm run await -- --agent A" }, { "intent": "Post a position to a venue, with the text read from a file", "lang": "bash", "code": "npm run await -- --agent A --file --item-file position.md --kind judgement" }, { "intent": "Check a venue, and move it to the archive when every check holds", "lang": "bash", "code": "npm run converge -- --agent A --file " }, {"intent": "List every flag of the write command", "lang": "bash", "code": "npm run await -- --help"} ], "api": "The package is used through commands rather than imports:\n\n- `npm run govern` runs every check over the package and writes each report under `_generated`. `--rule`, `--stage` and `--scope` narrow a run, and `--agent ` names who ran it.\n- `npm run await` writes to a coordination file and then waits for the next write by another agent. It needs `--agent `, and `--help` lists its flags.\n- `npm run converge` checks a venue and moves it to the archive once every check holds.\n- `npm run gates` checks that each rule reports a planted violation and accepts a clean sample.\n- `npm run typecheck` compiles the tools.\n- `npm run documents` runs the project's own document generators, if `execution.document_generators` names any.\n- `npm run clean`, `npm run corpus` and `npm run govern:segment` maintain source comments, document names and references.", "configuration": [ { "option": "_manifest.json", "note": "The package's name, summary and license, and the text of this README." }, { "option": "config/surface.config.ts", "note": "Every setting that describes the host project. Each setting is resolved, absent or deferred: an absent setting turns off the check that depends on it, and a deferred one blocks that check until the setting is given." }, { "option": "project.root", "default": "..", "note": "The path from this folder to the project root, which every install sets." }, { "option": "convention.operator_mode", "default": "overseer", "note": "How the developer takes part: `overseer` or `interactive`, as described under Install." }, { "option": "project.coordination_board", "default": "collab.comms.active", "note": "The board's file name, or absent for a project with one agent." }, { "option": "project.governance_policy", "note": "The project's own instructions file, where the package keeps one status line. Absent by default, so the package writes nothing outside its folder." }, { "option": "execution.quality_command and execution.quality_concerns", "note": "The project's own quality toolchain and which of its checks the pipeline runs, so one command runs both." }, { "option": "convention.secret_shapes", "default": "[]", "note": "The credential prefixes the secret check looks for, each with its shortest length, such as `sk_live_:24`." }, { "option": "convention.read_token_budget and convention.chars_per_token", "note": "How much one agent reads at once, which the check on record size is measured against." }, { "option": "config/taxonomy.config.ts", "note": "The names the package allows for folders and files: containers, concerns, subjects and variants." }, { "option": "config/agenda.config.ts", "note": "The planned order of venues. It is empty in a new install." } ], "aiContext": [ "Read the board whole on every turn. It holds items addressed to you by letter, and a partial read can miss one.", "Claim a letter with `--index \"\"` before your first write anywhere else, and write your role document with `--role` before your first edit.", "Write through `npm run await`. It writes only inside your own record, and it shows items that other agents posted since your last read.", "When you are waiting on another agent, run the wait instead of ending the turn. A wait that returns QUIET means no other agent wrote; carry on with your own work and wait again.", "Post findings to the other agents, on the board or in a venue. In overseer mode, address the developer only when the agents cannot go on; in interactive mode, bring each decision to the developer and wait for the answer.", "Write the lasting part of an item to the history file before the item is removed. The agent that handled an item removes it, and its author does not.", "An open venue blocks the build until it converges, so its failing check is expected." ], "disposal": [ "To stand a board down, remove things in the reverse of the order they were created: each agent removes its own role document and record, and the agent index goes last. In that order, every check still passes after each step.", "To remove the package, delete this folder. With `project.governance_policy` absent, the package has written nothing outside its folder; otherwise, also remove its status line from that file." ], "license": "Pattern Abstract Grammar (PAG) was created by Jay Baleine (Bane's Lab). It is free for non-commercial use and needs a paid license for commercial use. The license terms: https://banes-lab.com/licensing", "graph": [ "A **node** is a record that carries an `id`, a `subject` and edges.", "An **edge** is a citation, meaning an id written in a field. `blocks`, `answers`, `refutes`, `supersedes` and `satisfied-by` are one construct, resolved by one check, rather than five relations.", "**A record's open, blocked and absorbed states are derived by traversal.** A record is open while one of its outbound edges is unresolved, blocked while an unresolved node points to it, and absorbed once every edge is resolved.", "**An agent's ACTIVE or INACTIVE state is read from the agent index.** The marker on its board record is compared against the index, and where the two differ, the index is used.", "The graph check reports a cycle, an orphan and a citation that resolves to nothing as findings." ], "identity": [ "An item id is `-`, made of the writing agent's letter and an ordinal that the write command allocates. An id is allocated once and never reused. A subject is a declared subject key, derived again on every run and compared against its declaration.", "**The write command allocates the ordinal, not the agent.** Each record has one writer, so the ordinal needs no registry and no coordination step.", "**Two nodes that carry one subject key are reported as a finding rather than treated as a collision**, and the re-derivation check makes that decision.", "**An agent letter is bound to a role permanently and is never reused.** For this reason the index accumulates rows rather than living as a board section. The board deletes a resolved item, but a letter that is inactive still has to resolve, because every citation that ever named it points there. A new agent is indexed before its first write, and a letter is claimed by adding its row, not by using it.", "A role is declared within a surface, and letters recur at every depth as local addresses. The agent index is the one place where a letter is a lasting project identity. The two never mix, because a local letter is scoped to a surface and an indexed letter to the project." ], "surfaces": [ {"surface": "board", "holds": "each seat's Owns, Status, Flags and Refs", "lifetime": "current truth"}, { "surface": "venue", "holds": "positions, deferrals, directives and sign-offs for one decision", "lifetime": "until it converges, then archived whole" }, {"surface": "planning surfaces", "holds": "plan rows", "lifetime": "until the row retires"}, { "surface": "models and findings", "holds": "what a construct is, and what was measured about it", "lifetime": "current truth" }, {"surface": "the history file", "holds": "project history", "lifetime": "append"}, { "surface": "`_agenda.md`", "holds": "every planned invariant, what it must establish, and its state", "lifetime": "accumulating; a planned invariant is not deleted when a different one is raised ahead of it" } ], "surface-rules": [ "**Each surface names a role, and the configuration resolves the role to a path.** A surface named by its location would be a second declaration, competing with the one the checks read.", "**A surface declares its scope, and the checks report an overlap as a finding.** Scope is claimed by concern, not by location. When two agents claim directories, they can end up writing one folder from two claims that never mention each other.", "**Blocked has a different meaning on each of two surfaces.** A document record carries an `Edges` field, so its blocked state is derived by traversal. An agent record on the board carries no edges, so it has no blocked field, and who is waiting on whom is carried by how an item is addressed.", "`Refs` records that a new surface has arrived, meaning that it exists, not what it contains.", "**A planning surface moves only in the same change as the checklist check's root binding.** A surface in a directory that no check reads is not governed, wherever it sits.", "Converting an item from one surface to another is a move, never a copy.", "A finding can be checked against the codebase as it stands, but a plan row cannot be checked until something is built.", "The `_` prefix marks an accumulator, a file that only grows. Every other file holds only what is currently true, and the tense rules apply to it.", "**A root folder holds its entry document and its accumulators, and everything else lives in a concern folder.** The placement check matches the construct, meaning the `_` marker and the entry-document role, rather than either file name.", "**An accumulator is named for its function.** A file called notes invites an agent to annotate, reorder and append freely. A file that the tooling reads by position allows none of those, so its name says what the tooling does with it.", "**No summary line stands over a list.** A count, a total or a sentence saying that everything is placed, set beside a list, is a derived fact kept by hand. It disagrees with the list as soon as the list changes, and nothing reports the difference." ], "item-kinds": [ {"kind": "round", "home": "a venue", "closes when": "its acknowledger closes it"}, {"kind": "claim", "home": "a checklist row", "closes when": "the row retires"}, {"kind": "finding", "home": "the findings folder", "closes when": "it stays and is referenced"}, { "kind": "ruling", "home": "the surface owning the axis it binds", "closes when": "it stays and is cited by id" }, {"kind": "repair", "home": "the tree it fixes", "closes when": "the change is on disk"} ], "item-rules": [ "**An item's destination follows from its kind.** It is derived, not chosen.", "**No item is raised without a destination**, so deleting an item loses nothing.", "**A ruling has no register of its own.** The axis a ruling binds selects its surface, so the destination stays derived. A general register would give rulings a second home.", "A repair states the defect, the construct and the change, and it is addressed to the owner rather than asked as a question. Repairs exist because two rules meet on every defect an agent finds in a part of the codebase it does not own: fix a defect on sight, and leave another agent's scope untouched.", "**Friction in coordination points to a missing mechanism, not to a need for more care.** When coordination goes wrong, the first question is what the surface is missing. A coordination surface is software: it has state, invariants and a schema, and without a validator it decays. An accumulating file, a lost write, a stale item or a missed message is therefore a defect in this protocol, and the repair is a mechanism that makes the failure impossible or visible.", "**Before reporting an absence, an agent is asked to run the measurement again one scope wider.** If the answer changes, the first result described the query rather than the codebase. A negative result carries the scope of its query, and a claim that something does not exist leads to deleting, building or re-planning.", "**A matched token is cited by naming the rule that matches it, not by quoting the token.** A report that quotes a marker carries the marker itself, so the finding moves from the reported record to the report.", "**A detector matches every surface that contains its construct, including a surface that describes or tests it.** A report quoting a marker, a document explaining a forbidden shape and a fixture holding the construct its check catches are one class. Excluding such a surface by path creates a blind spot, while teaching the scanner to tell a use from a mention makes the check stronger." ], "closing": [ "An item satisfied by an **artifact** closes by derivation, when its citation resolves.", "**`Satisfied-by` names a condition that can be false, never a path.** A file path resolves as soon as the file exists, so the item would read as closed while the defect is still open. The citation points at something whose state can be wrong.", "**The condition also tracks the work: it is true when the work is done and false when it is not.** A citation that points at the findings themselves is satisfied by a broken codebase and becomes false once the findings are repaired.", "An item satisfied by a **judgement** is closed by its declared acknowledger and carries no reference, because there is nothing for one to point at. If the acknowledger is not ACTIVE, the item cannot close, so it is re-addressed rather than left.", "**That binding is checked.** The declared set is derived from the ACTIVE seats, so when a seat goes inactive, the check follows the new set on the next run with no file to edit. Leaving a binding unclaimed is allowed, but binding it to an absent agent is not, because that row can be built but never retired.", "**Absorbing an item is a transition, not a state.** Its lasting part is written to the history file, and the item is deleted in the same change, so history has one home.", "An item left unacknowledged past the declared stall limit is reported as a finding and escalated to the board." ], "item-shape": "An item addressed from one agent to another is a **fenced span with an allocated id**, not a sentence in a field.\n\n```text EXAMPLE: an item\n┌─── AGENT - · ───\nTo [, ][ AND ] — the argument, across as many lines as it needs.\n└─── END AGENT -\n```", "board-items": [ "**The kind selects how an item closes, and it sits on the opening marker.** An artifact item asks for something that can exist and closes with a typed reference that resolves. A judgement item asks for a reading and is closed by its acknowledger, with no reference.", "**The id and the fence work as one mechanism.** The id makes a fence addressable, and the fence makes the id's span removable. A span resolves only when exactly one opening and one closing marker carry its key, so at item level the key cannot be the agent letter, because one agent writes many items.", "**The field opens with an em dash, and the fences follow it.** A marker that shares the field's label line is not recognized, so the item reads as an opening with no close.", "**A fenced item may span as many lines as its argument needs.**", "**The check on well-formed fences is required.** A single unclosed marker makes its item impossible for the tool to remove.", "**Removal takes the whole span, never a matched line.** Removing an item by matching its text leaves its markers behind, and an orphaned fence is a span that no later operation can interpret.", "**An item is extracted before it is removed.** A removal names a typed reference that resolves. The check decides whether the extract is present, not whether it is faithful, because the faithfulness of a summary is a judgement.", "**The agent that handled an item removes it, never its author.** Handling and removing are one operation by one agent, so a handled item never waits for its author to notice it.", "**The one-writer-per-record rule applies to hand editing, not to the tool.** A tool that removes exactly one addressable span by id, after re-reading the file and with a compare-and-swap, is the mechanism the fence and the id were built for.", "**Removal depends on who an item was addressed to, not on who wrote it**, so an agent clears only traffic addressed to it, and an item's removal shows that its reader acted on it." ], "citation-forms-on-a-planning-surface": [ { "the citation is": "a live dependency", "then": "**the row is not closed.** The dependent is what keeps it open, so deleting it was premature" }, { "the citation is": "provenance", "then": "it is history sitting on a checklist, and the rule of one history home sends it to the history file" } ], "retiring-a-built-row": [ "**A built row is deleted, and only after the rows that cite it are.** A planning surface holds only current and future work, so a row kept with a done marker does not belong there.", "**A citation is either a live dependency or provenance, and only a live dependency belongs on a planning surface.**", "**A provenance citation is rewritten to name the mechanism rather than the row id.** A row is a unit of work and a mechanism is a lasting fact, so a citation that outlives its row is citing the mechanism.", "This has a cost: a mechanism name resolves against nothing, so the check cannot follow that reference.", "**What the check can hold is the deletion order, and it reports at the citing row.** A dangling citation is reported where it is read rather than where it was created." ], "the-seats-own-declaration": [ "A letter carries a role document at `roles/..role.md`, raised from `templates/role.template.md` with `--role`. The agent is asked to write it before its first write and to read it before its first edit.", "**The concern is the file's subject and the letter takes the variant slot**, because a seat changes hands and a concern does not. The letter resolves from the index that allocates it, so a new seat needs no vocabulary change.", "**A resuming session recovers its scope from this document.** Without it, a seat tends to infer its scope from whatever is being edited, and the board states what a seat owns but nothing about how it works or what it refuses.", "**The document names the seat's failure modes.** The sections that change behavior are the ones naming what this seat gets wrong.", "**The role check fails an active letter that has no document, and any document that is missing a section.**", "**A vacated seat keeps its document.** The concern outlives the seat, so the next agent to claim the concern is asked to read the document before its first edit.", "**A handover changes one field, `letter:`.** A letter is never reused, so the incoming seat takes a new one from the index and writes it there. Every other section describes the concern and is inherited unchanged.", "**The file name stays as it is.** The variant slot records which seat first held the concern, while the field is what the tooling reads and what a handover updates.", "**A concern may be held by a seat that owns another**, and in that case the document says so and states the cost." ], "the-projection": [ "The projection is **one line, overwritten and never appended to**. It carries the open blocker, who owns what, and a pointer to the board. It lives in the host project's instructions file under the marker the configuration declares, and it exists only when `project.governance_policy` is resolved.", "**It is the only channel to the board that a spawned agent has.** The host's standing instructions are injected into a spawned agent and the board is not, so for every bounded invocation that line stands in for the board.", "**A stale projection gives a spawned agent outdated information as its only information.** Raising or deleting a blocker therefore refreshes the projection in the same change.", "**A field named a one-liner claims something about its size.** Where a name states a shape, a check reads it." ], "scale": [ "A surface **reduces before it writes upward**: a parent publishes the combined result of its children, never their raw records.", "**The read-whole rule applies to the surface an agent owns and to its inbox**, both of which are bounded by construction. The global view is derived rather than read.", "Branching repeats at every level, from workers to an orchestrator, to a higher orchestrator, to a composer. Every level is a surface with one writer, so identity and reduction hold unchanged at any depth.", "The reduction step is declared but not built, and it has not been measured at any number of agents." ], "placement-and-enforcement": [ "A document declares its **type**, and the type selects its schema, where it may be placed and which rules apply to it.", "**Every field in a record schema declares its shape, and PAG's reasoning loop is not applied to a surface that is only read.** Declaring a field before use, and declaring a shape for each decision, carry over from PAG, but the loop itself belongs to an artifact that is executed. A typed field with no validator is not enforced.", "**The adapter indirection carries over before the typing does.** A coordination document that names a concrete path cannot move to another project, so paths resolve through settings.", "**What stays loaded is decided by precedence, not by how often a rule fires.** A rule that must apply before the domain is known stays loaded. A rule that assumes a known domain is referenced, and it loads when the work enters that domain.", "Placement reuses the concern grammar in `config/taxonomy.config.ts`, and admitting a new kind of document takes three edits to that one file: declare the container, add the kind to the closed concern list, and create the folders in the same change.", "**No index is written by hand.** The index is generated on every run and checked in both directions, for an entry with no file and for a file with no entry.", "Rules register in `tools/rules` and run through the single entry point.", "**Every scan covers every depth**, because a scan that stops short reports a pass over what it cannot see.", "A venue and its outcome are two files: the venue moves to the archive, and the outcome remains in the protocol." ], "blocking": [ "An open venue holds the build until it converges.", "It states its own **exit condition**, because without one it would halt the work indefinitely.", "**Its failing check is the intended state, not a defect to repair.**", "Every seat taking part marks it read, the discussion converges, and the outcome is written.", "**Every clause of the outcome cites the position it came from, and a clause without a citation is not agreed.** An agent other than the drafter runs the audit, because the failure it catches is the drafter's own preferences entering as consensus.", "**Before the venue is archived, each participant checks its own records against the outcome and adds what is missing.**" ], "concurrent-writes": [ "**The target is read immediately before it is written.** A path not read in the current turn has unknown contents, whatever the intent, and creating or renaming a file is a write to its destination.", "**Exclusive access is enforced by a barrier, not left to discipline**, and the barrier reports HELD only when the parked agents number one fewer than the active ones.", "Any tool written for this package that rewrites a whole file it does not own exclusively uses a compare-and-swap. **A tool that rewrites a whole file and reports its own success is the one writer that no later check can catch.**", "**The barrier and the compare-and-swap complement each other**: the barrier covers the parked agents, and the compare-and-swap covers the busy one." ], "schemas": "```text EXAMPLE: an agent record\nAgent X — ACTIVE | INACTIVE | INVOKED\n Owns: \n Status: \n Refs: \n```\n\n```text EXAMPLE: a document record\nItem - — \n Subject: \n Kind: round | claim | finding | ruling | repair\n Acknowledger: \n Satisfied-by: \n Evidence: \n Edges: \n```\n\n```text EXAMPLE: a surface header\nType: \nOwner: \nKey: \nParent: \n```\n\nThese are the shapes the templates instantiate. `Edges` carries the graph the traversal reads and `Parent` carries the reduction tree.", "what-transfers": [ "A template carries **the schema, the lifetime, the failure mode and the check**, never the schema alone, because a rule that is stated but cannot be checked makes the surface look governed when it is not.", "**The bootstrap document is the catalog of failures rather than the protocol**, because a rule given without its reason tends to be argued again.", "**A template ships classes, never instances.** The catalog carries shapes of failure, such as a mechanism with no effect, a passing result over a set that excluded its own subject, a hand-kept index drifting, a search used in place of a graph, and a finding with no destination, but never which file or which agent." ], "agents": [ "**Route work by where its input lives.** An input the codebase already holds calls for a rule extension or a pipeline stage, however well an agent would do it. Only an input that exists in no file calls for an agent, such as a claim that was true when written and may be false when read.", "**An agent run is a surface, and the agent's definition generates surfaces.** A run has one writer, a `Parent` that invoked it, records with edges, and a terminal state that is derived.", "**A run's `Key` is not allocated, and the package says so rather than inventing one.** No run-scoped surface exists on disk and no id namespace is declared for one, so until an allocator exists a run has no id that can be cited.", "**A run publishes its trust anchor, the escalations it declined and its audit trail, or it states that its reasoning cannot be recovered.** Reduction discards the individual nodes, so without a trail a wrong artifact cannot be traced back to the node that produced it.", "**The definition lives with the agent's behavior, and its output lives with the coordination files.** The surface's `Owner` field names the agent, which links the two.", "**A run reduces before it writes upward.** It emits one typed artifact and never its raw node outputs, and the artifact becomes an item with a `Subject` and a `Satisfied-by` that can be false.", "**Routing depends on the input, never on the expected answer.** A set of claims can be given to a run when the claims can be listed and each one names the observation that would settle it, which can be decided before the run.", "**`unverified` is a verdict with a destination, not a silent gap.** A run returns verified, contradicted or unverified, and an unverified claim becomes a finding with an acknowledger.", "**An agent is not a pipeline stage.** The pipeline checks that the agent was invoked before the decision it guards, and the agent does the verifying.", "**There are two decision points, and they answer different questions.** A phase-boundary check asks whether a phase's work is sound before the next phase builds on it. A retirement check asks whether a row's claim is still true before the row is deleted.", "**Neither one covers the other**: a phase can close without retiring any row, and a row can retire in the middle of a phase. Removing an item and acting on another agent's findings both consume claims, so both go through the retirement check.", "**A claim is checked against the codebase when it is written and again when it is read**, with the item's `Subject` and `Satisfied-by` as the set of claims.", "**A repair for a part of the codebase its finder does not own is produced in an analysis-only phase**, where the allowed operations exclude changes, and only the owner of that part acts on it.", "**A row whose evidence can be checked against the codebase can be closed by a run. A row that needs a running system cannot, and it goes to the owner.**" ], "what-ships": [ "**The package ships the templates and none of a deployment's records.** It carries the board template, the role template, the allocation scheme with its own invoked capabilities, empty roles, findings, checklists and specifications folders, and both accumulators with nothing accumulated. A board holding records, an index binding seat letters, and a role document per seat belong to a deployment.", "**The board is its template, copied**, so its shape can be checked from the start. The checks derive their record schema from the template, and a new board conforms by construction.", "**An install sets where the host project's root sits, and adoption renames the `.{provider}` folder.** Everything else about the host is declared as it is discovered, and whatever the host does not have is declared absent." ] } }