---
title: Handoff
description: "We write what we want. Engineering proves it works."
---

# Handoff

The wiki is where things get decided. It is not where they get built.

## The boundary

```text
  be-internal  (product side)          engineering  (elsewhere)
  ┌────────────────────────┐          ┌────────────────────────┐
  │ research, architecture │  ─ ✗ ─▶  │ the actual code        │
  │ requirements, specs    │          │                        │
  │                        │          │  NO READ ACCESS        │
  │ no code lives here     │          │  from this repo        │
  └────────────────────────┘          └────────────────────────┘
             │                                     ▲
             │       a PR is the only door         │
             └─────────────────────────────────────┘
```

Nothing in `be-internal` can read source, and that is the point. A spec
written by something that can read the code drifts into describing the code
— it inherits the compromises and stops being a target. We architect from
what we want, not from what exists.

## When a spec is ready

```text
  1  SPEC     a page in this wiki, argued and agreed
       │
       ▼
  2  PR       opened against the engineering repo
       │      this is the request — there is no other kind
       ▼
  3  BUILD    engineering builds it in GitHub
       │
       ▼
  4  TRACK    the PR link goes back on the spec page
```

Nothing gets requested in a DM, a comment or a conversation. If engineering
needs to do something, there is a PR, and the wiki knows its number.

## Who owns what

```text
   we own        WHAT it should do, and why        ◀── source of truth
   they own      HOW it gets built                 ◀── implementation
   they prove    that it meets the requirement     ◀── conformance
```

The docs do not get updated to match what shipped. If what shipped does not
meet the spec, that is a gap in the build, not a correction to the doc.

## Recording it

Every spec page that has become real ends with a block like this:

```markdown
## Build

- [ ] PR [#42](https://github.com/beliefengines/<repo>/pull/42)
      opened 2026-08-26
```

Tick it when it merges. The spec page is the tracker — if a build is not
linked from the wiki, it is not being tracked.

## Builds in flight

| Spec | PR | Opened | Status |
|---|---|---|---|
| — | — | — | nothing open yet |

---

This is about engineering work only. Editing the wiki itself still pushes
straight to `main` — see [editing the wiki](/handbook/editing-the-wiki).
No branches, no PRs, for pages.