Department charters

What a charter is

A department installed from a blueprint has two layers, and they never merge:

• The blueprint is versioned, immutable, and shipped with Orgabot. It states the department's purpose, responsibilities, obligations, constraints, and the pitfalls it is meant to avoid.
• Your overlay is what your organization adds on top, and what your organization has chosen to suppress.

The charter you read is the two layers resolved together. Nothing your organization does edits the blueprint, which is why a change can always be rolled back: the original text never went anywhere.

Reading it

orgabot organization department charter show <org> <department>

Every line comes back marked with where it came from (inherited or local) and whether it is active or suppressed. A suppressed line is still listed. That is deliberate: a line you cannot see is one you cannot restore, and hiding a suppression makes it indistinguishable from a deletion.

Adding one line

For a single addition with no review step:

orgabot organization department charter add <org> <department> responsibility \
  "File the state return by the 20th"

This path can only ever add. It cannot suppress anything.

Changing several things, with a review

Anything that takes a line away goes through propose, review, apply. Preview it first:

orgabot organization department charter preview <org> <department> \
  "add:pitfall:Closing before the bank feed lands" \
  "disable:pitfall:Rushing the close"

Each change is kind:section:statement, where kind is add, disable, or restore. Only the first two colons separate the fields, so a statement may contain colons of its own.

The preview writes nothing and reports every refusal, not just the first. When any change in a proposal is refused, none of the others apply either: a partly applied charter is not a charter anybody approved.

Then propose it:

orgabot organization department charter propose <org> <department> \
  --why "our controller asked for it" \
  "disable:pitfall:Rushing the close"

Proposing applies nothing. It records the change, the reason, who asked, and a fingerprint of the charter it was written against.

Reviewing

orgabot organization department charter decide <org> <proposal-id> apply
orgabot organization department charter decide <org> <proposal-id> reject --note "not yet"

Applying is a second, separately authorized act, and the record says who made it. When the same actor proposed and decided, the record says selfReviewed, so an audit can find every change nobody else looked at rather than reading them all as reviewed.

Orgabot runs as one operator on one machine and has no user session, so it cannot make a second pair of eyes appear. Where you want one, name the deciding actor:

orgabot organization department charter decide <org> <proposal-id> apply --as <actor-id>

A decision is final. Re-deciding a proposal is refused.

When the charter moved

If the charter changed between the proposal and the decision (somebody else's change landed, or the blueprint was upgraded), applying is refused. The review was given to a charter that no longer exists. Preview the change again against the current one and propose it afresh. The stale proposal stays pending, so nothing is lost.

Rolling back

Every applied change is a numbered revision holding the whole charter overlay, not a patch.

orgabot organization department charter revert <org> <department> 1

Revision 1 is the baseline: the state the first governed change found, recorded before that change was applied. Reverting there restores what was actually in the charter at the time, including anything added through the additive path.

A rollback is recorded as a new revision; earlier revisions are kept. History is appended to, never rewritten, so an audit can still see that the reverted state was once live, and reverting a rollback restores what it replaced.

The two changes Orgabot refuses

These are refused by construction. There is no approval that unlocks them.

An inherited obligation or constraint cannot be suppressed. Those two sections are where a blueprint states the controls it requires: independent approval, separation of the preparer from the approver, thresholds. An overlay that could switch one off would be a control removal wearing the clothes of a documentation edit, and putting it behind an approval would only make erasing a required control something one busy person can click through. A statement your organization added to those sections is yours and can be suppressed; the blueprint's own are not negotiable.

A charter change cannot widen access. A charter is prose. Nothing on this path reads or writes a grant, a capability slot, or a connector, so approving a charter change is not, and cannot quietly become, approving an access change.

Moving to a newer blueprint version

A department records the version it was installed at, and Orgabot reads its charter at that version. A newer version shipping does not change what an installed department says: advancing is a decision you make, not a deployment side effect.

orgabot organization department blueprint upgrade preview <org> <department>
orgabot organization department blueprint upgrade apply <org> <department>
orgabot organization department blueprint upgrade list <org> <department>
orgabot organization department blueprint upgrade rollback <org> <upgrade-id>

The preview writes nothing and shows everything: statements added and removed, roles and connections and capabilities declared or no longer declared, access scopes that moved, and what happens to your own charter overlay.

The upgrade is not destructive

Installation created real roles, memberships, and capability slots that you have since staffed and granted. A newer blueprint dropping one of them does not delete anything. It is reported as no longer declared, and the record, its staffing, and its access stay exactly where they are. Retiring it is a separate decision through the paths that already govern that.

What happens to your own statements

Your additions and suppressions are reconciled against the new inherited text, and every change is reported rather than quietly tidied:

• An addition the new version now states itself is absorbed: the local copy is dropped so the same sentence is not rendered twice, once as yours and once as inherited.
• A suppression whose target no longer exists is orphaned and dropped. Keeping it would silently re-arm if the text ever came back.
• A suppression whose target became an inherited obligation or constraint is dropped too. A required control can never be suppressed, so the entry could not take effect, and leaving it would read like a decision that did.

Nothing is added, rewritten, or reordered. Your words stay your words.

Acknowledging a widened intent

An upgrade creates no connector, grant, or credential. But a new version can say the department should reach further: a new required connection, or a role it now describes as needing read access where it previously said none. That is a decision, so the upgrade is refused until you acknowledge it:

orgabot organization department blueprint upgrade apply <org> <department> --approve-access-intent

The acknowledgement covers the plan you were shown. It does not carry into the next upgrade, and it grants nothing: the actual access still goes through the normal least-privilege request.

Rolling back

The upgrade record keeps the previous version and your charter overlay verbatim, so a rollback restores what was there rather than reverse-computing it. An absorbed statement comes back as your local addition again. The rollback is recorded as its own entry, so history shows the upgrade happened and was undone.

A rollback is refused if the charter changed after the upgrade. The version pin says nothing about your overlay, so restoring the pre-upgrade one would silently discard whatever you added since. Revert those changes through the charter path first, then roll the version back.

Going back is only ever a rollback. --to an older version is refused, and points you at the recorded upgrade to undo: that is where the verbatim restore and the already-undone check live.

Note that charter revert reconciles too. Restoring an old charter revision across a blueprint upgrade would otherwise re-introduce exactly the local duplicates the upgrade removed, so the restore is reconciled against the version in force now and reports anything it could not bring back letter for letter.

In the dashboard

The department's charter panel shows the inherited blueprint, your additions, anything suppressed (struck through, with a button to propose restoring it), the proposals awaiting review, and the revision history with a rollback button for each. It also states how many inherited controls cannot be suppressed, because a missing control reads as an oversight while a stated refusal reads as the design.

The blueprint version panel above it names the version the department runs and whether a newer one is available. The full upgrade plan is fetched when you ask for a preview rather than on every refresh, and applying an upgrade that widens the stated access intent requires ticking the acknowledgement first.