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

package/docs/developing.md

@@ -34,10 +34,8 @@ test/                  one file per area
 module per screen under `js/views/`. `roster portal` serves them from `/assets`, reading each
 file per request. Editing a stylesheet and reloading the page is the whole edit loop.
 
-It was one 2,100-line HTML file until the CSS and the seven screens grew past the point where
-any of them could be found in it. Splitting it needed no bundler, because the browser resolves
-the module graph itself, and a bundler would have been a build step in a tool whose selling
-point is that it does not have one.
+No bundler, because the browser resolves the module graph itself, and a bundler would be a
+build step in a tool whose selling point is that it does not have one.
 
 ```
 templates/portal/
@@ -64,13 +62,12 @@ registers into at boot.
 
 ## The rule that matters
 
-**Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs` and
-`session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
+**Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs`,
+`inflight.mjs`, `run-record.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
 
-This has gone wrong once already. A fix went into `roster-ops/.github/workflows/session.yaml`
-instead of the template and nothing noticed, because the framework had not touched that file
-yet. `roster upgrade` now reports an edit to a framework-owned file whether or not anything has
-collided, and `roster upgrade --check` fails on it.
+A fix made in the tenant's copy goes unnoticed until the framework next touches that file, and
+then it is a conflict. So `roster upgrade` reports an edit to a framework-owned file whether or
+not anything has collided, and `roster upgrade --check` fails on it.
 
 ## Template classes
 
@@ -101,21 +98,19 @@ marker, or the leftover line is stranded.
 
 ## How the tests are meant to work
 
-Three habits, each of which came from a test that was passing vacuously.
+Three habits, each of which guards against a test that passes without testing anything.
 
-**Test the harness, not just the code.** The portal tests set a property on a dead object for
-several rounds, because the state they were driving was a top-level `let` in a classic script
-and not reachable as a global. The state is now an exported object, so the tests import the
-real modules under a DOM shim and there is nothing to get wrong.
+**Test the harness, not just the code.** The portal's state is an exported object, so the tests
+import the real modules under a DOM shim and drive the same state the page does. A test that
+sets a property on something the code never reads cannot fail.
 
-**Run it against reality.** The portal and doctor tests build from the live workspace rather
-than a fixture, so they break when real data grows a shape the code cannot handle. That is how
-the brain-comparison bug was found: every live workflow reported as absent, because filenames
-are templated and the comparison did not render them.
+**Run it against reality when you can.** The suite builds a temporary tenant by default, so it
+runs for anybody who clones the repo. Set `ROSTER_TEST_WORKSPACE=<dir>` to run the portal and
+doctor tests against a real workspace instead, which is how you catch real data growing a shape
+the code cannot handle: templated filenames, for instance, that a comparison forgot to render.
 
 **Mutation-test the invariants.** For anything asserting "this behaviour must not regress",
-break it deliberately and check the test fails. The workflow-template tests were verified this
-way, one mutation each.
+break it deliberately and check the test fails. If it does not, the assertion is decoration.
 
 ## Adding a command
 

package/docs/doctor-codes.md

@@ -33,7 +33,13 @@ ran at all.
 | `agent.config` | **fail.** The agent needs a config file of its own and it is missing, or still has a `FILL IN` in it. Nanocoder is the one preset that does: it is a client rather than a model, so without a provider it starts, finds nothing to call, and exits. |
 | `business` | **fail** if `org/business.md` is missing. Every prompt is composed on top of it. |
 | `business.stub` | `org/business.md` is still the questions it shipped with. Nothing errors; the agents just write competent work about a business that does not exist. |
-| `actions-access` | **fail** unless the ops repo is callable from the whole organisation. This is the "workflow not found" trap. See [manual steps](manual-steps.md#1-allow-the-ops-repos-workflow-to-be-called). |
+| `priorities` | No `org/priorities.md`. Nothing breaks; each staff member just picks its own direction. See [concepts](concepts.md#priorities). |
+| `priorities.stub` | `org/priorities.md` is still the stub `roster init` wrote. |
+| `actions-access` | **fail** unless the ops repo is callable from the whole organisation. This is the "workflow not found" trap. See [manual steps](manual-steps.md#what-roster-does-for-you). |
+| `workflows` | No workflow in the repo is failing run after run. Reported for the ops repo here, and for each brain repo under its staff member. |
+| `workflows.failing` | **fail.** A workflow that is not one of roster's callers has failed at least its last two runs, with the date it started. Skipped and cancelled runs are stepped over. This is the canary that goes red and stays red, because whatever would have said so broke with it. |
+| `budget` | Trailing 30-day spend against a `budget` in `org.yaml`, for the org here and for a staff member under their name. A warning when it is past, never a failure, and only read when a budget is set. Cost comes from each run's record, so it says how many runs it could price. See [cost](cost.md#budgets). |
+| `review-gate` | Off unless `review_gate: true` is in `org.yaml`, and then a note that it is off. When on, one per product repo. **fail** when nothing requires a pull request on its default branch, or a staff App can bypass the rule; a warning when a PR is required with no approving review, when the repo is private on GitHub Free (which can't enforce the rule), or when the settings cannot be read. See [security](security.md#the-review-gate). |
 | `upgrade` | The tenant is in sync with the framework. |
 | `upgrade.stale` | Generated files are behind. `roster upgrade --apply`. |
 | `upgrade.owned` | **fail.** A framework-owned file was edited in the tenant. Move the change upstream or the next upgrade reverts it. |
@@ -55,8 +61,10 @@ ran at all.
 | `callers.uses` | **fail.** A caller references no reusable workflow, or one in a different organisation. A private reusable workflow is only callable inside its own org. |
 | `callers.target` | **fail.** A caller points at a workflow file that is not in the ops repo. Fails at run time as "workflow not found". |
 | `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
