Governance

One sentence decides most of this file: Two approvers — the design lead and the tech lead — with a monthly release note. Everything below is that sentence written out: who the two are and what each holds, what needs one signature and what needs both, how a decision is made and where it is recorded, how one is reopened, what happens when an approver is away, and how the group grows. The path a request takes to an answer is CONTRIBUTING.md; this file is who gives the answer.

It is written for a system that has one contributor today and is built for more than one. The architecture’s own conclusion is the design rule under every section here: with one person there is no governance to enforce, so the governance is generated over hand-maintained, tests over review, docs over memory — a rule that is a test cannot be forgotten, and a decision that is a dated line cannot be misremembered.

1. Who — the roles today

Role	Who	What they hold	Where they act
Owner and maintainer	The design lead	The system: every value, every component, every rule. The only contributor; the only person editing the Figma library, and the one who runs the export after a change — the design lead, on every change; sole owner of the @pepperui npm organisation	The Figma file Pepper UI; the repository through Claude Code’s sessions; the charter page; the Asana board, as its only member today
Second approver	The tech lead — head of tech	The second signature on a structural change — the tech lead can be the second signature on a new token or component without writing any of it; the Bitbucket workspace the repository sits in; the consumers they own, the site and MAFO, which take a change only as a change request	The repository (a pull request’s approval), the Asana card (a comment, once they are on the board — §9), the change requests in artifacts/change-requests/
Claude Code	the builder, under instruction	Works the plan in its order and never the calendar — stop re-litigating the timeline; every unit ends with a commit and a push to main, and a wrong commit is a revert; decides on the way when a unit needs a decision and marks it vetoable (§3); never publishes — a publish is the design lead’s action; never writes to a consumer; never reopens a rule of the design lead’s — such a rule is not vetoable by me (it is their own working rule)	The repository, the Figma file when the design lead has it open for a write, the Asana board’s unit tasks
Consumer owners	The tech lead (the site, MAFO); the design lead (the deck tool, the decks)	Whether and when their product takes a change. Nothing is connected to a live consumer. Every proof is built on a copy — the system proposes, in a pilot copy and a change request; the owner disposes	Their own repositories, on their own schedule
Anyone at Mobupps	—	A request, and an answer to it	The request form, which lands in the board’s Intake · requests from anyone section
Stakeholders	the owners of the products the system reaches, and the people who make its decks and pages — named per direction on the request’s card	A say on a direction before the two approvers decide (§2). What they said is recorded on the card and named in the decision; the two approvers still sign	The request’s card; the release note’s replies (§6)

2. What needs whose decision

The line: a structural change gets a second opinion. So:

The decision	Who decides	How it is recorded
A new token, a new component, a rename or a removal — anything that changes what the system has or what a name means	both approvers	a D-number in docs/03_DECISIONS.md; the second signature is a comment on the request’s card or an approval on the pull request
A fix within an existing component’s own values; a documentation gap	one approver	the session-log row that carries the fix, and the answer on the card
A write to the Figma library Pepper UI	The design lead — the only person in Figma, and the two older files are frozen	the audit run after every session that touches Figma and at every milestone close, filed in artifacts/audit/
A publish — the npm packages, the Figma library — and a tag or a release	The design lead, and it is their action, never Claude’s; the cadence itself is RELEASING.md	the changelog page reads the tags; the release note (§6) announces them
A change to a consumer	its owner	a change request in artifacts/change-requests/, with the evidence and how to verify it
The bar for a component — The bar for a component. No thin components, ever — and the plan’s order and dates	The design lead alone; the rule is do not renegotiate quality to protect a date	a new D-number superseding the old, never an edit to it (§4)
A principle	The design lead	docs/07_PRINCIPLES.md
The instrument a number is measured with — scripts/audit.py, the contrast matrix’s floors, the audit rubric	The design lead — a change to audit.py is a change to the instrument the baseline was measured with, and the design lead’s	a D-number, and the reading before and after it stated
A working rule of the design lead’s own — how sessions open, what is asked and what is not	The design lead; not vetoable by Claude	a D-number quoting their words
A direction the system takes — a new surface or product joining it, a deliverable struck or added, a change that alters what managers make with it	both approvers, after the stakeholders it reaches have been heard — vetoable: The design lead may sharpen what counts as a direction	a D-number that names who was heard and what they said, beside the two signatures
Adding an approver or a contributor	both approvers (§8)	a D-number naming the person and what they hold

3. How a decision is made, and where it lives

Every decision is a numbered entry in docs/03_DECISIONS.md in one shape — context → options → recommendation → status — with its date and its why, and every number in it cites the file it came from. There are three ways an entry comes to exist:

1. A question put to the design lead, with the options and a recommendation. Where it is put depends on its size: the charter page for a decision that should sit beside the others they have answered — scripts/charter.sh serves artifacts/charter-offline.html on 127.0.0.1 only, and their answers land in artifacts/answers.json; the Next actions for the design lead list in docs/06_PROGRESS.md for the smaller ones; the session itself when they are at the keyboard. Their answer is recorded in the entry.
2. A decision made on the way. A unit that cannot finish without a decision does not stop for one: Claude decides, records it the same day, marks the entry vetoable and names in Next actions exactly what is vetoable and what it would cost to change. The design lead confirms or vetoes when they read it — the charter page carries a veto item for the ones that deserve one (with the answer keep), and the entry then gains a dated Confirmed by the design lead line. A vetoable decision is in force from the day it is made; a veto reverts it, and the reversal is recorded (§4).
3. A rule of the design lead’s own, stated by them about how the work is done — recorded as theirs, and not vetoable by the builder.

