@nanocollective/roster 0.1.0-alpha.5 → 0.1.0-alpha.50

package/docs/manual-steps.md

@@ -1,186 +1,157 @@
 ---
 title: "Manual steps"
-description: "Every human action, why it cannot be automated, and what breaks if you skip it."
+description: "What only a person can do, why, and what breaks if it is skipped."
 sidebar_order: 2
 ---
 
 # Manual steps
 
-Everything a human has to do, why it cannot be automated, and what it looks like when you skip
-it. This page exists because every item on it has cost somebody real time.
+What roster cannot do for you, why, and what it looks like when one is skipped. The
+[getting started](getting-started.md) path walks through each of these in order; this page is
+what to read when one of them bites.
 
-**The portal walks you through most of this now.** `roster` with no arguments opens a setup screen
-that deep-links item 1, runs items 2 and 3 for you as far as GitHub allows, and hands you a prompt
-for items 5 and 6. This page is still the *why*: it is what to read when one of them bites, and
-what to check when the page says something is not done.
-
-The portal's **Health** screen checks most of these, per staff member and for the org, with
-every finding carrying the sentence that fixes it. `roster doctor` prints the same from a
-terminal. Look after each step.
+**Health**, or `roster doctor`, checks each one it can, and every finding carries the sentence
+that fixes it.
 
 ---
 
-## 1. Allow the ops repo's workflow to be called
-
-**Do:** `<org>/roster-ops` -> Settings -> Actions -> General -> *Access* -> **Accessible from
-repositories in the organisation**. The setup screen links straight to that page.
+## 1. Create the organisation
 
-**Why not automated:** it is an organisation permission on a repository, and the API for it
-needs admin rights that a token created for a different purpose should not have. roster reads
-it and tells you, but setting it is one click and it is yours.
+**Do:** make it on github.com, if you do not have one.
 
-**If you skip it:** every caller fails with **"workflow not found"**. That reads like a typo in
-a path, or a missing file, or a bad branch reference. You will check all three. It is none of
-them, it is this.
-
-**Check:** Health, or `roster doctor`, reports `roster-ops is callable from the whole org`.
+**Why not automated:** GitHub has no API for creating an organisation.
 
 ---
 
-## 2. Create the GitHub App
+## 2. Confirm the GitHub App
 
-**Do:** the **GitHub App** button on a staff card in the portal, or `roster app <handle>` in a
-terminal. Either opens a browser, GitHub asks you to confirm, and you come back. Credentials go
-straight into the repository's secrets.
+**Do:** press **GitHub App** on a staff card, or run `roster app <handle> --apply`. A tab
+opens; confirm on GitHub. The App's id and private key go straight into the brain repo's
+secrets.
 
-**Why not fully automated:** there is no API that creates a GitHub App. The only route is the
-App Manifest flow: POST a manifest to a settings page, a human confirms, GitHub returns a
-one-time code. roster does everything either side of that confirmation.
+**Why not automated:** there is no API that creates a GitHub App. The only route is the App
+Manifest flow, where a person confirms on a GitHub page. roster does everything either side of
+that.
 
-**If you skip it:** the run fails at the token-minting step with a message about the app not
-existing.
+**If you skip it:** the run fails at the token-minting step, saying the App does not exist.
 
-**Note:** the private key is handed to `gh` on standard input. It is never written to a file,
-never passed on a command line, and never appears in the process table. If the secret write
-fails after the App is created, the key is gone: generate a new one from the App's settings
-page and set the secret by hand. roster tells you this if it happens.
+The private key is handed to `gh` on standard input. It is never written to a file, never on a
+command line, and never in the process table. If the secret write fails after the App is
+created, the key is gone: generate a new one from the App's settings page and set the secret by
+hand. roster says so if it happens.
 
 ---
 
-## 3. Install the App, and grant it the right repositories
-
-**Do:** open the URL the portal shows, or that `roster app` prints. Choose repositories.
+## 3. Confirm the App's install
 