-| `secrets` | Every secret the callers reference exists on the brain repo. Derived from the callers themselves, not a fixed list. |
+| `secrets` | Every secret the callers reference exists on the brain repo, or is an organisation secret shared with it. Derived from the callers themselves, not a fixed list. |
 | `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
+| `owned-labels` | Roster's own labels exist on the tracker: `decision`, `review`, `chore` and `keep-open`. Checked whatever `staff.yaml` declares, since the prompts apply them. The fix is the `gh label create` lines. |
+| `ask-kind` | An open issue assigned to a human has no ask kind, or more than one. Home sorts what needs you by kind, so an ask without one lands nowhere. |
 | `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
 | `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |
 | `runs` | A window of recent runs. See below. |

package/docs/export.md

@@ -35,6 +35,7 @@ that reads it gets the same view without reimplementing the memory grammar.
 | `statusIssue` | pinned issue number |
 | `schedule` | cron |
 | `mention` | what wakes them |
+| `icon` | the icon set by `icon:` in staff.yaml, if any |
 | `bots[]` | every App login, `[bot]` suffix stripped |
 | `soloBots[]` | identities unique to this staff member |
 | `sharedBots[]` | identities shared with others |
@@ -99,6 +100,7 @@ Only surfaces that exist on disk appear. A declared surface that is missing show
 |---|---|
 | `workflows[]` | filenames under `.github/workflows/` |
 | `hasCharter`, `hasManifest` | |
+| `charterStub` | `CHARTER.md` is absent or still the scaffold, the same test as doctor's `charter.stub` |
 | `missingSurfaces[]` | declared, not on disk |
 | `memoryBytes` | size of `INDEX.md` |
 | `notesBytes` | total size of `memory/notes/` |

package/docs/extending.md

@@ -24,8 +24,8 @@ there too.
 | `guardrails.md` | non-negotiables. What nobody may do, regardless of charter. |
 | `operating.md` | the autonomy contract: the boot ritual, the hand-off, decision rights. |
 
-This is the seam that pays. A concision rule here used to mean editing twelve files across two
-repositories; now it is one file, and the next morning everybody has it.
+This is the seam that pays. A rule written here is one file, and the next morning everybody
+has it.
 
 Keep the split honest. If a rule would be true of every staff member you will ever hire, it
 belongs here. If it is about one role, it belongs in that role's charter.

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 ---
 title: "Getting started"
-description: "Stand up an org and a first staff member, from the portal."
+description: "From nothing to a first staff member's first finished run, in the portal."
 sidebar_order: 1
 ---
 
@@ -10,113 +10,138 @@ sidebar_order: 1
 npx @nanocollective/roster
 ```
 
