Shaping and governing it

The genome is what the organism is made of: the application's source, the organization under dna/org (its org chart, its law, its purpose, its catalogs)…

The genome is what the organism is made of: the application’s source, the organization under dna/org (its org chart, its law, its purpose, its catalogs), and the vendored core in vendor/dna. Its one job is to be the only place the organism’s shape is written. The project owns it, and every change to it is a candidate someone reviews: the Leader inside the grant the Board wrote, the Board for everything else. It fails before anyone reviews: a candidate that does not check, or that breaks the law, is denied with the reason. It never holds a secret or the day’s work; those are the vault’s and memory’s.

This page is how you shape it, and how the organism is governed while you do.

They are ordinary Hale source. Edit one by hand, and hale check --matrix . checks the application and the organization, each against its own law (Constitutions). Or ask the organism for the change (hale dna task create), and it arrives as a candidate with its diffs and evidence for review (One task, end to end). Beside the genome, the record holds what the Board decided about it: the purpose ratified, the practices in force, who holds which position.

dna/org/purpose.hl is one sentence, and the first thing a reviewer sees about what the codebase is meant to be:

// dna/org/purpose.hl — the declared purpose (project-owned).
//
// The first governed workflow is the baseline review: the Review
// named `purpose` ratifies THIS text (its subject digest is the
// sha256 of PURPOSE). Change the text and the Review's digest
// together, or the verdict is refused as stale.

const PURPOSE: String = "refproj: keep the application correct, reviewable and explainable; every change is staged, reviewed, and never applied by the organism itself.";

fn purpose() -> String {
    return PURPOSE;
}

init writes it and proposes it for the Board in the same step; hale dna review lists it first, and hale dna review purpose approve --as <you> ratifies it (Getting started). Make it true of your project before you do: the Leader reads it every time it thinks.

dna/org/charter.hl is the Leader’s brief, a function returning text like purpose:

// dna/org/charter.hl — the leader's brief (project-owned; generated by
// `hale dna init`). The leader reads this, the purpose, the law and
// the ratified design before it plans an ask and before it decides a
// Review. Change it as you would any part of the organism: through a
// reviewed change.
// …
fn charter() -> String {
    return CHARTER;
}

The generated text makes the Leader the organism’s architect: it proposes and the Board decides. It tells it to say, first, what an ask is — whether it concerns the organism, an appendage, a product or a person’s job, which class of change, one change or several — and that a plan only splits and classifies, never widens what was asked. Before it plans an ask and before it decides a Review, the Leader composes its brief in this order: CHARTER, PURPOSE, the LAW as the genome holds it, and PRACTICES, the package of ratified practices for org when memory has any.

A practice is a named paragraph the Board ratifies: how work is done here. The Leader reads the ratified ones in its brief, a reviewer cites them, and nothing is in force until the Board says so.

init seeds three families as proposals, one Board Review each:

A mandate is a practice with a position to be bound to: what that position decides, what it may not, what it cites, how it writes and what it escalates, with the authority defaults derived from the law’s change classes (the charter refines them). The three in design are the Leader’s, the editor’s and the agent’s; init on a repository proposes one more with every position it proposes, in a repository or an application (mandate/<position>, listed under holes right after its position). Ratified, a mandate is bound to the position’s node, so whoever holds the position reads it in their hat. It is knowledge about a position, not a grant.

The first two operating practices are the two rules of the organism. hale dna review groups them:

