Pipebrain — V1 Requirements

Status: Published reference · August 2026 · Revision 15 — corrections: §6’s trust model names the manual criteria as the whole human gate on finishing (it had counted the done transition too, contradicting the same paragraph’s opening — the completion guard takes no actor at all), and §6 rule 2 no longer says what remains after → verify is human judgment. Rev 14 (§15 records the decisions module as built — it had shipped while that entry still said deferred, contradicting §7’s own tool table; §7’s opening names the hosted streamable-HTTP endpoint beside stdio; and §12 records the live custom domain). Rev 13 (acceptance criteria widened from epics to work of any kind: an epic, a task and a bug each carry them, with the same AC-{n} identity and the same gates — §4 criteria, §6 rules 2–3, §7 set_criteria). Rev 12 (deployment topology removed from this public page: cluster, pool, port and role identities are operational facts that belong in the deploy specification and the team’s internal cluster note, and restating them here published a second copy that could quietly disagree with the first). Rev 11 (acceptance suites and run history removed — acceptance criteria are the only gate; §6 renumbered). Purpose: The published interface reference for Pipebrain — what an agent, an integrator, or a reader outside the team needs in order to use the product: the MCP tool surface (§7), the HTTP API (§9), and the embeddable feedback widget (§10). The governing requirements are versioned documents in the Pipebrain tracker itself (the PIPE-R… series), and they are what an epic links to; where a tracker document and this page disagree, the tracker document is the one that governs. Companion: WORKFLOW.md defines the delivery workflow Pipebrain exists to support. Entity names, status values, and MCP tool names must match between the two documents exactly.

1. What Pipebrain is

Pipebrain is the system of record for product work — requirements, epics, tasks, bugs, acceptance criteria, and user feedback — for a small team whose builders are agents. V1 is operated by two humans and their AI agents.

Pipebrain is a ledger, not an orchestrator. It records intent, holds claimable work, and receives reports. It never spawns, schedules, or drives agents. Agents (Claude Code sessions) do the thinking inside product repositories and report state changes through the Pipebrain MCP server. Humans gate the workflow at defined points.

V1 shipped two modules — issues (work tracking, with per-issue acceptance criteria) and requirements (versioned, living requirement documents); the platform has since grown content & assets, secrets, and org-instructions modules (§4, §7). Module boundaries in code reflect that Pipebrain is the platform and these are feature areas.

The problem the UI must solve

Today, working a feature means switching between a roadmap file (status), an epic index (structure), a feature file (acceptance checkboxes), and a requirements document (context) — and “checking off” a criterion means editing markdown. Pipebrain replaces that with the feature epic’s page: feature → slices → criteria, with status changes and criterion check-offs in place, and requirement context readable without navigating away. This is the design center of §8. The project overview and activity log are derived views that replace the hand-maintained roadmap and runlog files entirely.

Product principles

1. Simplicity first. Two users. Build the basics needed to organize, view, and filter work. No dashboards, no charts, no drag-and-drop, no configurable workflows.
2. Markdown is first-class. Requirement bodies, issue bodies, and comments are markdown, with quality editing and rendering everywhere.
3. Agent-native by design. The MCP server is a primary interface, not an afterthought. Web and MCP consume the same API.
4. Own the data, minimize vendors. DigitalOcean + Postgres only. No new third-party services.
5. Cost discipline. Marginal infrastructure cost ≈ $0 (shared database cluster) plus the smallest App Platform tiers.

2. Technical stack (locked — do not substitute)

*The V1 exclusion of WebSockets is revisited by the chat slice (§15, PIPE-11), which introduces @fastify/websocket + Postgres LISTEN/NOTIFY for one org-scoped stream.

Suggested workspace layout: apps/api, apps/web, apps/mcp, libs/domain (Zod schemas + types — single source of truth), libs/db (queries), libs/api-client, db/migrations (dbmate, repo root), libs/widget (builds the single widget.js artifact).

3. Users, auth, and attribution

• Seeded operators + invite-gated membership. V1 launched with exactly two operators created by a seed script (names/emails/initial passwords from local gitignored config); that path remains the bootstrap. There is still no open signup — account creation is gated by an org invitation (see §4 org_invitations): an ADMIN/OWNER invites by email as ADMIN or CONTRIBUTOR, and /invite/<token> is the only door to signup (the by-token preview renders logged out and drives the new-user branch). Invitation email is delivered via SES.
• Self-serve account recovery (post-V1): password reset (/forgot-password → password_reset_tokens) and email change with token confirmation (email_change_tokens, /verify-email/<token>). The V1 “reset = operator runs a script” rule is retired.
• Web: Better Auth email/password; httpOnly, SameSite=Lax session cookies.
• API tokens: minted in the web UI (Settings), stored hashed (SHA-256), plaintext shown exactly once, owned by an operator, labeled (e.g. ci-agent), revocable, last_used_at tracked. Token format: pbt_ + 32 bytes of cryptographically random base62 (~43 chars); unsalted SHA-256 is acceptable at this entropy. ONE prefix is accepted, by everything that judges a token by its shape — the product’s own checks, the clients it ships, and outside scanners. Recognition itself never reads it: the server resolves a presented token by the hash of the whole string, so the accepted spelling binds shape checks alone. Columns are spelled in §4 (api_tokens).
• Every write records actor_user_id and actor_token_id (null for web sessions). This distinguishes “an operator in the browser” from “their agent over MCP” in comments, revisions, criteria check-offs, and the audit trail. It is also the enforcement basis for human-only actions (§4 criteria).
• Widget submissions are unauthenticated (public per-project key) — see §10.

4. Domain model

Multi-organization deployment (shipped additively after V1 — PIPE-R8; no rename below the data model, which was only possible because the org anchor was real from the first migration). The organization is a real root entity and the RLS scope anchor (see §11). All tenant tables carry org_id NOT NULL.

Display-ID numbering uses per-project counters keyed by kind (issue, requirement), each updated atomically inside the insert transaction. Gaps acceptable; duplicates never.

organizations — the root entity

id (uuid), name, slug (unique), kind (shared | personal), created_by, created_at, updated_at, deleted_at. Every tenant table’s org_id references organizations(id). RLS is enabled and forced on it, self-scoped (id = current_setting('app.org_id')::uuid); it carries no org_id of its own — it is the scope anchor. V1 ran single-org (with a second org seeded for the RLS isolation tests, §13); multi-org shipped additively: shared orgs hold a team’s work, and each operator owns a personal org (slug derived from the email localpart). RLS enforces isolation across all orgs, shared and personal alike.

users — operators and invited members

The Better Auth user table, extended with default_org_id (nullable FK → organizations — the bare-login landing pointer, renamed from V1’s org_id NOT NULL; the truth about access lives in org_members, never in this pointer) and deleted_at. Its schema is generated once via the Better Auth CLI, translated to plain SQL, and hand-written into the dbmate migrations; Better Auth’s session/account/verification tables likewise live in migrations. All actor / created_by / claimed_by / approved_by / author_user_id / state_set_by FKs are uuid referencing users(id). The auth tables (user, session, account, verification) are org-independent infrastructure — not tenant tables: no org_id on session/account/verification, no forced RLS, read at cookie-validation time before app.org_id is set. Better Auth’s own migrator is never run in production.

org_members — membership is the truth

id, org_id, user_id, role (OWNER | ADMIN | CONTRIBUTOR), invited_by, created_at, updated_at, deleted_at; one live membership per (org_id, user_id) (partial unique index excluding soft-deleted rows, so a removed member can be re-added). A user belongs to any number of orgs and the web app selects the active one — access derives from a membership row, never from inference. Like users, this is auth-infrastructure zone: no RLS, read at request-binding time before app.org_id is set.

org_invitations — invite-gated signup

An ADMIN/OWNER invites by email as ADMIN or CONTRIBUTOR; the invite token gates account creation and, for a new user, the by-token new-user branch (§3). Managed in Settings (Organization tab → Members); email delivery via SES.

projects

name, key (2–5 uppercase letters, unique per org, used in display IDs), widget fields (§10), default_environment_id (FK → environments; seeded to the auto-created prod), timestamps, deleted_at. Creating a project automatically seeds two environments: dev and prod, and sets default_environment_id to prod.

environments

Per project: name, slug (unique per project), position. Operators can add, rename, and delete an environment — delete is allowed only when the environment has no issues.

milestones

