amplifier-bundle-converge

# Standing rules for this repository

Read these before your first edit. They apply to every session working here —
human, Amplifier, or another tool's coding agent — and they are the same rules
the people here follow. Nothing on this page needs the Amplifier bundle.

Read next: `PINS.md` (hard facts), `docs/CONTRACTS-README.md` (what a contract
is and how to change one). New to this method, or taking it to another
repository? `docs/ADOPTING.md` is the first day start to finish — install, check
that it took, start a manager session, and copy the participant kit correctly.

## Vocabulary

- **Intent steward** — the person who decides where this project is going. Their
  word is the law you obey.
- **Manager session** — the long-running AI session that runs the project's work
  on the steward's behalf: it plans, briefs, launches, verifies, integrates. It
  runs from the workspace root and everything it stands up lives at
  `<workspace>/.converge/<project>/` — the rule and its reason are in
  `modes/converge-manager.md`, clause 5.
- **Worker session** — a short-lived AI session that takes one bounded piece of
  work in its own copy of the code and returns with proof. You are probably one.
- **Contract** — a short promise this project must keep, in `contracts/`. A
  contract is *locked* (its heading carries `(FROZEN <date>)`) or *draft*.

## 1. Converge toward the vision and the contracts

`docs/VISION.md` says where this project is going. The contracts in
`contracts/` say what must be true along the way. Everything you do moves the
repository toward them.

- **Work is derived, never invented.** Every change traces to the gap between a
  contract and what exists, or to feedback the steward gave. Name the contract
  your change serves — one line, in the work item and in the commit message.
- **If a contract and the code disagree, the contract wins** — unless you have
  evidence the contract is wrong, in which case see rule 2.
- **If no contract covers what you are doing, stop and say so.** Do not invent
  the promise yourself. A missing contract is a decision for the steward.
- **A repository with *no* contracts at all is the one exception, and it has its
  own shape** — investigate, then propose: `contracts/operation.v1.md` Core 14,
  carried out in the clause 14 section of `modes/converge-manager.md`.
- **Converge is self-hosting.** This repository passes the same participant kit
  it ships in `docs/workspace-template/`. A rule we do not follow here is not a
  rule we may ship.

## 2. Change a locked contract only through a ratified proposal

A file whose heading carries `(FROZEN <date>)` takes no unapproved direct edit.
Not for a typo, not "while I'm in there", not because the change is obviously
right. Write the proposal first; leave its target unchanged while it awaits
the steward's answer.

To change one, add a sibling file named `<contract>.vN-candidate.md` — for
example `contracts/documents.v2-candidate.md` — with three parts, in order:

1. **The exact change**, sentence by sentence.
2. **The evidence** — a cost actually paid or a failure actually caught.
   Preference is not evidence.
3. **What does *not* change.**

The original stays the law until the steward answers with one word: *ratified* ·
*ratified with edits* · *declined* · *later*.

Once the steward has ratified the exact change and authorized publication,
verify the target, approved candidate bytes or hash, decision record, and test
evidence. Apply only that approved diff plus its dated changelog through the
existing guard, preserve the proposal and decision evidence, and re-check the
ledger. That is §5 publication, not a second ratification. Follow
`context/converge-awareness.md` for the same distinction; higher-priority
instructions remain controlling.

Two guards enforce this, and they are not the same guard. `.githooks/pre-push`
refuses a push that edits a locked file without a candidate beside it;
`hooks-candidate-guard` denies write-shaped tool calls inside an Amplifier
session. `PINS.md` records exactly what each one checks, including where they
currently disagree. **If a guard refuses you, do not work around it.** The
refusal is the rule working. If the guard is wrong, file that as work.

- Six documents are locked as of 2026-09-06 (docs/VISION.md, contracts/composition.v1.md, experience-operation, -console, -collaboration, -direction): both guards — the pre-push scan and hooks-candidate-guard — are ACTIVE for them; a change goes through a `<name>.vN-candidate.md` proposal beside the file. The remaining contracts are DRAFT (three held loosely) and may be edited in place with a changelog row when it fits.
blocking anything. The rule still holds — write proposals, not edits, the moment
one locks.

## 3. Where the contract check lives