$ hale dna review
32 pending review(s) of 32
  purpose — the declared purpose, the Board's to ratify first:
      k:3870910f5de4 — ratify the declared purpose?
      decide one with `hale dna review <id> …`, or all pending with `hale dna review purpose approve|reject`
  design — 11 seeded practice(s), each its own Review:
      k:05cecb18af4e — ratify the design practice `design/software-delivery`: For an appendage or a product: process boundaries first (what runs, fail…
      …
      decide one with `hale dna review <id> …`, or all pending with `hale dna review design approve|reject`
  operating — 7 seeded practice(s), each its own Review:
      k:33be310ddba8 — ratify the operating practice `operating/one-store-per-step`: a workflow step writes to exactly one store, by that store's one writer,…
      …
      decide one with `hale dna review <id> …`, or all pending with `hale dna review operating approve|reject`
  using — 7 seeded practice(s), each its own Review:
      k:8c1f6a4e2d70 — ratify the using practice `using/propose-review-ratify`: nothing is in force until the Board says so. A change to the organi…
      …
      decide one with `hale dna review <id> …`, or all pending with `hale dna review using approve|reject`
  holes — 6 hole(s) the repository leaves, each its own Review:
      k:d51a712f169e — ratify the position `board` under the purpose: it ratifies what this organization becomes
      …
      decide one with `hale dna review <id> …`, or all pending with `hale dna review holes approve|reject`
render one with `hale dna review <id>`; decide with `hale dna review <id> approve|revise|reject|abstain`

hale dna review design approve --as <you> decides each pending one in turn; the record still holds one verdict per practice. One of them does more than advise: operating/optimize-cadence, once ratified, declares the schedule of the optimize pass, once a day, convened by the Leader (Schedules). A different cadence is an amendment to that practice.

The using family is kept when init is run with --no-library: the library is the book and the spec, which the Board ratifies a family at a time (What a Work is told), and these are practices, one Review each. hale dna upgrade proposes each practice of the three families whose text changed, as it does the design, and the new toolchain’s library as new families.

A practice can come from anyone. When the same thing keeps going wrong, write down how it should go and say what prompted it:

hale dna practice propose acceptance/expense-receipt \
    --text "An expense closes with its receipt.
evidence: required" --because "three bills arrived without receipts"

The command writes a practice.requested row in your name (--as <who> names another); a running node relays it, and the organization proposes it with a Board Review of its own. With the organization running here, the command waits for that answer:

practice acceptance/expense-receipt proposed by alice as sha256:…; the Board ratifies it: `hale dna review k:… approve --authority board`

Roles are authorities, not identities: the person who proposed a practice may ratify it with the Board’s authority, and the record keeps who proposed and who decided. --supersedes <digest> names the version it replaces: ratifying the new one retires the old, declining it leaves the old in force. What an acceptance practice such as this one does to a person’s job is on One task, end to end.

hale dna practice lists every practice with its state (awaiting the Board, in force, declined, retired):

$ hale dna practice
practices: 16
  purpose sha256:38709 [awaiting the Board (k:3870910f5de4)] refproj: keep the application correct, reviewable and explainable; every change is staged, reviewed, and never applied by the organism itself.
  design/principles sha256:7b594 [awaiting the Board (k:7b5940a6bf3c)] Minimal structure: add a position only when it serves the whole; …
  …

Autonomy is a grant: written by the Board, held by a position, never widened by the position. In the generated organization the position is the Leader, and the grant is in dna/org/main.hl:

            boundary: dna::AutonomyBoundary {
                child: "refproj",
                grant: dna::Grant { child: "refproj", classes: "refactor docs", max_magnitude: 4, review: "pre" }
            },
            review_policy: dna::OrgPolicy { },

• classes — the change classes the Leader may decide.
• max_magnitude — a ceiling on the sum of the change’s magnitude vector (below). Past it, the change escalates whatever its class.
• review — "pre", "post", "sampled" or "audit". "pre" asks for a verdict before anything is applied; the others let a change with enough evidence be released, if the review policy does not block its class.

The grant is a constructor argument, not a runtime setting: no verb and no position widens it. Changing it is a change to the organization’s own seed, dna/org, which an organization change edits and the Board decides.

The Leader names a change’s class when it plans the ask. When its answer names none, the change is an application change of an appendage, and a change to the organism itself is class organization whatever the plan called it.

With the generated grant, an application change escalates to the Board. Widen it to "refactor docs application" in a reviewed commit and the Leader decides those under the magnitude too, with the record showing that it did.

Every candidate is measured from its semantic diff on a vector, never reduced to a confidence score, because a score would let evidence cancel a boundary it must never cancel (dna/core/types.hl):

Four are hard boundaries no grant covers: touching law, widening effects, crossing ownership, and an irreversible change with an external blast.

Evidence is counted, not rated: check_clean 1, verify_clean 1, tests_pass 2, replay_ok 2, rollback_rehearsed 2, and 2 per independent review. Before any of it counts, a candidate that does not check, or breaks a claim the fleet makes, is denied (mutation.deny); a seed with no Hale source to check is reviewed by a person whatever the grant.

Then dispose(grant, class, magnitude, evidence), a pure function, decides:

1. a hard boundary → review;
2. the class is not in the grant → escalate;
3. the sum exceeds max_magnitude → escalate;
4. the evidence is below the sum plus twice the novelty → stage;
5. review: "pre" → review; otherwise → release.

The disposition is a row (mutation.review, mutation.stage, mutation.escalate, mutation.release), so a reviewer sees why they were asked. Every disposition opens a Review, and only a release under a policy that does not block its class is applied before its verdict. The mechanical evidence adds up to 8, and a first change in a fresh lineage needs at least 9: without an independent review, nothing is released before its lineage has applied a change.

The review policy turns a disposition into a required authority. OrgPolicy requires the Board for a change that touches law, widens effects or crosses ownership, for the four Board classes, and for anything escalated; everything else inside the grant is the Leader’s, which answers with a model call and its reasoning in the record. Authorities are ranked board, leader, supervisor, reviewer, and a higher one satisfies a lower requirement. That authority is the fallback: when the positions of the graph that must sign a change are held, they sign it, and the Leader never decides it (The head and the face).

For small reversible refactors on a codebase with a history, swap the policy and loosen the grant for that class:

import "vendor/dna" as dna;

// Post-review for refactors: applied first, reviewed after.
fn trusted_policy() -> dna::PostReviewRefactors {
    return dna::PostReviewRefactors { };
}

fn trusted_boundary() -> dna::AutonomyBoundary {
    return dna::AutonomyBoundary {
        child: "refproj",
        grant: dna::Grant { child: "refproj", classes: "refactor", max_magnitude: 12, review: "post" }
    };
}

Use them as review_policy: trusted_policy() and boundary: trusted_boundary() on dna::Dna. PostReviewRefactors blocks every class but refactor. A refactor inside the grant, past no hard boundary and with enough evidence, is released: applied, expressed and observed first, and its Review follows with the question post-review: applied m4 (refactor): …?. A reviewer suffices to answer it. Reject it and the applied candidate is rolled back.

dna::Dna takes a second boundary, ceiling, which the generated organization leaves unset. With one, the Leader’s grant is read through it at every assessment: the classes both allow, the smaller magnitude, the stricter review. A grant written wider than its ceiling is refused in the record at birth (grant.refused) and bound by the ceiling.

A grant can also delegate money, and names nothing by default, so a grant that names no currency lets nothing be spent:

import "vendor/dna" as dna;

fn books_grant() -> dna::Grant {
    return dna::Grant {
        child: "books", classes: "docs", max_magnitude: 4, review: "pre",
        amounts: "USD 500.00",
        window_amounts: "USD 2000",
        window: "week",
        counterparties: "suppliers",
        routes: "operating-account",
        expires: 1798761600
    };
}

amounts is per operation, window_amounts per window, expires in unix seconds (0 never). The substrate reserves a spend against the grant before it is made (grant.reserved), and the law forbids any position from reaching a money effect except through it.

dna/org/law.hl is what no position may ever do, as the compiler sees it. The organization adopts it in its main (claims { adopt Org; }); the application keeps its own constitution:

group board = { dna::Board };
group leader = { dna::Leader };
group substrate = { dna::Dna };
group positions = { dna::Leader, dna::SourceEditor, dna::WorktreeTools, dna::LegRelay, dna::RelayReplay, dna::HumanWorkGateway, dna::ServicePerformer, dna::ScriptedPerformer };
group editors = { dna::SourceEditor, dna::WorktreeTools };
group knowledge = { dna::Knowledge, dna::MemoryKnowledge };
group credentials = { dna::CredentialSource, dna::HostedCredential };

constitution Org {
    // …
    apply_only_through_the_substrate: forbid reaches(positions, effects(genome_apply)) avoiding substrate;
    // …
    editors_never_commit: forbid reaches(editors, effects(repo_write));
    editors_never_touch_worktrees: forbid reaches(editors, effects(worktree_io));
    editors_never_apply: forbid reaches(editors, effects(genome_apply));
    editors_never_learn: forbid reaches(editors, knowledge);
    // …
    leader_never_commits: forbid reaches(leader, effects(repo_write)) avoiding substrate;
    leader_never_touches_worktrees: forbid reaches(leader, effects(worktree_io)) avoiding substrate;
    // Credentials are read from their source into sealed loci and never returned.
    credentials_sealed: require sealed(all credentials);
    // …
    money_only_through_the_substrate: forbid reaches(positions, effects(money)) avoiding substrate;
}

Nothing is applied except through the substrate’s gate after a settled Review; the editor reaches no git, no worktree gateway, no apply and no memory; the Leader decides and never commits; credentials stay sealed; money moves only through the substrate. These hold because the compiler checks them against the organization you actually wrote, following bus edges as well as calls.

The avoiding substrate clauses are what make “the Leader decides, the substrate acts” a checked fact. The Leader’s verdict does reach a repository, through the bus and dna::Dna, and only that way. Drop the clause from leader_never_commits and the check shows the path:

$ hale check dna/org
…/dna/org/law.hl:31:5: type error: claim `leader_never_commits` violated: `leader` reaches `effects(repo_write)` — witness: `dna::Leader::on_requested` -(publishes "dna::ReviewVerdict")-> `dna::Review::on_verdict` -(publishes "dna::ReviewSettled")-> `dna::Dna::on_review_settled` -> `dna::Dna::rollback_to_base` -> `dna::MutationGateway::rollback` -(dispatches dna::Repository.rollback)-> `dna::LocalGit::rollback`
…

Hand the editor a repository in main.hl and the build fails the same way, with the path as its witness, before anyone reviews anything. Add clauses of your own in the same block; the file asks you not to weaken these. A change that moves a claim is law_touched, a hard boundary, and the Board’s whatever its class. The vocabulary is Claims & the law; how an application states its own law, and how the two entrypoints are checked together, is Constitutions.

The Board and the Leader are loci in dna/org/main.hl. The positions people hold — a board, a reviewer of a part, a dev, an operator — are nodes of the organism’s graph, and who holds each is a holds edge, proposed and ratified like a practice (Memory and the record has the graph; hale dna show org reads it from memory). init proposes the positions its structure implies, for a repository (DNA, the building block) and for an application alike: the board, the application’s dev and reviewer, each as a proposal until the Board ratifies it with hale dna review holes approve. Before it does, there is nothing to fill:

$ hale dna fill board alice
hale dna: fill: `position:board` is no position or organization the record states or proposes

To seat people in the holes as init opens them, give init a pack that fills them (A pack at init): one verdict then ratifies the holes and their holders.

For a position the record states or proposes, ask the organization for a holder:

hale dna fill <position> <holder> [project] [--as <who>]

A position’s node can carry equipment, the API roles its holder is fitted with (equipment.roles): init derives them from the description the toolchain exports for a contract (spec/<Stem>.description.json, or hale check --api for the surfaces and streams an application serves; requires: [editor] lands on <app>/dev, requires: [reviewer] on <app>/reviewer) and fill prints them (equipment: editor), and hale dna show org lists them with the position’s mandate ({mandate: ratified; roles: editor}). Granting a token that carries them is not done by fill.

The CLI checks first: the holder must be a person the record knows (a row in their name, or an organization’s member) who has not retired, and never a name the organism writes as. The request is a hold.requested row in your name; the organization answers with a Board Review, listed by hale dna review under holds. Whoever holds the Board decides it, you included if that is you: a governance proposal is the one exception to the rule that a candidate’s author may not review it, since seating someone is not reviewing your own work (a change to the code still needs someone other than its author, even one the Board must approve):

proposed alice to hold position:board: the Board ratifies it as k:… (`hale dna review` lists it under `holds`)

A part’s reviewer and its dev are never the same holder. While you work alone (dna.trust = local) that is a warning; on a shared record it is refused, by the CLI and again where memory takes the ratified hold (hold.refused).

On a record several firms share, fill also says which firm owns a position and who belongs to a firm, both holds edges:

hale dna fill org/collections organization:north   # north owns org/collections
hale dna fill organization:north bob               # bob is north's member

A position has one owning organization, and a person belongs to one at most.

A position the graph does not state yet is opened through the organization, as a fill is:

hale dna position open api/steward --mandate "decides how the list's api reads; may not change the browser; cites the README's axioms; escalates a new surface to the Board" --under api --text "keeps the list's api"

The mandate is required: what the position decides, what it may not do, what it cites and what it escalates. --under names the part it unfolds from; a bare name is the seed, work part, position or process the graph states by that name, and a name the graph does not state is refused. The organization proposes the position’s node and its mandate as one Board Review, listed under positions:

proposed opening position:api/steward with its mandate: the Board ratifies it as k:… (`hale dna review` lists it under `positions`)

Ratifying it ratifies both. A name the graph already states, or one asked twice, is refused. Once it is ratified, hale dna fill gives it a holder.

A team is several positions and the people who hold them. Opening and filling each one is a Review apiece; a batch proposes them all as one, and the Board decides it once. Write the steps in a file:

# the api team
open api/dev | Decides: how the api is built. May not: sign its own changes. Cites: the contract. Escalates: to the Board.
open api/reviewer under position:api/dev | Decides: whether a change is ready. May not: write it. Cites: the change. Escalates: to the Board.
fill api/dev ada
fill api/reviewer bo

and read what it would do before proposing it:

hale dna apply team.batch --dry-run

+ position position:api/dev
+ mandate position:api/dev
+ position position:api/reviewer
+ mandate position:api/reviewer
+ holds position:api/dev ada
+ holds position:api/reviewer bo
6 line(s) added to the organization, 0 unchanged
nothing proposed (--dry-run)

A step may also take a holder out: vacate api/dev ada. On its own, hale dna vacate api/dev ada proposes that one step the same way; the position stays, and the hold goes once the Board ratifies it.

fill * ada fills every seat the batch leaves vacant: each position the organization would then state with a mandate and no holder (the batch’s own included). It is taken after every other step, so fill api/dev bo beside it keeps that seat for bo, and the Review lists the fills it stands for, one a seat.

Without --dry-run, apply proposes it as one Review, listed under changes; hale dna review changes approve ratifies every step of it together. A batch is checked whole before anything is written: a fill of a position nobody opens, a position opened twice, an under naming nothing, and the batch is refused with the step that is wrong. The order of the steps does not matter. If the organization changed before the Board decides, so that the batch no longer applies (one of its positions was opened meanwhile), approving it refuses it whole, and nothing of it lands: propose it again against the organization as it is.

The same file takes the operations that change a structure that exists:

assign api/reviewer reviews contract:spec/todo.md
merge api/reviewer into api/dev          # holders and reviews carry over, then api/reviewer closes
split api/dev into api/frontend api/backend
close ops/oncall
expose seed:billing as contract:spec/billing.md
depend seed:web on contract:spec/billing.md
externalize seed:billing                 # the part leaves; the organism depends on its contract
internalize contract:spec/billing.md as seed:billing

Each is a step like open or fill, so several of them are one Review, and the dry run shows what they add and take out: reviews lines for what a position signs, part lines for the parts, serves, consumes and outside lines for who meets at a contract. A split starts both new positions from the old one’s mandate, for the Board to amend. Closing a position takes its holders and reviews with it; the Board’s position is never closed.

A pack is a batch someone wrote once to be adopted many times, with blanks to fill: a dev team for a part, a small startup, a team that ships no code, a founder who holds every seat. Packs come from a nursery, a directory or a git repository with a nursery.toml index at its root; the toolchain carries one.

hale dna pack list
hale dna pack show dev-team --set part=api
hale dna pack apply dev-team --set part=api --set dev=ada --dry-run
hale dna pack apply dev-team --set part=api --set dev=ada

show prints the steps with the blanks filled; apply proposes them as one Review, named for the pack, like any batch. A pack may open positions, fill them and propose the practices its people work by (practice <name> | <text> is a batch step too). A line marked ? is left out when a blank it uses is not given, so --set dev=ada fills the dev’s seat and leaving out reviewer leaves that seat open. Another nursery is named with --from: a directory, or a git URL with #<rev> for the revision to read. A git nursery’s packs are adopted only once the Board trusts it: hale dna nursery add <url> proposes that, and hale dna nursery list shows the ones it trusts. The Review records which pack it was, its digest and where it came from.

hale dna pack retire dev-team undoes the latest adoption the Board ratified, as one more Review: the positions the pack opened close, the seats it filled and the reviews it assigned elsewhere are taken back, and its practices retire. Anything that has already gone is left out.

hale dna init --with <pack> proposes a pack in the same breath as the holes init opens, and the pack may fill those holes:

hale dna init . --with founder --set founder=riley --as riley
hale dna review all approve --as riley

The holes are proposals until the Board ratifies them, so a batch planned against the record alone finds no board to fill. init --with plans the pack on them instead: as though they were ratified. The batch names the pending Reviews it stands on, and the dry run says so:

+ holds position:board riley
+ holds position:api/dev riley
…
5 line(s) added to the organization, 0 taken out, 19 unchanged
planned on 10 pending Review(s) (k:c5a61bce0f4b, …): ratified after them, refused whole if any is not

review all approve decides holes before changes, so one verdict ratifies the holes and then the pack. A pack approved before its holes waits for them; if the Board declines one of them, the pack is refused whole as stale, and nothing of it lands. A pack that opens a position init already proposes is refused as soon as it is proposed. hale dna apply <file> --on-holes and hale dna pack apply … --on-holes plan the same way while init’s holes are still pending.

The same changes are commands of the head, for a UI or any program: every mutation is a head command, and the UI is a client of the generated surface. Commands::open_position, Commands::fill and Commands::apply_batch write the rows position open, fill and apply write, in the caller’s name; Commands::preview_batch is the dry run, as data. They need a seat (any position), and the organization answers them as it answers the CLI. The head has the shapes.

The org chart grows the way the code does: by a proposal the Board reviews. The signal is pressure, something seen more than once (Senses and reflexes has where it comes from):

hale dna pressure raise ingest "the ingest worker lags behind the queue every evening"
hale dna pressure

When one source has raised pressure three times (the concerns family’s appendage_threshold), the organization writes appendage.proposed — “an organ for <what> is proposed, not created” — and tells the Board. With initiative on, which is dna::Dna’s default, it goes one step further: it asks for an organization change to its own seed, whose objective is a dna::Leader beside the existing one in main.hl, named for what it oversees, with models: leader_models(). That candidate is verified like any other, recorded as appendage.candidate, and is the Board’s to decide. Applying it asks the host to rebuild and restart the organization with the position in it, and the window then judges the new organization. Set initiative: false and the proposal stays a note for the Board.

When the window judges an applied change, the record also gets pressure.remeasured: the fitness signals the proposal declared, and what the window saw.

Growth is also walked on a cadence: the optimize-walk workflow, whose schedule the practice operating/optimize-cadence declares, proposes one small change to the organization or records that the state is clean (Schedules).

After you upgrade hale, run:

hale dna upgrade

It rewrites vendor/dna from the binary and re-pins hale.lock:

vendor/dna: <n> file(s) rewritten, <m> unchanged; hale.lock pins toolchain <version>, embedded dna <digest>. dna/ untouched.

Your own files under dna/ stay yours. What upgrade does touch there is generated, or missing:

• It rewrites dna/org/workflows.hl to the current shape. Any definitions an older one held are named, for you to move into dna/org/own_workflows.hl.
• It rewrites dna/compose.yaml and dna/nats.conf, and draws the nerves’ passwords anew into the vault and dna/nats.secrets.conf.
• It creates what an older organization lacks: models.hl, work.hl, charter.hl, own_workflows.hl, dna/senses.yml.
• In dna/org/main.hl it rewrites only lines an older generator wrote exactly (the loop’s tick, the Board’s field, the retired owners field). Everything else it names as a note, with the line to write, and leaves to you.
• It proposes again each seeded practice whose text changed, each superseding the version in force, one Board Review each. A practice whose earlier replacement is still before the Board waits.
• With HALE_DNA_MEMORY_DSN_OWNER set, it applies memory’s schema for this toolchain (Memory and the record).