Per project, operator-managed (§8 Settings): id, org_id, project_id, token (e.g. M1, unique per project), label (e.g. “production launch”), position (int), active (boolean; at most one active per project — enforced by a partial unique index), archived (boolean, default false — the release is finished and leaves the everyday pickers, WITHOUT being deleted: the row stays listed, keeps its token, label and position, and every issue carrying that token is untouched; a table CHECK refuses active and archived together, so archiving the active milestone and activating an archived one are both refused, each with its own error code), created_at, updated_at, deleted_at. issues.milestone stays free text and is a loose reference to milestones.token: an issue may carry a token with no matching milestones row (it groups by that token on the overview, without a label or active state). The Work page’s active-milestone summary joins the active milestone row for its token, label, and progress.

issues — the single work entity

One table for all work. type distinguishes kinds, parent_id builds hierarchy, and the workflow is carried by status plus convention (defined in WORKFLOW.md).

“Open” (defined once): an issue is open when its status is not in {done, killed}. This single definition drives the Work page’s attention preset, the open-issue counts (§7 list_projects, §8), and which issues the blocked surfaces report (§8). Blocked-ness itself is recorded state, never derived from an issue’s status or its comments: an active blocked mark (with its reason) or at least one unresolved blocking issue — and a blocker resolves exactly when it stops being open. open only scopes which blocked issues the queue and the attention preset surface.

criteria — itemized acceptance criteria (epics, tasks, bugs)

Individually checkable rows on a piece of work: its contract — and, split by verification mode, the machine-verified evidence trail plus the human verification checklist (WORKFLOW.md Stage 6). An epic, a task and a bug each carry criteria, because what a criterion answers is how anyone knows the thing is done, and that question does not get easier as the work gets smaller. feedback is the one kind refused (422 criteria_not_supported), and it is refused for what it is rather than for its size: a report of something noticed, not work anyone has agreed to do — promote_feedback retypes it into work first, and that is the moment its contract gets written.

Enforcement (server rule, not convention): a request authenticated by an API token may set state only on auto criteria. State on manual criteria can be set only from a web session. This is what keeps the human gate real — an agent can never check off human judgment.

issue_blocked_marks — the explicit blocked mark

org_id, issue_id, reason (required, human-readable), set_by, set_via_token_id (nullable), set_at, cleared_by, cleared_via_token_id, cleared_at (null while the mark stands), created_at, updated_at, deleted_at. At most one active mark per issue — a partial unique index on issue_id where cleared_at is null and deleted_at is null; writes serialize on the issue row. Clearing never deletes: cleared rows are the issue’s blockage history, so who blocked it, why, and who ended it stay readable. Re-marking an already-marked issue clears the standing row and inserts a new one, so attribution is never overwritten.

issue_relations — typed edges between issues

org_id, from_issue_id (the blocker), to_issue_id (the waiting issue), kind (a CHECK over blocks | depends_on | duplicates | relates_to), created_by, via_token_id (nullable), created_at, updated_at, deleted_at; from_issue_id <> to_issue_id, and one live edge per (from_issue_id, to_issue_id, kind) (partial unique). Only kind = 'blocks' is wired (§15): both issues must be in the same project, and an edge that would close a cycle — directly or through other issues — is rejected with nothing recorded, checked under a per-project advisory lock so two concurrent writes cannot compose one. An edge is unresolved while its blocker is open; a done or killed blocker resolves it without the row changing.

requirements — project-scoped living documents

A separate first-class entity — not an issue type. Requirements describe the product, so they carry no environment, no status board, no claiming. Display ID = {project.key}-R{number} (e.g. DWB-R4).

Title and body live in revisions; the “current” title/body is the latest revision. Lifecycle is derived, never stored: draft (no approval yet) · approved (approved revision = latest revision) · amended (revisions exist after the approved one).

requirement_revisions — append-only history

Every save appends a revision. No UPDATE or DELETE grants on this table for the runtime role — it is immutable history by construction.

requirement_approvals — approval history

org_id, requirement_id, revision_id, approved_by, created_at. Append-only (no UPDATE/DELETE grant). Approving also sets requirements.approved_revision_id.

issue_requirement_links

Connects epics to the requirements they implement, pinned to the revision that was approved at link time: org_id, issue_id, requirement_id, revision_id, created_by, created_at, deleted_at. revision_id is NOT NULL. Linking a requirement with no approved revision is rejected with an actionable error (approve it first — matches WORKFLOW.md Stage 3’s gate); the §5 rule-4 “latest if never approved” read fallback never applies to freezing a link.

Staleness is derived, never stored: a link whose revision_id is older than the requirement’s current approved_revision_id means the epic was sliced from a superseded version — the UI badges this (§8). Cross-cutting requirements are never linked and never pinned (§5 rule 6), so staleness applies only to explicit links.

content_drafts — project-scoped topic documents (Content & Assets module)

A first-class entity, a sibling of requirements — not an issue type. A draft is raw material (a topic to publish) that gets promoted into work; it carries no environment, no status board, no claiming, and deliberately no approval gate and no lifecycle (kept lightweight — revisions simply accrue). Display ID = {project.key}-C{number} (e.g. DWB-C3).

Title/summary/body live on revisions; the “current” title/body is the latest revision.

content_draft_revisions — append-only history

Every save appends a revision (update_content). No UPDATE/DELETE grant — immutable by construction, like requirement_revisions. Fields: id, org_id, draft_id, revision_number (sequential from 1), title, summary (nullable), body (markdown), note (nullable — the why), created_by, via_token_id, created_at. Title/summary/body carry forward from the latest revision when omitted.

content_deliverables — per-platform children of a draft

One deliverable per platform per draft (unique (draft_id, platform) on live rows). platform ∈ bsky | x | reddit | hn | blog (a CHECK; easy to extend). Post text lives on revisions. The “posted” fact is just three fields: posted_url, posted_at, and posted_revision_id (pins the revision that was posted) — set by record_post, the only mutable non-timestamp state in the module (an external world-fact, the deliverable analog of issues.claimed_by). No status machine. Rendered id = {draft-key}/{platform} (e.g. DWB-C3/bsky). No project_id — a grandchild routes through the draft, matching criteria. posted_revision_id is a nullable FK into content_deliverable_revisions (the deliverable↔revision cycle, mirroring requirements.approved_revision_id).

content_deliverable_revisions — append-only post-text history

Every update_deliverable appends a revision (id, org_id, deliverable_id, revision_number, body, note, created_by, via_token_id, created_at; unique (deliverable_id, revision_number)). No UPDATE/DELETE grant.

issue_deliverable_links — promote a deliverable into work

Copies issue_requirement_links in shape, pinned to the deliverable’s LATEST revision at link time: org_id, issue_id, deliverable_id, revision_id (NOT NULL), created_by, created_at, deleted_at. Content has no approval gate, so the pin basis is latest where the requirements link pins approved; the only link-time guard is cross-project (there is no “unapproved” rejection and no cross-cutting concept). Staleness is derived, never stored: pinned_revision_number < latest_revision_number means the post text was amended after the work was scoped — the UI badges the task (§8), reusing the requirements staleness badge.

assets — S3-backed files (Content & Assets module)

A project-scoped metadata row over a DigitalOcean Spaces object (the storage the §15 “Evidence / artifact entity” roadmap named). A peer module — issues, requirements, deliverables, and (later) chat messages all reference it; it is not content-specific. Fields: id, org_id, project_id, storage_key (the S3 key — internal, never on the wire), filename, content_type, size, sha256, status (pending | active | rejected), reject_reason (nullable), created_by, created_at, verified_at (nullable), deleted_at. Any file type. Integrity: SHA-256 read-back verification — the client computes the digest; the server verifies it by reading the uploaded object back and hashing (Spaces has no additional-checksum support), then copies the verified bytes to an immutable final key (copy-after-verify) before flipping the row active. A row needs a status machine (unlike content) because it exists before its bytes land. Upload/download are available over web, CLI, and MCP (upload_asset/download_asset) — all path-based: the bytes move directly to/from storage by a local file path and never cross a tool argument or result. That is the real invariant borrowed from the secrets reveal-plane split (it is about values, not the plane) — and it still holds: get_asset/list_assets return metadata only, and storage_key is never on the wire.

asset_links — polymorphic references TO an asset

Modeled on issue_requirement_links but polymorphic: id, org_id, asset_id, target_type (a text CHECK), target_id (a bare uuid — no FK, since the target is polymorphic), created_by, created_at, deleted_at (unique (asset_id, target_type, target_id) on live rows). target_type is seeded with the wired + planned values (deliverable_revision, content_draft, issue, requirement, chat_message, run, criterion), but only deliverable_revision and content_draft are wired today — adding another is a new enum value + UI, not a migration off an array. App-level integrity: a link is only ever created via link_asset, which resolves the target first. Appending a deliverable revision carries its live asset links forward, so an amendment never orphans the post’s attachments.

