Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/devteam/governance/constitution.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Who decides what, how the supervisor earns the right to decide more, and the pri
| Fixing production incidents | owner, delegable | On the ladder as `incident-fix`, starting at "ask with a default" (the owner's choice: a fix is a reviewed, gated ticket, and an incident left alone costs more than a question). Scoped by the incident's severity, which the kit computes from its observations: `sev:low` (1 to 2) and `sev:high` (3 and 4), so the owner can let low-severity fixes go ahead and tell them. The default is what lets a fix go ahead without an answer, severe incidents included; it can't fire sooner than 15 minutes after the question. Where merging releases (settings `release: "merge"`), rung 3 of the class needs `release-production` at 3 too: merging a fix deploys it. Whoever makes the fix backs up first where a change could destroy anything, and holds for a human, as an ordinary Inbox question, when not confident in it (`process/worker.md`). Defaulted answers never count as agreement, and a verified fix is evidence, never trust; only the owner's answers move the class. A fix that regresses asks the owner: a wrong call, which they correct (the class drops to rung 1), or a sound call whose fix failed (a problem, no trust change). The kit recommends the second and never corrects. |
| Remediating production | owner, delegable | On the ladder as `production-remediation`, start 1, ceiling 2: the owner always sees a restart, a scale or a rollback coming, or it runs at its default (an outage question can carry `--deadline 15m`). Only scripts the owner lists in `remediations` (owner settings, `governance-edit`) run, each pinned by its blob sha, from main, once per decision, soon after the answer, each logged as an act; the answer names the remediation (and a rollback's release), and no standing rule covers the class. A rollback across a `production-migration` act since its target release is a one-way door, whatever `reversible` says: it needs the owner's own answer to a question with no default. |
| Allowing anything when a check fails | owner | The default is to deny. |
| A rule, gate or review standard; anything in `governance/` or `process/` | owner | The supervisor proposes with evidence. |
| A rule, gate or review standard; anything in `governance/` or `process/` | owner | The supervisor proposes with evidence. One exception: adding a new gate that runs only development-only tools, leaving every existing gate as it is, is the supervisor's (`gate-add`, §2 and §4). Changing or removing a gate stays the owner's `gate-change`. |
| Approving a design, a feature's graph, a ticket's spec and plan | supervisor | Each is an act in the log (`approve-spec`, `approve-plan`, `approve-feature-plan`). |
| Contract and ordering rulings; re-plans inside a feature; scheduling | supervisor | Cite the contract text, not convenience. |
| **The merge** | supervisor only | `devteam.mjs merge` is the merge word. Workers never merge. |
Expand Down Expand Up @@ -48,7 +48,7 @@ Some owner decisions can be handed to the supervisor a step at a time, as eviden
"incident-fix": { "ceiling": 3, "start": 2, "about": "open and run a ticket that fixes a production incident the sensors found" },
"production-remediation": { "ceiling": 2, "start": 1, "about": "restart, scale or roll back production with a reviewed remediation script" }
},
"constitutional": ["merge-word", "approve-feature-plan", "merge-chore", "worker-slots", "replan-within-feature", "add-ticket", "approve-spec", "approve-plan", "approve-design-change", "contract-ruling", "improvement-trial", "release-staging", "goal-readiness", "apply-default", "withdraw-question", "recovery", "carry-answer", "drain", "undrain", "goal-hold", "fleet-drain", "fleet-park", "fleet-undrain", "fleet-unpark", "registry-edit", "goal-impact", "orient-noise"],
"constitutional": ["merge-word", "approve-feature-plan", "merge-chore", "worker-slots", "replan-within-feature", "add-ticket", "approve-spec", "approve-plan", "approve-design-change", "contract-ruling", "improvement-trial", "release-staging", "goal-readiness", "apply-default", "withdraw-question", "recovery", "carry-answer", "drain", "undrain", "goal-hold", "fleet-drain", "fleet-park", "fleet-undrain", "fleet-unpark", "registry-edit", "goal-impact", "orient-noise", "gate-add"],
"owner_only": ["one-way-door", "check-override", "governance-edit", "process-edit", "gate-change", "goal-change", "strategy-change", "goal-met", "registry-attest", "new-dependency", "artifact-publish"],
"owner_rules": ["gate-change"],
"reasons": [
Expand All @@ -66,7 +66,7 @@ Some owner decisions can be handed to the supervisor a step at a time, as eviden
}
```

- **Three kinds of decision.** `classes` are the owner's decisions that can be delegated, each with a start rung and a ceiling. `constitutional` are the supervisor's own; they are logged as decisions or acts and a correction of one feeds knowledge, never authority. `owner_only` stay at "ask" whatever the evidence; of those, the classes in `owner_rules` (gate-change) may also be settled by a standing rule the owner gave themselves (`answer … --rule … --rule-scope class:<class>` from the dashboard, their terminal or chat), which then approves that class's calls and merges as an answer would. A project may lower a ceiling in its settings (`autonomy_ceilings`), never raise one; `validate` fails if it does. `registry-edit` (a url link added, changed or removed) is constitutional: the owner corrects it like any act, and a correction becomes a lesson scoped `link:<id>`, not a trust drop. If the owner wants trust semantics here later, it becomes a ladder class at start 3, ceiling 3. `goal-impact` (how much a goal matters, judged against the strategy) is constitutional too: the owner's correction sets the goal's impact to the value they give and becomes a lesson scoped `class:goal-impact`, not a trust drop. `orient-noise` (a recurring signal ruled noise, citing the observations it explains) is constitutional too: the owner corrects it like any call, a correction brings the signal back to Orient, and it moves no rung. `registry-attest`, the owner's yes that the registry lists everything the project depends on (`planning.md` §7), is owner_only: never defaulted. `artifact-publish`, the owner making a landed artifact readable by anyone from the cloud box or taking it down, is owner_only and the one class of act the owner writes (`artifact publish|unpublish`, which the gateway's confirm page runs): a record of what the owner did, never a call, so trust, decisions and corrections leave it out, and the log refuses it from anyone else. A preview (a running dev server the owner can open) is run state, approves nothing, and is never a record.
- **Three kinds of decision.** `classes` are the owner's decisions that can be delegated, each with a start rung and a ceiling. `constitutional` are the supervisor's own; they are logged as decisions or acts and a correction of one feeds knowledge, never authority. `owner_only` stay at "ask" whatever the evidence; of those, the classes in `owner_rules` (gate-change) may also be settled by a standing rule the owner gave themselves (`answer … --rule … --rule-scope class:<class>` from the dashboard, their terminal or chat), which then approves that class's calls and merges as an answer would. A project may lower a ceiling in its settings (`autonomy_ceilings`), never raise one; `validate` fails if it does. `registry-edit` (a url link added, changed or removed) is constitutional: the owner corrects it like any act, and a correction becomes a lesson scoped `link:<id>`, not a trust drop. If the owner wants trust semantics here later, it becomes a ladder class at start 3, ceiling 3. `goal-impact` (how much a goal matters, judged against the strategy) is constitutional too: the owner's correction sets the goal's impact to the value they give and becomes a lesson scoped `class:goal-impact`, not a trust drop. `orient-noise` (a recurring signal ruled noise, citing the observations it explains) is constitutional too: the owner corrects it like any call, a correction brings the signal back to Orient, and it moves no rung. `registry-attest`, the owner's yes that the registry lists everything the project depends on (`planning.md` §7), is owner_only: never defaulted. `artifact-publish`, the owner making a landed artifact readable by anyone from the cloud box or taking it down, is owner_only and the one class of act the owner writes (`artifact publish|unpublish`, which the gateway's confirm page runs): a record of what the owner did, never a call, so trust, decisions and corrections leave it out, and the log refuses it from anyone else. A preview (a running dev server the owner can open) is run state, approves nothing, and is never a record. `gate-add` (a new gate that runs only development-only tools, such as a linter, added to `settings.gates`) is constitutional too: the owner ruled that development-only tools don't need their approval (§4), and a new check only makes merges stricter. `merge` lands it without a question only from the supervisor's own chore PR, when it adds gates after main's and leaves every gate main has identical (field order included) and in order. A gate's command runs with the supervisor's own environment, like every gate's, so nothing checks that it runs only a development-only tool: that is the supervisor's judgement, and the act is what the owner reviews, and logs it as its own `gate-add` act; the owner corrects it like any act. Changing, loosening, reordering or removing a gate, and any change to `worktree_setup` or `worktree_files`, stays the owner's `gate-change`.
- **Why a question was asked.** Every question names its class and carries `why_asked`: the class's rung and ceiling, and reasons from the table. The dashboard shows it first.
- **Moving up.** Only through the owner. When answering, the owner can say how the next decision of that class is handled (ask, ask with a default, act and report), for the whole class or one scope; it applies at once, up to the ceiling. Or the supervisor asks a `trust` question when, of the last ten answered questions in the class, the owner went with its recommendation nine or more times (an answer equal to the recommendation; defaulted answers don't count); `ask --kind trust` refuses without that evidence, and the question carries those question ids and the uncorrected calls since the class last dropped. At most one open per class, two in all, asked at a retro. The supervisor never moves itself up.
- **Decisions and acts.** A judgment call is a `decision` line (`devteam.mjs decide`): what was decided, the options weighed, why, and the authority it rested on, snapshotted when it was made (the class's rung and ceiling, and the answer, default or standing rule it cites). Acts that carry it out cite it (`act --decision <d-id>`), take its class and stay within its refs. A decision made on the class's own rung lapses if the class drops after it. A mechanical act (a merge the gates passed, a worker started for a ready ticket) needs no decision line and is its own decision; so is every act logged before decisions existed.
Expand Down Expand Up @@ -95,7 +95,7 @@ A change is a one-way door if reverting it is expensive or impossible once shipp
- a migration that is not rollback-safe, or any destructive data change
- a public or cross-component contract change that removes or narrows behaviour
- a new persistence shape in an append-only or event-sourced store
- a new top-level dependency, runtime, datastore or vendor; a development-only tool (a linter, formatter, type checker or test helper that ships nothing to production) is not one
- a new top-level dependency, runtime, datastore or vendor; a development-only tool (a linter, formatter, type checker or test helper that ships nothing to production) is not one, and neither is a new gate that runs only such tools (`gate-add`, §2: the supervisor's call, recorded as its own act; changing or removing a gate stays the owner's `gate-change`)
- anything touching authentication, authorization, payments or PII
- anything the owner lists under one-way doors in the settings

Expand Down
Loading
Loading