-**Why not automated:** installing is a grant of access to specific repositories, and GitHub
-requires a human to choose them. This is the correct behaviour and should not be worked around.
+**Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
+with the organisation and the repos this staff member needs already selected: its brain, the
+ops repo (every run checks it out first), each peer's tracker, and the product repos. Check the
+list and confirm. Choosing **All repositories** instead also works.
 
-**Grant it on every tracker the staff member writes to**, not just their own. The token is
-minted organisation-wide, and a peer's board is where a brief lands. Both the portal and
-`roster app` say so.
+**Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
+a person to confirm it. That is correct and should not be worked around.
 
-**If you skip it, or under-grant it:** this is the trap that costs the most time, because of
-how it fails.
+The pre-selection uses `suggested_target_id` and `repository_ids[]` on the install page. GitHub's
+own links use them, but they are not in GitHub's documentation. If the ids cannot be read, or
+GitHub stops honouring them, the link is the plain install page and you tick the repos yourself;
+the portal and `roster app` both list which.
 
-> The API reports an App's **declaration** separately from an installation's **grant**.
-> `GET /apps/<slug>` will happily tell you the App exists and has `contents: write`. That says
-> nothing about whether it has been installed on the repository you care about. Two of our
-> Apps declare permissions they were never granted.
-
-So: **do not verify an installation by reading the API.** The only thing that proves the whole
-chain (App created, installed, granted, secrets right, workflow reachable) is a run that
-finished. `roster doctor` reads a window of recent runs for exactly this reason, and reports a
-workflow that has never run as **unproven** rather than as fine.
-
-**Check:** that staff member's Health screen, or `roster doctor <handle>`. Then trigger one run
-and look again.
+**If you under-grant it:** this is the trap that costs the most time, because the API reports an
+App's **declaration** separately from an installation's **grant**. `GET /apps/<slug>` will say
+the App exists and has `contents: write` without saying whether it is installed on the repo you
+care about. So **do not verify an installation by reading the API**. Run it once (item 5).
 
 ---
 
-## 4. Set the agent's credential
+## 4. Get the agent's credential
 