status_history — append-only transition log

One row per status change, written in the same transaction as the transition, plus a row at creation (from_status = null). Powers the activity log (§8). Append-only like requirement history — no UPDATE grant. (The audit schema cannot serve this purpose: the runtime role deliberately has no access to it.)

comments

org_id, issue_id, body (markdown), author_user_id, via_token_id (nullable), created_at, updated_at, deleted_at.

api_tokens

id, org_id, user_id (owning operator), label, token_hash (SHA-256, unique), token_prefix (first 8 chars, for display), last_used_at, revoked_at, created_at. Token format and hashing per §3.

org_instructions — org-level agent instructions

One row per (org, scope). scope is the closed set general | requirements | content | work.epic | work.task | work.bug | work.feedback (mirrors the domain instructionScopeSchema; the work.* values track issue types 1:1). body is 1–4000 chars — over-cap writes are rejected, never truncated; the cap bounds context fan-out, since every scope’s text is composed into the guidance the MCP get_work_context read returns (§7). Columns: id, org_id, scope, body, created_by, via_token_id, timestamps, deleted_at; partial unique on live (org_id, scope). Clear = soft delete; a later set inserts a fresh live row. Plain audited config rows (the milestones shape) — no revisions table; edit history lives in audit. Writes are ADMIN-only on both auth planes — deliberately bearer-reachable so an admin-owned pbt_ token edits over MCP (an accepted risk: instruction text binds every future agent session with no approval gate); any member reads. No project_id: a pbt_ token is org-pinned and one MCP session serves every project in the org, so per-project text cannot ride startup-frozen session guidance — project overrides, if ever wanted, arrive additively with a project-aware validation layer.

audit

Per §11.

5. Requirements module semantics

1. Project-scoped living documents. Requirements are organized per product area (e.g. “Status pages”, “Backup”) or per concern (vision, constraints, non-functionals), not per feature. Features link to the requirements they touch; a requirement is amended across the product’s whole life.
2. Every save is a revision. update_requirement appends to requirement_revisions; nothing is edited in place. Old versions are always viewable.
3. Approval pins a version. approve_requirement records an approval of a specific revision (default: latest) and sets approved_revision_id. Re-approval after amendments pins the newer revision; the approvals table keeps history.
4. Reads default to the approved revision. Agents building against a requirement get the approved version unless they explicitly request another revision (or the pinned revision on an epic link).
5. Links pin, badges warn. Epic↔requirement links freeze the revision the epic was sliced from. When a requirement’s approval advances past a link, the UI badges the epic. In chip rows the badge is the compact form r{current-approved} since (e.g. r4 since), sitting beside the pinned · r{n} link; in detail contexts the full phrase requirement updated since slicing is the badge/tooltip. Humans decide whether to re-slice, re-link, or ignore.
6. Cross-cutting requirements bind everything. A requirement flagged cross_cutting (vision, legal/privacy constraints, platform conventions, non-functionals) applies to every epic in the project with no explicit links. Agent context (get_issue) automatically includes the project’s cross-cutting documents at their latest approved revision — deliberately unpinned, because project-wide constraints evolve and always apply in their current form. Feature links remain pinned. Handling of mid-flight changes — a cross-cutting re-approval that conflicts with an already-frozen contract or in-progress epic — is defined in WORKFLOW.md: the evaluator records the epic blocked (set_blocked, with the cross-cutting change as the reason) and comments the conflict, and the operator decides whether to amend the contract or defer the new rule.

6. Workflow semantics (fixed — no configurable workflows)

The status enum is the only workflow. Conventions live in WORKFLOW.md; the server enforces exactly these rules:

1. Claiming is atomic. claim succeeds only if claimed_by IS NULL (single UPDATE … WHERE … RETURNING). Under concurrent claims, exactly one wins; the loser’s error names the current claimer. release clears it; explicit reassignment is allowed.
2. → verify requires every non-deleted criterion the issue carries with verification = 'auto' to be passed; an epic must additionally carry at least one non-deleted criterion. This is the agent handing off: its half of verification is done. What remains is whatever the issue’s manual criteria ask a person to judge, which for an issue carrying none is nothing. An issue whose criteria are all manual has no auto rows, so it moves freely — correctly, because there is nothing for the agent to verify — and so does a task or a bug carrying no criteria at all.
3. → done requires every non-deleted criterion the issue carries to be passed and every child issue to be terminal (done or killed), whatever the parent’s type; an epic must additionally carry at least one non-deleted criterion. A parent’s gate reads its children’s terminal status and never their criteria: a child’s own unpassed criterion holds that child open, and reaches the parent through the child’s status — the same fact arriving once rather than twice. The at-least-one check is the epic’s alone for two reasons: “every criterion passed” is trivially true over an empty set, so without it an epic that stated no contract walks past every gate; and below an epic most work is adequately described by its body, so demanding a checklist there would strand every task and bug already in flight. (A criterion added mid-verification blocks done until it passes — this is how discovery fold-in stays honest; see WORKFLOW.md.)
4. Every status change writes status_history in the same transaction (§4).
5. All other transitions are unrestricted, with one cross-type exception: a blocked issue (an active blocked mark, or at least one unresolved blocking issue — see §4) is refused on → ready and → in_progress, and the refusal names the mark’s reason and every unresolved blocker. ready otherwise carries no guard: it means “planned and specced, an agent can claim it.” Humans are trusted; agents follow the conventions in WORKFLOW.md. (In particular, “done epics never reopen” is a workflow convention, not a server guard — mistakes must remain correctable.)
6. Attaching open work moves the parent to in_progress. Both acts of attachment count: creating an issue that names a parent, and editing an existing issue so its parent changes. When the arriving child is non-terminal, the parent is set to in_progress and the move is written to status_history (rule 4) attributed to the actor that attached the child, which is the whole record of it — nothing else is raised. The reason is that a parent with fresh open work under it is being built again, and one left at verify goes on asking a person to judge work that is not finished, and stays in the waiting queue (§7 list_waiting) while it does. The move changes only the parent’s status: it gates nothing and refuses nothing. Three cases leave the parent’s status untouched: a terminal parent, which already refuses a non-terminal child (§4) so that this rule can never reopen finished work; a parent that could not lawfully reach in_progress — blocked under rule 5, or carrying no milestone, which every status but triage and killed requires — which keeps its status and still takes the child, because a finding has to stay fileable against blocked and unscheduled work; and the completion review task open_review creates, which is filed under its epic with the move suppressed, since the review is the gate the epic is waiting at. The rule has no inverse: a parent whose children all reach terminal stays where the rule left it, and only a person moves it on. An edit that leaves parent unchanged is not an attachment and moves nothing.

Trust model (state it in code comments and in the UI): acceptance criteria are the only gate. Criterion states split by mode: auto states are agent-verified observables with recorded evidence (set by the evaluator per WORKFLOW.md, and server-limited to auto rows); manual states are human assertions that only a web session can set. What this does and does not prove: evidence records that the evaluator confirmed a behavior against the running system, which is a stronger claim than a test file being unaltered — but it is still agent-reported, and a manual criterion is the only assertion a human makes directly. Independent execution arrives with the V2 runner (§15). The human gate on finishing is the manual criteria, and nothing else — reserved_for_person (§4) holds work for a person before anyone starts, which is a different gate on a different act. The done transition is not part of it: the completion guard takes no actor at all, so it cannot inspect the credential even accidentally. Every manual row holds its issue open until a person works through it, and an issue carrying none does not wait at all — so a criterion’s mode decides how much of an operator’s attention the work costs.

7. MCP server

apps/mcp: a stdio MCP server for Claude Code; the same tool surface is also served over streamable HTTP at the API’s /mcp endpoint, for clients that cannot spawn a subprocess and connect by signing the person in instead (upload_asset/download_asset are the local-only exceptions — they move bytes by a path on the machine running the server). Env (stdio): PIPEBRAIN_API_URL, PIPEBRAIN_TOKEN (a pbt_ token) — missing either fails startup immediately with a clear error (§2 configuration rule). All calls go through the HTTP API — the MCP server holds no database access. Tool errors return actionable messages.