-Run that in an empty directory. There is nothing else to install and nothing to configure
-first: the page that opens is the setup screen, and it is the whole of setup.
+Run that in an empty directory. The page that opens is the setup screen, and it is the whole of
+setup. Every step below is also a command, listed at the end; they do the same work on the same
+files.
 
-You need two things before you start. `gh` [authenticated](https://cli.github.com), and a
-credential for whichever [coding agent](agents.md) you want to run. A GitHub organisation too,
-if you do not already have one: GitHub has no API for creating one, so that part happens on
-github.com.
+**How long it takes:** about an hour and a half to two hours to a first staff member's first
+finished run. Most of that is writing: what the business is, and the staff member's charter,
+each a conversation of twenty to thirty minutes with your own AI. The rest is about a dozen
+clicks and waiting for the run. Those two files are what make the staff worth running, so that
+hour is the part not to rush.
 
-Everything below is also a command, and the commands are in [the CLI
-reference](commands.md). They do the same work on the same files. This page is the portal
-because that is the shorter road, not because the terminal is second class.
+## Before you start
 
-## 1. Say which organisation
+- **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation. roster
+  does everything through your own `gh` and holds no token of its own.
+- **A GitHub organisation.** GitHub has no API for creating one, so if you need one, make it on
+  github.com first. Brains are private repos; on GitHub Free that works, with one difference in
+  step 5.
+- **A credential for your [coding agent](agents.md).** For Claude Code, run
+  `claude setup-token` and keep the token it prints for step 5.
 
-![The setup screen, asking which organisation and who runs it](images/setup-org.jpg)
+You only need [the three things in Concepts](concepts.md#the-three-things-you-need-to-know) to follow
+this. Everything else can wait.
 
-**It works out which of two things this is, and you do not have to know.** An organisation
-that does not run roster yet gets one stood up. One that already does gets *checked out* here
-instead, ops repo and every staff repo side by side, which is the shape the CI runner uses.
-That second case is how somebody joins an org a colleague set up, and offering both is how an
-org ends up with two `roster-ops` repos.
+## 1. Say which organisation, then read the plan
 
-The rest of the card is three answers: what the business is called, which GitHub login the
-agents answer to, and which coding agent runs a session. The agent is the one that is awkward
-to change later, because it decides which credential the repos need.
+![The setup screen, asking which organisation and who runs it](images/setup-org.jpg)
 
-## 2. Read the plan before anything exists
+Pick the organisation, say what the business is called and which coding agent runs a session.
+If the organisation already runs roster, the page offers to check it out here instead, which is
+how a second person joins.
 
 ![The plan: sixteen files and one private repo, listed before anything is written](images/setup-plan.jpg)
 
-Nothing has been created yet. **Show me the plan** lists every file and every repo it would
-make, and *Create it* is a separate button. This is the pattern everywhere in roster: the plan
-first, then the apply, and the same `initFiles` behind both the browser and the terminal so
-they cannot disagree about what a new tenant contains.
+**Show me the plan** lists every file and repo it would make; *Create it* is a separate button.
+That is the pattern everywhere in roster: the plan first, then the apply.
 
-After it applies you have `acme/roster-ops`: the org layer, the runner machinery, and a
-recorded merge base so later [upgrades](upgrading.md) are merges rather than copies.
+Creating it makes `<org>/roster-ops` and **sets its Actions access** so every repo in the org
+can call its workflow. Without that every run fails with "workflow not found". If GitHub refuses
+(it needs admin on the repo), the page says why and links to the setting to click instead.
 
-## 3. The Actions setting
+The rest of the steps stay on the same page. Reload it and the portal opens on **Getting
+started**, which keeps them in the sidebar until they are done, with hiring first. The sidebar
+counts them: three for the org, five for each staff member.
 
-The page asks for this next and deep-links to the exact settings page, because it is the one
-step whose failure is unrecognisable.
+## 2. Say what the business is
 
-**Settings → Actions → General on `roster-ops`, set access to "accessible from repositories in
-the organisation".** Skip it and every workflow later fails with "workflow not found", which
-reads like a typo and is not one.
+`org/business.md` ships as questions, and it is composed into the top of every prompt. An agent
+that cannot answer them writes plausible work about a business that does not exist.
 
-It is on [manual steps](manual-steps.md) with the others roster cannot do for you, and
-[Health](#7-health-then-one-run-by-hand) keeps asking until it is done.
+**Copy the prompt** puts a brief on your clipboard with every file it refers to inside it. Paste
+it into Claude, ChatGPT or anything else; it interviews you and hands back the file. Paste the
+reply into the box and you get a diff and a save button. See
+[the portal](portal.md#copy-a-prompt-paste-the-answer-back).
 
-## 4. Say what the business is
+Then `org/priorities.md`: what matters this month, ranked, and what is out of scope. A few
+lines, only you can write it, so it opens in place on the setup screen and saves the same way.
+See [concepts](concepts.md#priorities).
 
-`org/business.md` ships as questions, and it is composed into the top of every prompt. An agent
-that cannot answer them writes plausible work about a business that does not exist, so this
-comes before hiring anybody.
+## 3. Hire someone
+
+![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
 
-roster holds no model credential and cannot write it for you. What the portal does instead is
-both halves of the round trip: **Copy the prompt** puts a self-contained brief on your
-clipboard, and **paste the answer back** turns the reply into a file, with a diff and a button
-rather than a silent save. See [the portal](portal.md#copy-a-prompt-paste-the-answer-back).
+**Staff**, then pick a role: CTO, CMO, Support, or **Something else** with a name and a sentence
+about what they do. With nobody hired yet the Staff screen opens on the picker. The role fills
+in the handle, name and repo; they are under **Advanced** if you want to change them.
 
-## 5. Hire someone
+The role opens a numbered list: hire, create their GitHub App, write their charter, add your
+agent credential, run once now. The steps after the hire say *Hire first* until it is done.
 
-![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
+Step 1 says in one sentence what the hire creates and when they run. **Show details** has the
+full plan: the repo, the schedule and why, and the commits it will make **as you** in repos that
+already exist: each peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
+
+For the first hire there is nobody to copy an App name from, so **Advanced** also has two:
+this staff member's App, and the shared public App, filled in as `<org>-<handle>` and
+`<org>-robot`. Names are unique across GitHub, so keep the org prefix. The public one only
+matters if a product repo is public.
+
+Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
+product repo**.
+
+After **Hire** the list stays on the same staff member, now on step 2. Leave and come back later
+with **Finish setting up** on their card.
 
-**Staff → Hire someone.** Only the handle is required; everything else is copied from whoever
-is already here. You get the plan first: every file, every label, the schedule it chose and
-why, the peer wiring in both directions, and the steps it cannot do for you.
+## 4. Create the App, and confirm the install
 
-For the first hire in a new org there is nobody to copy an identity from, so the App names are
-asked for rather than guessed at. Later hires infer both.
+**Create the App**, in step 2. GitHub has no API that creates an App, so a tab opens and you
+confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
+The public App is offered too when a product repo is public.
 
-## 6. Give them an identity, and install it
+Then **Install it**. The install page opens with the organisation and every repo this staff
+member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
+the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
+asks a person.
 
-**GitHub App**, on the same card. There is no API that creates a GitHub App, so this runs the
-manifest flow: a manifest is posted to a settings page, you confirm, and GitHub hands back a
-one-time code. The private key is held in memory and written straight to a repository secret
-without ever touching disk.
+## 5. Write the charter
 
-**What it cannot do is install the App.** That is a grant of access to specific repositories
-and GitHub asks a human to choose them, which is correct. Grant it every tracker the staff
-member writes to, not only their own. This is the step that most often looks done and is not.
+Step 3. **Let an AI interview you** is the same copy-a-prompt loop as step 2 of this guide, aimed
+at `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
+[worked example](writing-a-charter.md#worked-examples) to model the shape on. **Start from the
+template** opens that example in an editor with your business's name in it; edit it so it fits
+before saving. **Edit the file** is the file as it is. roster never generates a charter, because
+a generated one makes exactly the generic agent this whole arrangement exists to avoid.
 
-Then **Write the charter**, which is the same copy-a-prompt loop as `business.md`, aimed at
-`CHARTER.md`. `hire` deliberately does not generate one: a generated charter produces exactly
-the generic agent this whole arrangement exists to avoid. It is the file that decides
-everything else, so it is worth the time. [Writing a charter](writing-a-charter.md).
+## 6. Store the agent credential, once
 
-## 7. Health, then one run by hand
+Step 4, shown only while no credential is stored. It is also on the card and on the setup
+screen. Paste the token from `claude setup-token` (or your agent's key; the box says where to
+get one). It is stored as one organisation secret, shared with the brain repos, and each later
+hire is added to it. It is not asked for again.
 
-**Health** is `roster doctor` on the page, every finding carrying the sentence that fixes it,
-split into what an agent can do and what only a person can. Work through it until the ids are
-gone.
+On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
+instead, and the page says so. It is still one paste now; a later hire needs it once more.
 
-Then trigger the daily workflow once from the Actions tab and read the log.
+## 7. Run it once
 
-**A workflow that has never run has proved nothing.** Not that the App is installed, not that
-the grant took, not that the secrets are right. `doctor` says `unproven` rather than `fine` for
-exactly this reason.
+**Run once now**, step 5, also on the card and on **Health**. It starts the daily workflow, follows it, and
+tells you how it ended, with the log.
+
+**A workflow that has never run has proved nothing**: not that the App is installed on the right
+repos, not that the secrets are right. Doctor reports it as `unproven` until one run has
+finished, and this is that run. If it fails, the result names the step, and
+[troubleshooting](troubleshooting.md) has what each failure usually means.
+
+Health is `roster doctor` on the page. Every finding carries the sentence that fixes it.
 
 ## 8. Now look at what you built
 
 ![A staff member's brain: memory sections, the facts in them, and the files](images/brain.jpg)
 
-**Brain** is that staff member's memory and files together, because they were always the same
-thing. **Prompt** is the text they are actually sent, composed by your own `compose.mjs`, with
-every layer it was made of and which repo each came from.
+**Brain** is that staff member's memory and files together. **Prompt** is the text they are
+actually sent, with every layer it was made of and which repo each came from.
 
 ![The Prompt screen: the composed text, and the layers behind it](images/prompt.jpg)
 
@@ -126,14 +151,39 @@ that*. The answer is always in one of those files.
 ![The Org screen, with org.yaml and every layer every staff member inherits](images/org.jpg)
 
 **Org** is the layer everybody inherits. Change `org/voice.md` once and it reaches every staff
-member on their next run, without regenerating anything.
+member on their next run.
+
+## From a terminal
+
+The same road, command by command. Each prints its plan and changes nothing without `--apply`.
+
+`roster` below means `npx @nanocollective/roster@latest`, unless you have installed it with
+`npm install -g @nanocollective/roster`.
+
+```bash
+roster init --org acme --apply        # the ops repo, and its Actions access
+roster brief discover                 # a brief for org/business.md
+roster brief priorities               # a brief for org/priorities.md
+roster hire cto --apply               # the brain, the wiring, the commits as you
+roster app cto --apply                # the App, its secrets, and a pre-ticked install link
+roster credential --apply             # the agent credential, once for the org
+roster brief charter cto              # the charter brief, with the CTO example
+roster run cto --apply                # one run, followed to the end
+```
+
+## What is still yours to do
+
+Five things, each because GitHub or the job itself needs a person: creating the organisation,
+confirming the App, confirming its install, getting the agent credential, and writing
+`business.md`, `priorities.md` and each charter. [Manual steps](manual-steps.md) has why for
+each.
 
 ## Where things go from here
 
-- **A second staff member**: Staff → Hire someone, then the App. Peer wiring happens both ways.
-- **Answering your agents**: [the Inbox](portal.md#inbox) is everything open across the org, and
-  the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work);
-  asking for a change to it is [one button](portal.md#asking-for-a-change).
+- **A second staff member**: Staff → Hire someone, then GitHub App, the charter and one run. The
+  credential is already there.
+- **Answering your agents**: [Home](portal.md#home) is what needs you, who is working and
+  what you asked for. Replies and merges go out as you.
 - **A framework update**: `roster upgrade`, or the same from the portal. See
   [upgrading](upgrading.md).
 - **The whole portal**, screen by screen: [the portal](portal.md).