-**Do:** put the coding agent's credential on each brain repo as a secret. The name follows the
-credential: `CLAUDE_CODE_OAUTH_TOKEN`, `CODEX_API_KEY`, and so on. See
-[choosing a coding agent](agents.md).
+**Do:** get a credential for your coding agent (`claude setup-token` for Claude Code; the others
+are in [choosing a coding agent](agents.md#1-the-credential-exists-and-you-have-it)) and paste it
+into **Agent credential**, or pipe it to `roster credential --apply`. It is stored once, as an
+organisation secret shared with the brain repos, and each hire adds its repo to it.
 
 **Why not automated:** it is your account's credential and roster has no way to obtain one.
 
+Where an org secret would not arrive, it goes on each brain repo instead and says why. On GitHub
+Free, org secrets do not reach private repos, and only an org owner can set one. Setting an org
+secret also needs the `admin:org` scope on your `gh` token; if it is missing, the credential goes
+on each repo and the output gives the command that adds the scope.
+
 **If you skip it:** the run fails immediately with `the caller passed no agent credential`.
-That check exists so it fails there rather than forty lines later inside the agent, after the
-checkouts have already happened.
 
-**Check:** Health, or `roster doctor`, lists the secrets each caller references and whether
-they exist.
+**Check:** Health, or `roster doctor`, lists the secrets each caller references and whether they
+exist, on the repo or shared from the org.
 
 ---
 
-## 5. Write `org/business.md`
+## 5. Watch the first run
 
-**Do:** the setup screen does both halves of this. **Copy the prompt** puts a brief on your
-clipboard with every file it refers to inlined, so a chat window with no filesystem is as useful
-as an agent standing in the repo; the box beneath it takes the reply, shows you a diff, and
-saves only when you press the button. `roster brief discover` prints the same brief for a
-terminal, and you can always just answer the questions in the file by hand.
+**Do:** **Run once now** on the staff card or on Health, or `roster run <handle> --apply`. It
+starts the daily workflow, follows it, and reports how it ended, with the log.
 
-Health reports `business.stub` while it is still the questions.
+**Why it is yours:** it is a real run. It does a day's work and costs what one does, so it is a
+button you press rather than something setup does behind your back.
 
-**Why not automated:** an agent that does not know the business writes work that is plausible
-and generic. That is worse than no work, because it takes longer to notice. This file is
-composed into the top of every prompt, every run.
-
-**If you skip it:** nothing errors. That is the problem. You get competent-looking output about
-a business that does not exist.
+**Why it matters:** the only thing that proves the whole chain (App created, installed, granted,
+secrets right, ops repo callable) is a run that finished. `roster doctor` reports a workflow
+that has never run as **unproven** rather than fine, and one finished run clears it.
 
 ---
 
-## 6. Write each staff member's `CHARTER.md`
+## 6. Write `org/business.md` and `org/priorities.md`
 
-**Do:** **Write the charter** on that staff member's card, which is the same copy-a-prompt,
-paste-the-answer-back round trip as item 5, aimed at `CHARTER.md`. The brief it copies carries
-the org layer, `business.md` and **the peers' charters**, because without those the model writes
-a second copy of whoever it was shown. `roster brief charter <handle>` prints the same brief, and
-[writing a charter](writing-a-charter.md) has the shape if you would rather write it yourself.
+**Do:** on the setup screen, **Copy the prompt** puts a brief on your clipboard with every file
+it refers to inside it; paste the reply back and you get a diff and a save button. `roster brief
+discover` prints the same brief. Then write `org/priorities.md`: a few ranked lines on what
+matters this month.
 
-**Why not automated:** same reason, one level down. The charter is what makes a staff member
-different from the others.
+Health reports `business.stub` and `priorities.stub` while either is still the stub.
 
-**If you skip it:** `charter` reports it as present, because the stub is a file. `charter.stub`
-is the finding that says nobody has answered it. The agent has no personality and produces
-whatever the shared layer implies.
+**Why not automated:** an agent that does not know the business writes work that is plausible
+and generic. That is worse than no work, because it takes longer to notice.
 
----
+**If you skip it:** nothing errors. That is the problem.
 
-## 7. Commit and push what roster wrote into other repos
+---
 
-**Do:** hiring writes a whole brain repo and pushes it, so this is mostly about `roster
-upgrade`, which writes into repos on disk and leaves them for you. Review, commit, push.
+## 7. Write each staff member's `CHARTER.md`
 
-Hiring from the Staff screen still edits the *other* staff members' manifests on disk to wire the
-peers both ways, and those are yours to commit.
+**Do:** **Write the charter** on that staff member's card, the same round trip as item 6. The
+brief carries the org layer, `business.md`, the peers' charters, and where the role matches one,
+a [worked example](writing-a-charter.md#worked-examples) to model the shape on. `roster brief
+charter <handle>` prints the same brief.
 
-**Why not automated:** roster does not commit on your behalf into repositories it did not
-create in that command. And **App tokens cannot push a change under `.github/workflows/` in any
-repository**, which is a GitHub restriction and not a configuration mistake. That is also why
-agents can never update their own workflows, and why upgrades are human-run by design.
+**Why not automated:** the charter is what makes a staff member different from the others, and
+a generated one is the generic agent this arrangement exists to avoid.
 
-**If you skip it:** the change exists locally and nowhere else. `roster upgrade` will report it
-as still pending next time, which is the intended behaviour.
+**If you skip it:** `charter.stub` says nobody has answered it, and the agent produces whatever
+the shared layer implies.
 
 ---
 
-## Order
+## 8. Commit what `roster upgrade` wrote
+
+**Do:** review, commit and push what `roster upgrade --apply` changed in the brain repos.
 
-For a new organisation:
+**Why not automated:** **App tokens cannot push a change under `.github/workflows/`**, in any
+repository. That is a GitHub restriction, and it is why agents never update their own workflows
+and upgrades are run by a person. Hiring commits its own changes as you, and lists them first.
 
-In the portal it is the screen you are looking at, in this order:
+**If you skip it:** the change exists locally and nowhere else, and `roster upgrade` reports it as
+pending next time.
 
-```
-the setup screen                         1 is deep-linked from it, and 5 is on it
-Staff -> Hire someone                    then 7
-GitHub App, on the new staff card        2, then 3
-Write the charter, on the same card      6
-                                         4 is yours: a secret on the brain repo
-Health                                   until the ids are gone
-```
+---
 
-From a terminal:
+## What roster does for you
 
-```
-roster init --org <org> --apply          # 1 applies here
-roster hire <handle> --apply             # then 7
-roster app <handle>                      # 2, then 3
-# 4, 5, 6
-roster doctor <handle>
-```
+Each of these is a step of a command, listed in its plan before it happens, and each falls back
+to telling you exactly what to click if GitHub refuses.
 
-Then trigger one run by hand before trusting the schedule. A workflow that has never run has
-proved nothing.
+| | |
+|---|---|
+| The ops repo's Actions access | `roster init --apply`, or **Set it for me** on the setup screen. Needs admin on the ops repo. Skipped, every caller fails with "workflow not found". |
+| Committing peer wiring | `roster hire --apply` commits and pushes each peer's `staff.yaml` and `org.yaml` as you. A push that fails is reported and left for you. |
+| Giving each new brain the credential | `roster hire --apply` adds the repo to the org secret. |
+| Choosing repos on the install page | pre-selected, as above. |
+| The review gate on product repos | `roster hire --apply` adds it where there is none. See [security](security.md#the-review-gate). |

package/docs/memory.md

@@ -16,8 +16,8 @@ memory/INDEX.md      one line per fact. Read in full at every boot.
 memory/notes/*.md    the argument behind a fact. Read only when that fact is in play.
 ```
 
-That split is the whole design. Boot context here went from about 52,000 words to about 6,000
-by making it, and the saving repeats on every run forever.
+That split is the whole design. Boot context here went from about 52,000 words to about 10,000
+today by making it, and the saving repeats on every run forever.
 
 ## The grammar
 
@@ -48,10 +48,27 @@ rumour.
 Rule 5 is the one that gets skipped and the one that matters. Everything else degrades slowly;
 this one degrades the boot cost of every future run.
 
+## Budgets
+
+Prose is advice, and an index nobody prunes grows past what a run can usefully read. So
+`roster lint` warns past three budgets:
+
+| Budget | Default | Rule |
+|---|---|---|
+| One fact's line | 400 characters | `too-long`, naming the fact |
+| `memory/INDEX.md` | 24KB | `index-too-big`, naming the three longest facts |
+| `log/decisions.md` | 24KB | `decisions-too-big`: roll older entries into `log/decisions/<YYYY-MM>.md` |
+
+Change them under `memory:` in [org.yaml](org-yaml.md#memory), or per staff member in
+[staff.yaml](staff-yaml.md#memory). The daily prompt tells a staff member to check its sizes at
+hand-off and make pruning that run's job when it is over.
+
 ## What does not go in memory
 
 - **Why something was decided.** That is `log/decisions.md`, and it is not boot context.
 - **How a thing works.** That is a draft or a strategy document.
+- **An idea not yet acted on.** That is one line in `strategy/ideas.md`, and it becomes an issue
+  only when it needs a ruling.
 - **What is outstanding.** That is the pinned status issue.
 
 Nothing is copied between them. Four places, four jobs, and a fact that appears in two of them
@@ -64,7 +81,8 @@ opens an issue in that staff member's own repository asking them to fix it, whic
 right move: they wrote it, and an issue on their tracker is a thing that wakes them.
 
 It catches: a missing `So:`, a duplicate slug, a note nothing links to, a link to a note that
-does not exist, an over-long line, a `[measured]` fact with no `n`, and an "updated:" chain.
+does not exist, an over-long line, a `[measured]` fact with no `n`, an "updated:" chain, and an
+index or decision log over its budget.
 
 The same checks, for a terminal or for CI:
 

package/docs/org-yaml.md

@@ -34,10 +34,13 @@ agent:
   permissions: full
 
 defaults:
-  model: claude-opus-5
+  model: claude-opus-5-5
   timeout_minutes: 90
   mention_timeout_minutes: 90
 
+budget: 300
+review_gate: true
+
 staff:
   - { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
   - { handle: cmo, dir: marketing, name: Chief Marketing Officer, schedule: "40 7 * * 1-5" }
@@ -58,6 +61,8 @@ repos:
 | `name` | yes | What the business is called, in prose. Appears in prompts. |
 | `ops_dir` | no | Directory name of the ops repo in the runner checkout. Defaults to `roster-ops`. |
 | `experiment_private` | no | Whether the fact that this org is agent-run is itself private. Read by the guardrails fragment. |
+| `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
+| `review_gate` | no | `true` to have GitHub require a reviewed pull request before anything merges into a product repo. Off by default, because private repos need a paid plan for it. See [security](security.md#the-review-gate). |
 
 ### `human` and `humans`
 
@@ -121,8 +126,23 @@ Fallbacks for staff members who do not set their own.
 | `model` | Model id passed to the agent. |
 | `timeout_minutes` | Ceiling on a daily session. `90` if unset. |
 | `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
+| `max_runs_per_day` | What a new hire's `max_runs_per_day` starts at. `6` when unset. |
 | `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
 
+### `memory`
+
+Budgets `roster lint` holds every staff member's memory to. All optional; a staff member's own
+[`memory:`](staff-yaml.md#memory) overrides these.
+
+```yaml
+memory:
+  max_fact_chars: 400     # one fact's line in memory/INDEX.md
+  max_index_kb: 24        # the whole index, read in full at every boot
+  max_decisions_kb: 24    # log/decisions.md
+```
+
+Over budget is a warning naming what to cut, never an error. See [memory](memory.md#budgets).
+
 ### `staff`
 
 The registry. One inline map per staff member. **This is the org's view of them**; the rest
@@ -134,10 +154,26 @@ lives in their own `staff.yaml`.
 | `dir` | no | Directory and repo name. Defaults to the handle. |
 | `name` | no | Role name in prose. |
 | `schedule` | no | Cron. Informational here; the caller workflow is what actually schedules. |
+| `budget` | no | USD over any trailing 30 days, for this staff member alone. |
 
 `roster hire` appends to this list. An empty list (`staff: []`) is valid and is what a fresh
 org has.
 
+### `budget`
+
+A number of dollars, on the org, on a staff entry, or both:
+
+```yaml
+budget: 300
+staff:
+  - { handle: cto, dir: technology, name: Chief Technology Officer, budget: 200 }
+```
+
+Spend over the trailing 30 days is added up from each run's record. Past a budget, `roster
+doctor` warns and the portal's Runs screen marks the total. **Nothing stops a run.** A cap that
+ends a session fails it after the work is done and committed, which is a false red rather than a
+saved penny; `timeout_minutes` is the real bound. See [cost](cost.md#budgets).
+
 ### `repos`
 
 Every repository the org owns, and what it is for.
@@ -159,7 +195,9 @@ Every repository the org owns, and what it is for.
 | `runner-plan.mjs` | `org`, `staff`, and each manifest's `works_in` and `peers` |
 | `agents.mjs` | `agent`, `staff` |
 | `roster hire` | all of it, plus every existing manifest |
-| `roster doctor` | all of it |
+| `roster doctor` | all of it, including `budget` |
+| `roster lint` | `staff`, `memory` |
+| `roster portal` | all of it; the Runs screen reads `budget` |
 
 ## Editing it