Every mutation tool returns the created/updated resource — at least its uuid, display id, and the fields the call changed, plus server-computed fields (e.g. set_criteria returns the resulting list with each row’s stable number) — so agents can chain calls without a follow-up get.

Wire parameter names are camelCase (requirementLinks, crossCutting, criterionNumber, claimedBy, …), matching §9’s wire-casing rule — the tables below spell some fields snake_case for readability only.

Every tool refuses a call carrying an argument name it does not recognise, and the refusal names that argument — matching the HTTP layer’s strict-schema posture, so a misspelled or extra argument is never silently dropped. A near miss of a real field name (Summary, affected_surfaces) is therefore a refusal rather than a silent loss of what was typed, and every advertised input schema carries additionalProperties: false, so a caller can read the contract instead of learning it from a refusal.

Org instructions compose into the guidance the work-context read returns. At server start the org’s instruction texts (§4 org_instructions) are fetched over the API — fail-open: an unreachable API boots the server with no organization text, never blocks or crashes it — and composed into ONE document: the environment-binding banner, then the product’s shipped doctrine, then every saved scope, each under a heading naming it (## Organization instructions — general, — requirements, — content, — work.epic, …). A scope with nothing saved contributes nothing, not even its heading, and no tool description carries any of it. The guidance is a per-session snapshot — an edit applies from the next session, never a running one. An org with no instructions gets a byte-identical base surface.

Three surfaces, because the session-start field is 2KB (decision record PIPE-D30). The composition above is roughly nineteen thousand characters and the agent client truncates the server-level instructions field at 2KB — silently, and where several servers are configured they share about 4KB, so 2KB is a ceiling rather than a grant. So the composition rides the get_work_context result, which is not bound by that cap and which declares its own ceiling in _meta["anthropic/maxResultSizeChars"] rather than inheriting an operator-set default; the instructions field carries a bounded index naming that call, the environment binding, and the few rules whose violation cannot be undone; and every other read carries one fixed pointer line naming where the binding guidance lives and which call returns it. The index is independent of the org’s saved text, so its bound holds for every org rather than for the one that was measured. get_work_context is additionally marked _meta["anthropic/alwaysLoad"], since tool search defers definitions until an agent searches and the one call a session should make first must not need a search step to be visible. Nothing compels the fetch — the product is a ledger and does not drive agents — so the index, the pointer, and the pointer line on each authoring tool’s description are three independent prompts, and whether the layering works is checked by a person rather than asserted by a test that cannot drive the real client.

The complete registered tool surface — organizations, projects and milestones, deliverable targets, the waiting queue (list_waiting, the org-wide read of everything not moving on its own; it takes no narrowing arguments and returns the whole queue, while the §8 web view narrows what it draws by project and category), the working-context pack (get_work_context — everything a session needs before it starts, in one read, addressed by a work item or by a project), issues, requirements, Conventions (CONV-{n} — standing guidance for the whole organization, approved by a person), Prompts (PROMPT-{n} — the organization’s reusable prompt library), Decision records (KEY-D{n} — one decision per record, superseded rather than edited, with no delete tool), content and deliverables, Assets (metadata plus path-based upload_asset/download_asset — the bytes move by local file path, never through a tool argument or result; see §12), Secrets (values inbound-only, never returned — the reveal plane is the web UI and the ppb CLI; see §12), and Org instructions:

Deliverable promotion: create_issue and update_issue also accept deliverable_links (add/remove), mirroring requirement_links and pinning the deliverable’s current revision — the removable counterpart to the protected link promote_deliverable writes.

8. Web UI

Design intent: simple, fast, markdown-first — and everything about a feature on one screen. Explicitly out of scope: dashboards, time-series charts, drag-and-drop, command palettes, configurable views.

Design language (dark-first — match the reference mock in the repository)

• Layered surfaces, not boxes-in-boxes. Near-black page canvas; cards one step lighter with hairline borders and 12px radius; inset panels (e.g. a criteria checklist inside a slice card) one step darker than their card. Separation comes from surface steps and spacing — hairlines only divide rows within a card. Build dark-first; a light theme derives from the same tokens later.
• Tile-anchored rows. Every list row leads with a ~34px rounded-square icon tile tinted by meaning; text never floats unanchored.
• Semantic color map — the only colors. Green = passed/done · red = failed/bug · amber = blocked/warning · blue = needs-a-human and pinned requirement links · purple = milestones and in-progress activity · neutral gray = everything else. Color encodes meaning, never decoration; no gradients, shadows, or decorative effects.
• Typography. One sans for UI; monospace for every identifier (DWB-42, AC-3, commit SHAs, r3); two weights only (400/500); sentence case everywhere; 13–14px row text with 12–12.5px muted secondary lines.
• Status as colored text in rows, not pills. Chips are reserved for milestones, counts, and the small auto/manual mode tags.
• Restraint. At most one filled primary button per view (New issue); all other buttons outline/ghost.

Navigation: URLs carry the org and the project — /:orgSlug/:projectKey/…. The org segment resolves the active org (and points the shared API client’s X-Org-Id header at it, §9) before any child query runs; the org home lands a projectless visit on the org’s waiting queue (/:orgSlug/waiting), never inside whichever project was open last. Within an org, everything but that queue is scoped to the currently-selected project, chosen via a project switcher (backed by list_projects) at the top of the sidebar; the queue itself reads no project, but renders in the shell with the org’s remembered (else first) project selected — the same resolution the old landing redirect used — so landing there never starts a session at a dead project nav. Within that project: the Work page, plus Requirements, Content, Assets, Secrets, and Log sections. Pinned to the bottom of the sidebar, a utility cluster: Help · Feedback · Log · Settings. Feedback is a control, not a destination — it opens the shipped widget’s own panel in place (§10), so it is a button rather than a link with a URL to middle-click. Because the shell always offers that row, the widget’s floating button is suppressed for as long as the shell is mounted and restored when it is not: the signed-out pages (login, invite, forgot/reset password, verify-email) and /help have no Feedback row of their own, and the float is the only way in there.

• Waiting — the landing surface. The org-wide queue at /:orgSlug/waiting, where a projectless visit lands once the org has any project at all (an org with none gets the create-your-first-project state instead, which is the only thing that would help there): everything not moving on its own across all the org’s projects, longest wait first, grouped into the three sections §7’s list_waiting names — a requirement revision awaiting approval, a question awaiting an answer, and work in verify holding at least one criterion not passed. Not all of it waits on the operator, and the page says so rather than claiming every row is theirs: a question clears with answer_question and an auto criterion with set_criterion_state, so what genuinely waits for a person is a revision to approve and a criterion marked for human judgment. What counts as a gate, and the order, are the server’s: both clients read that one endpoint, so the definition cannot drift between them, and all this view decides is which of those rows to show. Each row names its project, says how long it has waited, and links to the surface the gate is actually cleared on. Three composable narrowings, all of them URL state: one project (a select), one category (chips over the three gate kinds), and a Mine / Everyone viewer scope. The first two make a narrowed page a link someone else can open on the same rows; the third does not, and cannot — mine resolves against whoever is authenticated, never against the sender, so a shared ?mine=1 link shows the recipient their own gates. Each carries its widening choice beside it wherever there is anything to widen, and an empty narrowed result says the filters matched nothing rather than claiming the org is caught up. Categories collapse, in memory only — deliberately neither in the URL nor in storage, since a fold is not part of what a shared link means and a remembered one would make an operator’s first visit somebody else’s — so every load starts fully open; a folded section carries the one number this view computes, how many rows it is holding out of sight under the narrowing in force. Nothing else is counted: listing individual gates and rolling nothing up is what makes a cross-project view admissible at all.

• Work — one project’s whole board. The former Queue, Board, and Overview consolidated on one screen (they superseded the separate views with no redirects): an attention preset (triage ∪ verify ∪ blocked — work in verify with any non-passed (pending/failed) manual criteria and their counts; blocked work — open issues carrying an active blocked mark or at least one unresolved blocking issue, the union counted once per issue, each row carrying the mark’s reason where there is one; and the triage backlog); facet filters (type, claimed, priority, milestone, plus environment tabs including “all” and server-side text search); the board rows grouped by status with inline status changes and claim/release, every row that carries criteria showing a progress fraction (e.g. 3/7), and an epic showing one whether or not it has stated any; and the derived overview/milestone strip — feature epics (top-level epics) with children counts by status and aggregate criteria progress, project totals by status, per-milestone done/total progress bars, and the active-milestone summary (the active row’s token, label, progress) — plus real empty states. Everything is client-side over one issues fetch naming every status (an omitted status now means open work only, so the page asks for all of them by name), with text search kept server-side — one fetch keeps the facets instant and the server simple. All live queries — no hand-maintained numbers, ever.

• Project switcher — a sidebar control (backed by list_projects) that sets the selected project; there is no standalone projects-index page — Work and every other project section are scoped to the selected project. The waiting queue above is the one exception and reads no project at all, which is what lets it answer “what needs me” for the whole org.

• Activity log — the runlog, derived. Status transitions from status_history, grouped by day, newest first. Default filter: flips to done (the “shipped” view), with an all-transitions toggle and type/milestone filters. Every entry links to its issue. The narrative half of a runlog — what was built and how it was verified — intentionally lives on the epics themselves (the builder’s handoff summary, criterion evidence, comments), not in a separate document.

• Feature epic detail — the centerpiece. For a feature epic (any epic with children), the detail page shows:

  • the epic’s title, rendered body, status, milestone, and claimer — status editable in place;
  • its linked requirements as chips — clicking opens the requirement in a slide-over panel at the pinned revision (with a “view latest approved” toggle and staleness badge), never navigating away; the project’s cross-cutting requirements appear as a distinct group of chips (always latest approved, no staleness concept);
  • a children table: display id, title, status (editable inline), claimer (claim/release inline), criteria progress n/m;
  • each child row expands in place to its criteria checklist — each criterion shows its stable AC-{n} id and mode (auto/manual), is checkable (click cycles pending → passed; an explicit control marks failed), and displays state attribution (who/when) plus expandable evidence on agent-verified rows. Agent-verified rows are visually distinct so the human instantly sees what’s left for them. A one-click “file bug” action on a failed criterion opens a prefilled bug form (type=bug, parent=<the issue that owns the criterion>, body referencing the criterion).

  The goal: verify a whole feature — read context, check criteria, flip statuses, file bugs — all in one place.

• Issue detail — rendered markdown body; edit mode with live preview (side-by-side on desktop, toggle on mobile); GFM support (tables, task lists, fenced code with syntax highlighting). Metadata panel: display id, type, status, priority, milestone, environment, claimer, parent/children. Acceptance criteria panel (on any kind that carries criteria — an epic, a task, a bug): the same checkable list, with inline add/edit/reorder and per-row verification mode. Requirement links open the slide-over panel. Comments use the markdown editor.

• Requirements list (per project) — display id, title, cross_cutting badge, lifecycle badge (draft / approved / amended), latest/approved revision numbers, linked-epic count, text filter.

• Requirement detail — rendered markdown at the approved revision by default; edit mode (appends a revision) with live preview; revision history list with per-revision notes and view-any-revision; Approve button (with confirmation when re-approving past amendments); approvals history; cross-cutting toggle; linked issues list with staleness indicators.

• New issue — minimal form with the markdown editor; optional requirement links, criteria, and milestone (the milestone input suggests tokens from the project’s milestones table, to prevent drift — everywhere milestones are edited).

• Content list & detail (Content & Assets module — semantics in §4/§7, operating flow in WORKFLOW.md) — the draft list mirrors the requirements list: rows grouped by area (no-area bucket last) with display id, title, summary, author byline, and deliverable / linked-issue counts; server-side text filter plus client-side area and author chips. The draft detail mirrors requirement detail — rendered body at a viewable revision, revision history, the deliverables list — with no approval concept, so no Approve control. The deliverable detail (/content/:ref/:platform) shows the current post text, revision history with an append-revision form, the posted fact (or a record-post form), linked issues with staleness chips, and linked assets (download / unlink / link more).

• Assets — the project’s binary attachments (§4 assets): browser uploads run the full SHA-256 → create → presigned PUT → complete-with-verify flow; list or thumbnail-gallery views with category filters and date/size sort (server-side); each asset carries a live link-count badge and opens a detail slide-over with its linked items and a delete action (gated on zero links).

• Secrets — the project’s encrypted secrets, scoped by environment tab (§7’s reveal rules): the management plane (create / rotate / rollback / describe / delete) carries metadata only, while reveal (view / copy) fetches a single plaintext imperatively per click — access-logged, held only in transient component state, and re-masked on toggle-off, tab switch, or navigation.

• Settings — one page at two mount points (org-scoped /:orgSlug/settings and project-scoped, the same component with the Project tab live or disabled depending on whether the URL carries a :projectKey; role gating is per-section, never per-tab). Project: environments (add / rename / delete, where delete is refused for an environment that has issues); milestones (create / rename token & label / reorder / set the single active one / archive a finished release and restore it — an archived row stays in the same list in position order, carries a visible archived marker, and offers no set-active control); deliverable targets (add / relabel / reorder / activate–deactivate; delete is refused for a target in use — deactivate instead; slugs are immutable); widget (key, allowed origins, copy-paste snippet). Organization: members & invitations (ADMIN/OWNER invites by email as ADMIN/CONTRIBUTOR, per §3/§4); API tokens (mint / reveal-once / revoke — open to any member, who mint their own); agent instructions (ADMIN-only — one editor over the seven scopes with a live character count against the 4000 cap and the standing note that edits apply to the next agent session). Account: password change, email change with token confirmation, sign out, leave org, and account deletion.

• Freshness — React Query polling, refetchInterval ≤ 10 s on lists and open detail views. No SSE/WebSockets in V1.

• Security — markdown rendering must sanitize HTML: feedback bodies are untrusted input.

9. HTTP API

Fastify under /api/v1, Zod-validated bodies, queries, and responses. Auth: session cookie or Authorization: Bearer pbt_…. Per-request org binding: a caller binds the org it acts in per request via an X-Org-Id header (or, on a GET, an ?org= query param for browser navigations that cannot set a header), so the request’s outbound scope and its cache key derive from the same org id — a mutable “current org” singleton would let one tab’s switch bleed into another tab’s request, and per-request binding closes that. This is one rule for every credential (PIPE-R7 rule 5): a bearer (pbt_) caller and a chat-client connection resolve the header exactly as a session caller does, and the caller’s role comes from their membership in the NAMED org, not from the credential’s row. Naming an org the credential’s holder is not a live member of is refused (403) before any org scope is set. A call that names none is refused (403 org_required) when the caller presents a bearer token or a chat-client connection, and the refusal names the organizations that caller could have named; no credential carries an organization of its own to fall back to. The routes whose purpose is to discover which organizations a caller may name are the exception, and answer without a scope. A session caller still falls back, through default_org_id → personal org → any membership. Resources mirror §4 and §7: issues (with nested comments / claim / status / criteria), requirements (with revisions / approvals / links), content (drafts / deliverables / posts), assets, projects (with environments, milestones, read-only status history for the activity log, and the project-nested secrets routes — /api/v1/projects/:key/secrets), orgs, org membership (members / invitations), org instructions, notifications (the caller’s own registered devices and per-event preferences), tokens, auth. Public and unauthenticated: GET /api/healthz (checks DB connectivity with SELECT 1) and the feedback intake (§10).

Wire casing: JSON on the wire is camelCase everywhere (matching §10’s projectKey/pageUrl/appVersion and TS idiom); database columns stay snake_case; the Zod schemas define the camelCase wire shape.

List endpoints accept limit (default 200, max 500) and offset, and return { items: [...] }.

Web-session-only routes: token management (mint / list / revoke) and password change reject bearer auth — a pbt_ token must not mint or revoke tokens. (This sits alongside the manual-criteria web-only rule of §4.)

The web app consumes this same API — no private endpoints for the UI (UI-is-contract).

Reserved, documented, not built: /api/v1/jobs/* — runner claim/lease/heartbeat/complete (§15). Design module boundaries so adding it later touches nothing in the issues or requirements modules.

10. Feedback widget

The wire contract is the product; clients are thin.

Intake endpoint — POST /api/v1/feedback (unauthenticated)

• Body: projectKey (pk_…, required), message (required, ≤ 4,000 chars), optional environment slug, email, pageUrl, appVersion, metadata (flat object).
• Total payload cap 16 KB.
• Unknown project key: same response shape/timing as success where practical (no key-probing oracle). Missing or invalid environment → the project’s default_environment_id (§4, seeded to prod).
• CORS: Origin checked against the project’s allowlist.
• Rate limits (env-configurable; in-memory is acceptable for a single instance): 10/min and 100/hour per IP; 1,000/day per project key. Over limit → 429. The client IP is read from X-Forwarded-For as set by DO App Platform’s edge — Fastify runs with trustProxy enabled and derives the IP from the trusted proxy position, never the leftmost client-supplied value (which is spoofable). This is why the api service is pinned to exactly one instance (§12): the counters are per-process.
• Effect: creates an issue — type=feedback, status=triage, source=widget, context captured into namespaced metadata (system = server-captured: user agent, origin, received-at; client = the submitted payload, untrusted), created_by = null.

Web snippet (V1 deliverable)

A single widget.js — vanilla JS, zero dependencies, ≤ 10 KB, served from the app — configured by data attributes:

<script src="https://app.pipebrain.dev/widget.js" data-key="pk_…" data-environment="prod" defer></script>

Floating button → small panel (message textarea + optional email) → POST → thank-you → reset. Graceful failure on network errors and 429. Basic accessibility (labels, focus trap, Esc closes). No screenshots in V1.

The floating button is the default shape, not the only one. data-launcher="none" on the script tag suppresses it — the launcher is still mounted, just hidden — leaving the host page to open the panel on its own terms. Absent the attribute (every embed written before this existed), the button appears exactly as before. The widget publishes a single global, window.pipebrainFeedback, carrying open, close, showLauncher, hideLauncher, and submit({ message, email?, pageUrl? }) — and nothing else — then announces itself by dispatching a pipebrain:feedback-ready event on window. The event is load-bearing: the script is deferred, so the host page’s own code may run either before or after it, and without the announcement whichever ran second would win by accident. A page that finds the global already present uses it immediately and also listens; both orders work. submit shares one post path with the panel’s own form — same frozen body, no extra fields — resolves only on an ok response, rejects on an empty message, a non-ok response, or a network failure, and never touches the panel UI. With no floating button there is nothing to anchor to, so open() centres the panel over a dimmed scrim (click to close); with the launcher present it stays anchored to the launcher’s corner — the bottom right, unless the embed asked for another.

Which corner that is comes from data-corner on the script tag, one of exactly four values: bottom-right (the default), bottom-left, top-right, top-left. The raw attribute is trimmed and then matched exactly, as data-key, data-environment and data-app-version are read (data-launcher is the exception — it compares untrimmed), and it is not lowercased. Anything else — absent, empty, whitespace, a typo, a different case — resolves to bottom-right silently, with nothing written to the console: the widget runs on somebody else’s page, where a mistyped attribute should cost the chosen corner and leave a working feedback button. The corners are physical viewport corners and do not follow the page’s writing direction. The launcher and the panel opened from it share one corner; with data-launcher="none" the panel still centres over the scrim, because a centred panel has no corner to sit in. The corner is read once at mount and is not part of the public surface — window.pipebrainFeedback gains no method and no argument for it, and the five methods above remain the whole of it.

React Native client

Post-V1. It targets the endpoint contract above, unchanged.

11. Data & security invariants (non-negotiable)

1. Soft deletes only. Every tenant table has deleted_at; the runtime role has no DELETE grant; all reads exclude soft-deleted rows. Exception by design: requirement_revisions, requirement_approvals, and status_history are append-only history — the runtime role additionally has no UPDATE grant on them.
2. Audit via DB triggers. An audit.log table in a separate schema records insert/update/soft-delete on tenant tables with the row diff and the actor. The actor is read from two transaction-local GUCs set alongside app.org_id: set_config('app.actor_id', …) (the acting user, written to actor_user_id) and set_config('app.token_id', …) (the API token, null for web sessions, written to actor_token_id) — so the audit row carries both, distinguishing “an operator in the browser” from “their agent over MCP” per §3. The runtime role has no privileges on the audit schema. The trigger functions are therefore SECURITY DEFINER, owned by the migration role, with a pinned search_path (SET search_path = '', fully-qualifying every reference) so the invoker’s lack of audit privileges does not block the insert and the standard escalation footgun is closed.
3. RLS from migration 0001. Every tenant table: org_id NOT NULL, RLS enabled and forced, policies scoped to current_setting('app.org_id'), set per transaction from the session/token. The runtime role is non-superuser, non-BYPASSRLS; the API refuses to boot if it detects a privileged database login, and additionally verifies at boot that the runtime role owns no tenant table (ownership implicitly confers DELETE/UPDATE regardless of grants). Tenant tables (and the audit schema, functions, and sequences) are owned by the migration role, never the runtime role — runtime ownership would nullify the grant-based soft-delete and append-only invariants.
4. Zod-first, named exports. If money ever appears, integer minor units (it should not in V1).
5. Migrations are forward-only. Production changes are new migrations, never edits to applied ones.
6. Secrets live only in App Platform encrypted env vars and local gitignored config. .do/app.yaml is committed as a placeholder template only.

12. Infrastructure & deployment

Topology: one DO App Platform app with three components — web (static site: SPA build + widget.js), api (Dockerfile service, routed at /api, pinned to exactly one instance — the in-memory rate limiter (§10) keys per-process, so horizontal scaling would silently multiply the effective limits; §2 excludes a shared store (Redis), making single-instance an enforced V1 constraint), migrate (PRE_DEPLOY job running dbmate up). The migrate job runs schema migrations only, connecting as the migration role via a separate privileged DATABASE_URL_ADMIN env var scoped to that job and never available to the api service (so the §11.3 boot guard never sees a privileged login). Same-origin cookies by construction. deploy_on_push from main; a deploy goes live only if migrations and the GET /api/healthz check pass. The app serves at its custom domain, app.pipebrain.dev.

Database — a logical database on a shared managed cluster. Pipebrain does not get its own cluster: an operator provisions, once and before the first deploy, a dedicated logical database, a non-privileged runtime login that may connect to that database and to no other on the cluster, and a transaction-mode connection pool sized to leave the cluster headroom for migrations and admin scripts. The runtime role’s grants arrive with the migrations, so §11’s RLS rules govern it rather than hand configuration, and the api reaches it over the pool while migrations and one-time admin scripts use the direct connection. Which cluster, in which region, at which size, on which ports, and under which pool and role names, are operational facts rather than requirements: they belong to the deploy specification and to the team’s internal cluster note, which change on their own schedule and are verifiable against the running system.

Local development: docker compose Postgres 17. Every local port (Postgres, api, web) comes from .env — docker compose reads it too; nothing is hardcoded. The operator machines run several projects’ databases and dev servers concurrently, so .env.example ships collision-avoiding suggestions (e.g. Postgres 5456, not 5432) and each machine adjusts locally. Dev servers bind 0.0.0.0 so the app is reachable from other devices on the LAN; the web dev server proxies /api to the api process, so session cookies stay same-origin from any device. npm run setup = compose up + dbmate up + seed (org, two operators, one demo project with cross-cutting + area requirements, a feature epic, slices with criteria, and a milestone). npm run dev = api + web. npm run check = typecheck + lint + tests + build (integration tests read the same .env). No cloud dependencies locally.

Production bootstrap: the migrate PRE_DEPLOY job runs schema migrations only — it seeds no rows. A documented one-time script, npm run bootstrap:prod, is run manually against the direct (non-pooled) admin connection after the first deploy’s migrations succeed; it creates the org and the two operators from gitignored config (values sourced from App Platform secrets in prod), and nothing else — no demo project or sample content. Without it a fresh prod database has no org row (RLS requires one) and no operators (login requires them).

Env vars & secrets (per component):

Every variable above appears in the committed .env.example; none has an in-code default — a process missing any required var refuses to start and names it (§2).

CI: GitHub Actions runs npm run check on pull requests and pushes to main, required before merge; deploy_on_push remains the deploy trigger. npm run check’s integration tests need Docker (a local Postgres 17 service container mirroring the compose setup), so CI provisions one.

13. Testing requirements (the build-era record)

This section and §14 record what V1 was built and gated against, and they are kept for that reason: forty-odd code and test files cite their items by number. New work is governed by the tracker’s requirement documents and by the acceptance criteria on the work itself — an epic, a task or a bug — not by this list.

Jest. Integration tests run against local Postgres and are the proof for §14. Minimum coverage:

• RLS isolation: a second seeded org’s rows are invisible through the API and as the runtime role; the boot guard rejects a privileged login.
• Claim atomicity under concurrency; display-number uniqueness under concurrency (≥ 50 parallel creates, issues and requirements).
• Status guards: the verify guard over auto criteria (§6 rule 2) and the done guard over all criteria (§6 rule 3) — including a criterion added mid-verify blocking done until passed, the zero-criteria refusal on both, and an all-manual epic reaching verify freely.
• create_issue: omitted status defaults to triage; omitted environment resolves explicit → parent’s environment → project default_environment_id. update_issue rejects a type change into a kind that cannot carry criteria (feedback) while the issue has non-deleted criteria, and permits every epic/task/bug retype. create_issue/update_issue reject a self-parent and a cycle (ancestor-walk). The parent move (§6 rule 6) on both paths: a non-terminal child moves its parent to in_progress from every non-terminal status and writes one status_history row attributed to the actor; a terminal child, a blocked parent, a parent with no milestone, an edit that leaves parent unchanged, and the review task open_review files each leave the parent’s status as it was, and the blocked and milestone-less parents still take the child.
• Criteria guards: verify requires every auto criterion the issue carries to be passed; done requires every criterion it carries to be passed; both additionally refuse an EPIC with zero criteria, while a task or a bug carrying none passes untouched; an issue whose criteria are all manual reaches verify freely.
• Requirements: every update appends a revision (append-only enforced — UPDATE on revisions is rejected at the DB level); approval pins; lifecycle derivation (draft/approved/amended); links pin the approved revision; staleness derivation when approval advances; cross-cutting inclusion — get_issue returns cross-cutting documents at the latest approved revision, reflecting re-approvals immediately, with no staleness computed for them; the optional revision note round-trips. Linking (via create_issue/update_issue) to a requirement with no approved revision is rejected; toggling cross_cutting=true on a requirement that has explicit links is rejected, while toggling it off is allowed.
• Criteria: create/replace via set_criteria (with modes); state changes attributed with evidence; state resets exactly when a matched row’s text or verification mode changes (and survives pure reorders); criterion numbers are stable across reorder and set_criteria replacement and never reused; set_criterion_state resolves by uuid and by issue + AC number; mode enforcement — a token-authenticated request cannot set state on a manual criterion, a web session can, and auto accepts both; how_to enforcement — a token is refused (how_to_required, naming each offender) on a manual item it writes new, retitles, or flips from auto without howTo, a row kept with unchanged text is exempt and a web session is never subject to the rule, howTo on an auto item is rejected by the schema, a kept row preserves stored instructions when the payload omits them and drops them on a flip to auto, and a call changing only howTo leaves state, evidence and attribution untouched.
• Status history: a row is written in the same transaction as every status change (and at creation); append-only enforced at the DB level; the activity-log query returns transitions filtered and day-grouped.
• Widget: CORS allowlist, rate limits, payload caps, unknown-key behavior, feedback-issue creation with system/client metadata namespacing.
• Soft-delete visibility rules and the absence of DELETE grants — asserted ownership-aware, by querying the catalog for the runtime role’s DELETE privilege on each tenant table and requiring it to be false; the boot guard also rejects a runtime role that owns any tenant table; audit rows with actor for insert/update/soft-delete.
• Token lifecycle: mint → authenticate → attribute → revoke → reject. Token-management and password-change routes reject bearer auth (web-session-only).
• Milestones: token is unique per project; the partial unique index permits at most one active milestone per project; a table check keeps active and archived from ever both holding, so the refusal to archive the active milestone and the refusal to activate an archived one cannot disagree with the stored row; the active-milestone summary joins the active row (token, label, progress); an issue carrying a milestone token with no milestones row still groups under it on the overview.
• Health: GET /api/healthz returns healthy when the DB answers SELECT 1 and reflects the DB being unreachable.
• Config fail-fast: the api (and the MCP server) refuse to start when a required env var is missing, and the error names the missing vars; ports and bind address come from env, never code.
• Org instructions: upsert set semantics on the (org, scope) natural key; the 4000-char cap rejects (never truncates); the ADMIN write gate holds on BOTH auth planes (a CONTRIBUTOR session and a CONTRIBUTOR token each 403, an ADMIN succeeds) while any member reads; clear = soft delete with a fresh live row on re-set; RLS isolation; audit attribution for user- and token-plane writes; the composed guidance proven on a fresh spawn (returned by get_work_context — the doctrine whole, then every saved scope exactly once under a heading naming it, an unsaved scope contributing not even its heading, no tool description carrying any of it, and the session-start index within the client’s cap), fail-open boot with the API unreachable, and per-session snapshot staleness (a running session keeps its startup text).
• MCP end-to-end (§14.31): a Jest-driven test spawns apps/mcp over stdio against a locally running API (using a minted pbt_ token), asserts tools/list matches the registered tool names exactly and that no tool description carries organization text (the org’s guidance rides the get_work_context result, behind a bounded index in the server-level instructions field), and drives the core workflow tools end-to-end.

14. V1 acceptance criteria (the build-era record)

Item numbers are stable and never reused — the same rule this document sets for AC-{n} in item 12, and for the same reason: roughly forty code and test files cite these items by number (§14.26), so renumbering silently repoints every one of them at a different claim. Items 14–16 are retired: they specified acceptance suites and run history, removed in rev 11. The gap is deliberate.

Projects & environments

1. An operator can create a project (name, key); dev and prod environments are seeded automatically and default_environment_id is set to prod; environments can be added, renamed, and deleted (delete refused when the environment has issues); milestones can be created, renamed (token + label), reordered, set active (at most one active per project), and archived and restored — an archived milestone stays listed and keeps its token, label and position, disappears from the everyday pickers except where it is the value already chosen, and still accepts a completion review; archiving the active milestone and activating an archived one are refused.
2. Issue display IDs are KEY-N and requirement display IDs are KEY-R{N}, per-project, increasing; 50 concurrent creations of each kind produce no duplicate numbers (integration test).

Issues 3. Issues of all four types can be created and edited with markdown bodies; environment is required; parent and milestone are optional. Omitted status defaults to triage; omitted environment resolves explicit → parent’s environment → project default_environment_id. Changing type to feedback is rejected while the issue has criteria, and epic/task/bug retypes are permitted; a self-parent or a parent cycle is rejected. Attaching open work to a parent — at creation, or by changing an existing issue’s parent — moves that parent to in_progress and records the move against whoever attached the child; a terminal parent refuses the attachment instead, a blocked or milestone-less parent takes the child and keeps its status, and the completion review task is filed without moving anything. 4. Filters work: project, environment, status, type, claimed_by, priority, milestone, and text search over title + body. 5. Status transitions follow the enum; the criteria guards are enforced on whatever work carries criteria (ready is unguarded; verify needs every auto criterion passed; done needs every criterion passed — including criteria added mid-verification; both verify and done additionally refuse an EPIC with no criteria at all, a refusal that binds an epic alone). 6. Claiming is atomic: concurrent claims by both operators yield exactly one winner (integration test); release works; the claimer is visible in lists. 7. Soft delete: deleted rows vanish from lists and API responses but remain in the database; the runtime role has no DELETE grant (test).

Requirements 8. Requirements can be created, listed, and read per project; every edit appends a revision; an optional revision note is persisted and shown in history; any historical revision is viewable; direct UPDATE of a revision row is rejected at the database level. 9. approve_requirement pins a revision; lifecycle badges derive correctly (draft → approved → amended after a post-approval edit → approved again after re-approval); approvals history is retained. 10. Linking an epic to a requirement pins the approved revision; when the requirement’s approval later advances, the epic shows a staleness indicator (API-derived, UI-visible); linking to a requirement with no approved revision is rejected with an actionable error. 11. A requirement can be flagged cross_cutting; get_issue on any epic in that project includes it at the latest approved revision (re-approvals reflected immediately, no staleness shown); non-flagged requirements appear only via explicit links. Flagging cross_cutting is rejected while the requirement has explicit links; un-flagging is always allowed.

Acceptance criteria 12. Criteria can be authored on an epic, a task, or a bug (ordered, each auto or manual), edited, reordered, and soft-deleted, and are refused on a feedback issue; each carries a stable per-issue AC-{n} number preserved across reorder and set_criteria replacement and never reused; set_criterion_state resolves by uuid or by issue + number; states (pending/passed/failed) carry attribution (who, when, via which token) and evidence; a token cannot set state on a manual criterion (rejected with a clear error), while auto criteria accept token or session. 13. An issue of any kind with any non-passed criterion cannot be set to done, and one with any non-passed auto criterion cannot be set to verify; each guard error names the unmet criteria by AC-{n}. An epic with zero criteria is refused at both; a task or a bug with zero criteria is not.

Comments 17. Markdown comments render correctly with attribution (operator, plus token label when submitted via MCP).

Auth & tokens 18. Seeded operators and invited members can log in; there is no open signup surface — account creation happens only through a valid org invitation (invite-gated, per §3). 19. Tokens: mint (plaintext shown once), label, revoke; the API rejects revoked tokens; MCP authenticates with a token; actions attribute to the owning operator and record the token.

Widget 20. The snippet, embedded on an external origin in the CORS allowlist, submits successfully; a disallowed origin is rejected. 21. A submission creates a feedback issue in triage with metadata captured under system (server-captured) and client (submitted) namespaces; rate limits are enforced per IP and per key (integration test); a payload over 16 KB is rejected.

Security invariants 22. RLS: a second seeded org cannot read or write the first org’s rows through the API or as the runtime role via direct SQL (integration test). 23. Audit rows are produced for insert/update/soft-delete on issues, requirements, and criteria, with the actor recorded; the runtime role cannot read the audit schema. 24. The API refuses to boot when the database login is superuser or BYPASSRLS, or when the runtime role owns any tenant table.

Web 25. The Work page (Queue, Board, and Overview consolidated) shows the verify work with any non-passed (pending/failed) manual criteria and their counts, blocked work (open issues with an active blocked mark or an unresolved blocking issue — the union, each issue counted once, carrying the mark’s reason where there is one), the triage count, and the active-milestone summary (active row’s token, label, done/total progress), all derived live; navigation project → environment → status works; the Requirements section lists and renders documents with revision history, approval, and the cross-cutting toggle. 26. The feature epic’s detail page works end-to-end: children table with inline status changes and claim/release; criteria checklists expand in place showing stable AC-{n} ids and are checkable with attribution and evidence; linked requirements open in a slide-over at the pinned revision without navigation; cross-cutting requirements appear as their own always-current group; a failed criterion offers a prefilled file-bug action. 27. Issue detail shows the rendered body, edit-with-preview, comments, and — on any kind that carries criteria — the criteria panel. 28. The overview/milestone strip on the Work page shows feature epics with children counts by status and criteria progress, project totals, and per-milestone counts — all derived live from current data. 29. The activity log shows status transitions grouped by day (default filter: flips to done), each entry linking to its issue, derived from status_history. 30. Lists and open detail views refresh via polling (≤ 10 s) without user action.

MCP 31. The full registered tool surface functions end-to-end against a running API — a Jest-driven test that spawns apps/mcp over stdio against a locally running API (with a minted pbt_ token), asserts tools/list matches the registered tool names exactly, that the criteria-authoring tools’ descriptions teach the howTo rule, and that the server instructions field names the API the session is bound to under the Pipebrain banner, and drives the core workflow tools.

Ops 32. On a fresh clone, cp .env.example .env then npm run setup brings up local Postgres, migrates, and seeds; then npm run check passes clean (its integration tests require the Docker Postgres from setup). All ports come from .env; the dev servers bind 0.0.0.0 and the app is usable from another device on the LAN; a missing required env var fails startup with an error naming it. CI runs npm run check on PRs and pushes to main, required before merge. 33. Deploys run migrations as a PRE_DEPLOY job (as the migration role via DATABASE_URL_ADMIN) and abort on failure; GET /api/healthz gates rollout; npm run bootstrap:prod is run once against the direct admin connection to create the org and operators.

Org instructions 34. Org-level agent instructions round-trip end-to-end: an ADMIN sets per-scope texts (the Settings editor or the *_org_instruction tools), a freshly spawned MCP session’s get_work_context read returns every saved scope exactly once — the doctrine whole, then one block per scope under a heading naming it, an unsaved scope contributing nothing, no tool description carrying any of it, and the server-level instructions field carrying only the bounded index — a running session keeps its startup snapshot, an unreachable API at spawn boots fail-open with no organization text, and writes below ADMIN are rejected on both auth planes.

15. Out of scope for V1 / roadmap

• Runner (V2 — first expansion). A local polling service each operator can run. It claims jobs over the reserved /api/v1/jobs/* surface with leases and heartbeats. First job kind: independently re-execute an epic’s acceptance tests and record machine-trusted evidence against its auto criteria — the missing half that made the V1 manifest check worthless. Later: headless builder kickoff. Pipebrain remains a ledger; the runner executes deterministic jobs, never orchestration.
• Decision records — built. Shipped as their own module rather than via the document-kinds generalization this entry once sketched: a decision record (KEY-D{n}) is written once, proposed until it is accepted, and from accepted on changes only by being superseded by a replacement — no revision chain, so there was no revisions/approvals machinery to share with requirements after all (§7 create_decision / update_decision / accept_decision / supersede_decision; citing one from work or from a requirement is a link field on update_issue / update_requirement, never a tool of its own). Decisions with a real tradeoff are recorded here and attached to what they govern (see WORKFLOW.md).
  • Note (Content & Assets module): the Content module (§4 content_drafts) was likewise built as a parallel sibling of requirements, NOT via the document-kinds generalization — deliberately: content has no approval gate and has child deliverables, neither of which the requirements tables model, so folding it in would have meant nullable-approval columns and a kind-conditional guard on every existing requirements query. With decisions also shipped standalone, no module uses the document-kinds route.
• Real-time chat — Slice 1 specified, not yet built (PIPE-11). An org-scoped single stream (no channel entity — the stream is the org; access is the existing org-anchored RLS), ordered by a server-assigned per-org monotonic seq (never created_at). Messages tag entities via message_references reusing the pinned-revision-link primitive, with bidirectional backlinks (“mentioned in chat” on the referenced entity) and a derived project filter; per-user reactions; one chat_read_state row per (org, user) driving both the unread line and read receipts; attachments through the assets module (precondition: org-scoped assets with nullable project). Live delivery via @fastify/websocket with Postgres LISTEN/NOTIFY fan-out — the sanctioned revision of §2’s WebSockets exclusion. The web panel is shell-mounted (never per-route). PWA install and push notifications have since shipped as their own slices (the notifications entry below); offline sync has not. @user mentions, threads, presence, and MCP chat tools are explicitly out of scope. The acceptance contract lives on PIPE-11’s criteria rows.
• Requirement revision diff view (side-by-side or inline diff between two revisions). V1 ships view-any-revision; diffing is deferred.
• React Native feedback client — targets §10’s contract unchanged.
• Realtime (SSE) if polling ever grates — note that LISTEN/NOTIFY requires a direct (non-pooled) database connection. The chat slice above adopts WebSockets + LISTEN/NOTIFY for one org-scoped stream ahead of this entry.
• Issue relations (V2 — partially realized). The single additive issue_relations table this entry anticipated now exists (§4), with the kind column it named (blocks | depends_on | duplicates | relates_to). Only kind = 'blocks' is exposed: blocked-by / blocks edges between issues in the same project, written from the waiting issue’s side, feeding the blocked signal (§8) and the guard that refuses ready/in_progress while a blocker is open. depends_on, duplicates, and relates_to remain deferred surface — the column accepts them, nothing writes or reads them, and wiring one is a query plus UI, not a migration.
• Evidence / artifact entity (V2 — partially realized). The object-storage foundation this entry anticipated now ships as the Assets module (§4 assets, DigitalOcean Spaces). Assets are referenced polymorphically via asset_links, whose target_type already seeds the run, criterion, and issue targets this entry named — but only deliverable_revision and content_draft are wired today. Attaching typed artifacts to runs / criterion evidence / issues is now a matter of wiring those existing enum values (a target UI + query), not new storage.
• Requirement comments (V2). Review discussion threads on requirement documents; in V1, review discussion lives on the feature epic’s comments. Additive later (dedicated table or polymorphic comments).
• Notifications — built (PIPE-197). What earned it: agents stop and ask when they need a decision, and nothing told anyone they had stopped, so the delay between an agent stopping and a person reading it was however long until someone next opened the app. A person registers a device and chooses which of four events notify them — a question asked, work reaching verify, feedback arriving, a chat message. Two rules are part of the decision rather than details of it: you are not notified about what you did yourself in a browser but are notified about what your own agent did through a token, and a notification raised by text an outsider submitted never carries that text. Delivery reaches the device through the push service the person’s own browser picks; why a carrier the browser chooses is not a dependency this product took is settled in the stack requirement. Still deferred: digests, batching, quiet hours, per-project muting, a notification inbox, and email as a second channel.
• Full-text search — built. Organization-wide rather than per-project, scoped by the same isolation every other read obeys. Which kinds of record it reaches is deliberately not fixed here: a kind joins when a result for it can be opened and acted on.
• Labels, burndown charts, and additional internal-tooling modules — only when a concrete need appears.