The **ledger** at `ledger/rows.yaml` records, one row per checkable clause,
whether that clause is currently *Kept · Not yet · Broken · Pinned open · Can't
check*. Its format is `docs/LEDGER-FORMAT.md`. It is derived from the contracts,
never hand-edited into agreement with the code.

**Both the ledger and the kits exist, and both run today.** A claim that a
contract is kept is checkable here — so check it, and paste what you saw. An
unchecked claim is still an opinion and must be labelled as one.

```
uv run --with pyyaml ledger/checks/verify.py     # the ledger's own self-checks
uv run conformance/documents/run.py .            # a kit that reads the repository
```

`conformance/README.md` names every kit, what it judges, and how to run it —
the repository-reading kits take a path, the experience kits take the running
app's URL. Read it before you run one.

The documents kit's rule 9a reads the work queue, which is not a file in this tree — refresh its export with `uv run scripts/export-work-items.py --project converge --out docs/work-items.json` before you trust that rule's verdict. **That export is the documents kit's input, and nothing else's.** `ledger/checks/verify.py` reads the queue itself, live, through `amplifier-work-tracker`; when it cannot, it says so loudly and fails rather than passing on a snapshot nobody refreshed (converge-j0u5).

Rules for the check itself:

- **A check that cannot run reports "Can't check", never a pass.** Where a rule
  cannot yet be enforced, say so rather than pretend.
- **Do not weaken a check to make it green.** A failing check is information.
- **Drift is caught in both directions** — a clause quietly broken, and a clause
  quietly kept without anyone recording it.

## 4. What goes to the intent steward — and what does not

Exactly four kinds of call reach the steward:

1. **Ratify** a change to the vision or a contract.
2. **Irreversible or destructive** choices.
3. **Checks only a person or a device can perform.**
4. **Priority, or stop.**

Anything else that reaches them is a defect in how the work is set up — file it
as one. Do not ask permission for work already in your brief. Do not ask which
of two equivalent implementations to use. Do not narrate progress.

When you do need the steward, state the decision in one sentence, give the two
or three options with their consequences, and say which you recommend.

## 5. Finish honestly

- **Done means seen working**, not "the code is written" and not "the tests I
  wrote pass". Paste the output inline as you produce it.
- **Never claim a result you did not observe.** An unverified claim is worse
  than no claim, because the next session builds on it.
- **Stuck is a real answer.** Name the blocker and what you tried. A blocked
  lane that says so is worth more than a green one that guessed.
- **Stay in your lane.** Edit only the files your brief names. If another file
  needs a change, write that fact down for its owner rather than making it.
- **Keep evidence within permitted paths.** A worker can return artifacts from
  its own ignored worktree directory for the manager session to read and report.
  A filesystem access denial is never permission to retry the write through
  bash, Python, or a different tool.
- **Check manager-guidance changes with**
  `python3 -B -m pytest tests/test_manager_guidance.py evaluations/turnkey/tests`.
  These are guidance/fixture regressions, not proof of live manager behavior.
  Keep the numeric failed-attempt bound separate from healthy waiting, and
  verify a lane's terminal-report path is permitted before making it required.

## 6. App verification lessons

- A browser test must enter Home, select its explicitly configured manager,
  and wait for the workspace before testing a surface or closing its console.
  Hidden DOM nodes and an intentionally invisible console's child boxes are
  not rendered UI; keep whole-page width and visible-console assertions.
  Initial hosted-PR discovery must follow normal manager selection, not a
  test-only refresh hook that can conceal missing production wiring.
- `page.route()` does not intercept a service worker's own fetches. Prove that
  fault injection happened, using a server-side fault or an explicitly
  worker-free context. A failed read's Retry must actually restore the document.
- A missing controller alone is not proof that service workers are unavailable:
  first registration may still be pending. Preserve fail-closed confirmation
  for existing/in-flight workers. Draft collaboration must use two distinct
  authenticated people while decisions, locking, priority, steering and terminal
  control remain restricted to the registered steward.
- Check every asynchronous continuation that can change the selected review:
  authority, list, detail, POST completion and its awaited read-back. A guard
  before the first await does not protect an outcome painted after a second one.
- An installed-child test claiming "no configuration" needs an isolated HOME
  and configuration environment, not merely a stripped PYTHONPATH. Keep real
  production precedence and exact workspace-discovery assertions intact.