What makes an entry finished is the same test the plan applies to a unit: someone other than you could verify it without asking you a question. A decision that cannot be checked against a file is not yet a decision; it is a memory.

4. How a decision is reopened

• By a new entry, never by editing the old one. A decision that no longer holds is superseded by a new D-number that names it — and the old entry stays where it is, struck and dated where it is wrong. The rule is CLAUDE.md §Mistakes stay visible: correct it in place with the error kept and dated. A decision log that quietly improves is worth nothing, because nobody can tell what was decided when.
• Who may reopen what. A decision of the design lead’s — the design lead. A vetoable decision of Claude’s — the design lead, at any time; Claude, only when the next unit shows it wrong, and then with the new entry stating the reason and the cost. The bar and the plan’s order — the design lead alone. A decision both approvers signed — both again.
• A requester who was declined. The answer Declined names the principle or the decision a request contradicts. To reopen it, the requester — or an approver on their behalf — writes the case as a proposal: the decision by number, what has changed since it was made, and what the change would cost the consumers that read the value. Both approvers answer it, and the outcome is a new entry either way: superseded, or confirmed with the date and the reason it still holds. A request cannot reopen a decision by being repeated; it can by bringing what the original entry did not have.
• A finding is not a re-score. The audit ritual closes a finding by the work, never by changing the number; a rubric or an instrument changes only by §2’s last rows.

5. When an approver is away

Two approvers exist so that the system does not stop entirely when the design lead is away, so the two cases are written down rather than improvised:

• the design lead away. No Figma write and no publish happen — nobody else edits the library, and a publish is their action. The repository holds by itself: every output is generated from its source and npm test fails on drift, so nothing decays for want of attention. Requests still get their first answer inside the promise: The tech lead may answer Exists, Declined or Question alone, and sign a fix alone; a Queued that needs a new row waits for the first working day back, and the answer says so.
• the tech lead away. A structural change may be decided by the design lead alone and built, marked in its entry awaiting the second signature; it is listed as such in the next monthly release note (§6), and the tech lead confirms or reopens it (§4) on their return. The second signature is a second opinion, not a lock on the first — the point is that a structural change is seen by two people, and the note guarantees it is.

6. The rhythm — when decisions are made and told

• Every unit — the session ritual in docs/06_PROGRESS.md: the box ticked, the scoreboard recounted, a session-log row, the Asana task, a commit and a push. A decision made in the unit is in docs/03_DECISIONS.md the same day.
• Every Figma write — the audit run, its score on the roadmap page.
• Every two weeks — the sprint review note on the Asana board.
• Monthly — monthly, a release note to managers: what shipped, what was decided, what is awaiting a second signature, and the requests answered that month with the time they took. The release cadence — what a version means, when a minor ships, what carries a migration note — is RELEASING.md, this file’s companion.

7. Boundaries — what governance here never reaches

• A consumer’s code. Nothing is connected to a live consumer. Every proof is built on a copy: a pilot lives in artifacts/pilots/, a change for a consumer is a change request, and the consumer’s owner decides. No signature here commits to the deck tool, the site or MAFO.
• The frozen Figma files. The Pepper Deck UI Kit and the site design file are read-only backups; a decision about them is a decision to read them, never to write.
• Credentials. They are held by the person, never by the repository: the npm account is the design lead’s with two-factor authentication on for publishing; the Bitbucket registry token and the Figma key live in ~/.claude.json on their machine — never in the repo, never in a file the repo can see; and .gitignore opens with the reason. Adding a contributor never means copying a credential; it means issuing them one of their own.

8. Growing the group

Two approvers for now, and this is how later works:

• A third approver is a decision of both current approvers, recorded as a D-number that names the person, what they hold and where they act (the table in §1 gains a row). Approvers are named people, never a role.
• A contributor — someone who builds rather than approves — gets repository access by invitation (*Repo access is needed only by contributors), works through pull requests that npm test and the pipeline must pass, and gets edit access to the Figma library only from the design lead, only once the audit ritual is part of how they work. Their first contributions are reviewed by an approver against the nine-point bar; the bar does not have a junior tier.
• The builder’s mandate is in CLAUDE.md and AGENTS.md: work the order, decide on the way and mark it vetoable, never publish, never touch a consumer, never invent a value. A second agent, or a second person running one, inherits the same mandate by reading the same files — which is why they are files.

9. What this file waits on

• the tech lead on the board. The Asana board is private with the design lead as its only member, so the second signature has nowhere to be written as a comment yet; one invitation fixes it, and the same setting that opens Intake to the workspace may do both.
• The release cadence — RELEASING.md — which §2 and §6 point at.
• The first monthly release note — the first time §6’s promise is kept.