@nanocollective/roster 0.1.0-alpha.1

package/docs/concepts.md

@@ -0,0 +1,112 @@
+---
+title: "Concepts"
+description: "The ops repo, the brain, charters, manifests, surfaces and peers."
+sidebar_order: 3
+---
+
+# Concepts
+
+## The ops repo
+
+`<org>/roster-ops` holds two different kinds of thing, and the split matters.
+
+**`org/` is yours.** `business.md`, `voice.md`, `guardrails.md`, `operating.md`. This is the
+business truth and the shared half of every staff member's instructions. Edit it freely. A
+change here reaches everybody on their next run, which is the point: a concision rule that used
+to mean editing twelve files is now one file.
+
+**Everything else is machinery** and belongs to the framework: `compose.mjs`, `agents.mjs`,
+`runner-plan.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
+framework changes the same file, at which point your change is a conflict at best and silently
+reverted at worst. Fix machinery in the framework, then `roster upgrade`.
+
+`roster upgrade` enforces this distinction. It reports an edit to a framework-owned file even
+when nothing has collided yet, because "not broken yet" is the state a lost fix sits in.
+
+## The brain
+
+A staff member's repository *is* their memory. There is no database.
+
+| | |
+|---|---|
+| `CHARTER.md` | the personality. Hand written. Decides everything else. |
+| `staff.yaml` | the machine-readable half: handle, schedule, identities, peers, surfaces |
+| `memory/INDEX.md` | one line per fact, read in full at every boot |
+| `memory/notes/` | the argument behind a fact, read only when that fact is in play |
+| `log/decisions.md` | why things were decided. Not boot context. |
+| `.github/workflows/` | three callers, about forty lines each |
+
+## Charter and manifest
+
+Two halves of one thing. The charter is prose for the agent; the manifest is fields for the
+machinery. `roster lint` fails if they disagree.
+
+The charter is the only file roster refuses to generate. A generated charter produces a generic
+agent, and a generic agent produces work that is plausible, competent-looking and about nothing
+in particular.
+
+## Surfaces
+
+`staff.yaml` declares what a staff member keeps and how to render it:
+
+```yaml
+surfaces:
+  - { path: memory/,   render: memory }
+  - { path: assets/,   render: gallery }
+  - { path: data/,     render: table }
+  - { path: strategy/, render: doc }
+```
+
+This is how the portal renders a brain it has never seen. A CMO with brand assets and analytics
+exports declares `gallery` and `table`; nothing in the portal knows what a CMO is.
+
+## The composed prompt
+
+```
+org/operating.md + org/guardrails.md + org/voice.md + org/business.md
+                 + <staff>/CHARTER.md + prompts/<kind>.md
+```
+
+Built at run time by `compose.mjs` in the tenant's own repo. See it for yourself:
+
+```bash
+roster prompt cto --kind daily
+```
+
+`compose.mjs` is vendored into the tenant rather than imported from the framework. A run at
+07:00 must not depend on npm, on a network fetch, or on an organisation the tenant does not
+control.
+
+## Kinds of run
+
+| | |
+|---|---|
+| `daily` | the scheduled session. Boot, work, hand off. |
+| `mention` | `@handle` in a comment or a new issue body. A task, not a session. |
+| `pr-mention` | a review comment on the public product repo, forwarded in. |
+
+`mention` and `pr-mention` prompts refuse to compose without trigger context, because they are
+written for the comment that woke them. That is correct behaviour, not a bug.
+
+## Identities
+
+A staff member posts as a GitHub App, not as you. Usually two:
+
+- a **private** identity for their own trackers, unique to them
+- a **public** identity shared by everyone, for the product repo, deliberately anonymous
+
+The public one is shared on purpose. A bot opening a pull request on a public repo is
+unremarkable; a bot signing itself with a job title is a tell.
+
+## Peers
+
+Staff members write to each other. A peer entry carries the label *this* staff member uses when
+filing on *that* tracker, so it is not symmetric:
+
+```yaml
+# technology/staff.yaml
+peers:
+  - { handle: cmo, brain: acme/marketing, label: from-cto }
+```
+
+`from-cto` lives on `acme/marketing`, because that is where the CTO's asks land.

package/docs/cost.md

@@ -0,0 +1,61 @@
+---
+title: "Cost"
+description: "What an agent-run org spends, and on what."
+sidebar_order: 12
+---
+
+# Cost
+
+Three separate bills, and they behave differently.
+
+## The coding agent
+
+The largest by far, and the one that scales with how much work you ask for.
+
+A session's cost is roughly its length. Ours run 11 to 55 minutes of wall clock, and a longer
+session is a bigger bill as well as a slower one. The lever that matters is not the model
+setting, it is how much you ask a staff member to do each morning and how much context it has
+to read to start.
+
+That is why the memory system is shaped the way it is. Boot context here went from about 52,000
+words to about 6,000 by moving from a narrative status file to one line per fact. That is a
+direct, repeated saving on every run of every staff member.
+
+**Watch for sessions growing into their ceiling.** A run that gets killed at
+`timeout_minutes` has been paid for and produced nothing. `roster doctor` reports the ratio.
+
+## GitHub Actions minutes
+
+Real on private repositories, and easy to forget because it is metered per minute of runner
+time and every scheduled run consumes it whether or not the run was useful.
+
+Three things spend it more than you would expect:
+
+- **Timeouts.** A run killed at 90 minutes bills 90 minutes.
+- **Mention workflows.** Every comment on a tracker triggers a run, even ones the condition
+  gates out. Those are seconds each, but they are not free and they are numerous.
+- **`fetch-depth: 0`** on the brain checkout, which is deliberate (the agent reads its own
+  history) but grows with the repository.
+
+Public repositories are free, which is why the product-repo lane costs nothing.
+
+## GitHub Apps
+
+Free. There is no per-App or per-installation charge. The only cost here is the human minute
+it takes to install one.
+
+## What roster itself costs
+
+Nothing at run time. The framework is not a dependency of anything a tenant runs: the CLI runs
+on your machine when you ask it to, and the machinery is vendored into the tenant's own repo.
+
+## Keeping it down
+
+- **Prune memory.** Deleting is the maintenance. Every line in `memory/INDEX.md` is read at
+  every boot, by every run, forever.
+- **Do not raise a timeout to fix a slow session.** Find out why it grew. A ceiling that keeps
+  being raised is a session that has stopped fitting its job.
+- **Give a mention workflow a shorter ceiling than a daily one.** A focused task that runs for
+  an hour has gone wrong, and the ceiling is the only thing that stops it.
+- **Check the ratio, not the last run.** `roster doctor` reports how many of the last ten runs
+  succeeded. One bad run is noise; four is a bill.

package/docs/developing.md

@@ -0,0 +1,147 @@
+---
+title: "Working on roster itself"
+description: "Layout, template classes, and the rules that matter."
+sidebar_order: 22
+---
+
+# Working on roster itself
+
+```bash
+git clone <the framework> && cd roster && npm install
+npm test          # the whole suite
+npx tsc --noEmit  # typecheck
+```
+
+Tests are `node:test` run through `tsx`. There is no build step for development, and the portal
+has no build step at all.
+
+## Layout
+
+```
+src/cli.ts             command table and help
+src/commands/          one file per command
+src/lib/               shared: workspace, memory, render, merge, gh, templates, docs
+templates/ops/         what a tenant's ops repo is generated from
+templates/brain/       what a staff member's repo is generated from
+templates/portal/      the portal: a shell, css/, and js/ as ES modules
+docs/                  these pages
+test/                  one file per area
+```
+
+## The portal has no build step, on purpose
+
+`templates/portal/` is a plain `index.html`, one stylesheet per area under `css/`, and one ES
+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.
+
+```
+templates/portal/
+  index.html           the shell: <link>s, the sidebar's bones, one <script type="module">
+  css/base.css         tokens, reset, buttons, inputs, chips
+  css/layout.css       the frame: sidebar, main, tree-beside-viewer
+  css/<area>.css       markdown, brain, inbox, graph, diff, health
+  js/state.js          every screen's state in one object, and the URL that mirrors it
+  js/router.js         one indirection so a view can repaint without importing the shell
+  js/dom.js  api.js  md.js  refresh.js  icons.js
+  js/app.js            boot, the sidebar, dispatching a view into <main>
+  js/views/*.js        one per screen
+```
+
+`js/icons.js` holds two dozen [Lucide](https://lucide.dev) glyphs as inlined path data, ISC
+licensed. Vendored rather than fetched, because the portal is offline-first and an icon that
+needs the network is an icon that is sometimes a blank square. They take colour from
+`currentColor` and size from a `--ic` custom property, so a component styles them in CSS and
+never touches the SVG. Nothing in the UI should draw with a text character.
+
+Two rules keep the module graph a tree rather than a ring: **state lives in `state.js`**, and
+**a view never imports `app.js`**. It calls `render()` from `router.js`, which the shell
+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`.
+
+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.
+
+## Template classes
+
+Ownership decides what `roster upgrade` does, and getting it wrong is how you either lose
+somebody's work or never ship an improvement.
+
+| Where | Class | Upgrade behaviour |
+|---|---|---|
+| `templates/ops/org/`, `prompts/` | `seeded` | three-way merge |
+| `templates/ops/` everything else | `managed` | reported even when nothing collided |
+| `templates/brain/.github/workflows/` | `generated` | regenerated wholesale |
+| `templates/brain/` everything else | `scaffold` | added when new, never rewritten |
+
+`scaffold` is the important one. A working agent rewrites `CHARTER.md` and `memory/INDEX.md`
+beyond recognition, and merging a template into that would be vandalism.
+
+## Tokens in brain templates
+
+`templates/brain/` is rendered with `%%TOKEN%%` substitution, **including filenames**, which is
+why the callers are `%%STAFF%%-daily.yaml`.
+
+An unfilled token throws rather than being left on the page. A workflow containing a literal
+`%%SCHEDULE%%` is a file GitHub accepts and never runs.
+
+A line containing `%%TOKENS%%` is a note to whoever reads the template and is dropped on
+render, along with the `#` separator above it. Every line of a multi-line note needs the
+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.
+
+**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.
+
+**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.
+
+**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.
+
+## Adding a command
+
+1. `src/commands/<name>.ts`, exporting `<name>Command` and `<name>Help`.
+2. Add both to the tables in `src/cli.ts`.
+3. Document it in `docs/commands.md`. **A test fails if you do not**, and another fails if the
+   flags you document are not ones the parser accepts.
+
+Prefer plan-then-apply. Every command that changes anything prints what it would do and needs
+`--apply`, and that is the convention that makes them safe to run in someone else's org.
+
+## Adding an agent preset
+
+`templates/ops/agents.mjs`. Three fields: `install`, `run`, `token_env`. The run command reads
+the prompt from `$AGENT_PROMPT_FILE`.
+
+**Read the flags off the tool's own help or docs.** Every preset that ships was verified that
+way, and the tests say which flag exists for which reason. `docs/agents.md` has to quote the
+same install line, and a test checks it does.
+
+## Before pushing anything that touches a live org
+
+```bash
+roster prompt cto --kind daily     # composed prompt, byte for byte
+roster upgrade                     # what would change, and where
+roster doctor                      # is it still wired up
+```
+
+A prompt change with no visible diff in the composed output is the only kind that is safe.

package/docs/doctor-codes.md

@@ -0,0 +1,74 @@
+---
+title: "doctor codes"
+description: "Every finding roster doctor can emit, what it means, and what to do."
+sidebar_order: 19
+---
+
+# doctor codes
+
+Every finding `roster doctor` can emit. Each carries a stable `id`, which is what
+`--json` reports and what to quote in an issue.
+
+```bash
+roster doctor --json | jq '.findings[] | select(.level != "ok")'
+```
+
+Levels: `fail` sets exit code 1, `warn` does not, `ok` is reported so you can see the check
+ran at all.
+
+## Workspace
+
+| id | Means |
+|---|---|
+| `gh` | Whether `gh` is installed and authenticated. A warning here means every network check was skipped, not that anything is wrong. |
+| `org.yaml` | The org manifest parsed, and how much it declares. |
+| `human` | **fail.** `org.yaml` has no `human.github`. The mention callers gate on that login, so nothing can wake an agent. |
+| `repo` | Every repo in `org.yaml` is reachable. A failure means it does not exist or your `gh` cannot see it. |
+| `repo.visibility` | A repo's real visibility disagrees with what `org.yaml` records. Cosmetic, but the posture it records is then fiction. |
+| `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). |
+| `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. |
+| `upgrade.blocked` | A file cannot be merged: either a conflict to resolve, or no recorded base. See [upgrading](upgrading.md). |
+
+## Per staff member
+
+| id | Means |
+|---|---|
+| `checkout` | **fail.** Their directory is not checked out beside the ops repo, so nothing else could be checked. |
+| `manifest` | **fail.** No `staff.yaml`, or it does not parse. `compose.mjs` reads a small strict YAML subset. |
+| `manifest.handle` | **fail.** `staff.yaml` and `org.yaml` disagree about the handle. The composer looks them up by the `org.yaml` one. |
+| `manifest.brain` | **fail.** No brain repo declared, so no secrets, labels or runs can be checked. |
+| `charter` | **fail** if `CHARTER.md` is absent. Note that a stub counts as present: this checks the file exists, not that it says anything. |
+| `charter.stub` | `CHARTER.md` exists but is still the scaffold. `charter` above only checks the file is there, which a stub is. |
+| `memory` | `memory/INDEX.md` parses, and how many facts and notes it holds. |
+| `compose` | All three prompts compose. A failure names the kind and the placeholder. |
+| `callers` | Three caller workflows exist. |
+| `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. |
+| `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
+| `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. |
+| `runs.timeout` | **fail.** Runs were killed at a ceiling. |
+| `runs.cancelled` | Runs were cancelled short of any ceiling, with their durations. |
+
+## Reading `runs`
+
+This is the only check that proves the whole chain works, so it is worth understanding.
+
+- **"has never run"** is a warning, not an `ok`. Nothing has exercised the App grant or the
+  secrets, so nothing is known.
+- **"all gated out before doing anything"** means every recent trigger was `skipped`. That is
+  normal for a mention workflow, but it means the credentials are still unproven.
+- **"ran to a Nm ceiling and were killed"** is a timeout. GitHub reports those as `cancelled`,
+  so doctor identifies them by duration. If the ceiling it names differs from the one the
+  caller sets today, it says so: those runs happened under the old setting.
+- **`N/M recent runs succeeded`** is the healthy form.
+
+A skipped run is never counted as a failure. Most of a mention workflow's history is skipped
+runs, and counting them would bury the real ones.

package/docs/export.md

@@ -0,0 +1,113 @@
+---
+title: "roster export reference"
+description: "The JSON shape, field by field."
+sidebar_order: 18
+---
+
+# `roster export` reference
+
+The whole org as one JSON document.
+
+```bash
+roster export --out org.json
+```
+
+Rendering is decoupled from parsing on purpose: the portal reads this shape, so anything else
+that reads it gets the same view without reimplementing the memory grammar.
+
+## Top level
+
+| Field | |
+|---|---|
+| `org` | the GitHub organisation |
+| `name` | the business name |
+| `opsName` | the ops repo's directory, so a consumer can address `org.yaml` and `org/*.md` by path |
+| `human` | the `human` block from `org.yaml` |
+| `generatedAt` | ISO timestamp |
+| `staff[]` | one entry per staff member |
+
+## A staff member
+
+| Field | |
+|---|---|
+| `handle`, `name`, `dir`, `brain` | identity |
+| `statusIssue` | pinned issue number |
+| `schedule` | cron |
+| `mention` | what wakes them |
+| `bots[]` | every App login, `[bot]` suffix stripped |
+| `soloBots[]` | identities unique to this staff member |
+| `sharedBots[]` | identities shared with others |
+| `worksIn[]` | repos contributed to but not owned |
+| `peers[]` | `{ handle, brain, label }` |
+| `facts[]` | parsed memory |
+| `sections[]` | memory section names, in file order |
+| `notes[]` | filenames under `memory/notes/` |
+| `links[]` | the graph |
+| `problems[]` | lint findings |
+| `surfaces[]` | declared surfaces and their files |
+| `recentCommits[]` | last 25 |
+| `factsChanged[]` | facts added and removed recently |
+| `rig` | scaffolding health |
+
+The split between `soloBots` and `sharedBots` matters: a solo identity names one staff member,
+a shared one names only "one of them". Attributing work by author needs both.
+
+## `facts[]`
+
+| Field | |
+|---|---|
+| `slug` | the identifier, unique within a staff member |
+| `section` | the heading it sits under |
+| `statement` | the fact |
+| `consequence` | the `So:` clause |
+| `line` | line number in `INDEX.md` |
+| `raw` | the source line |
+
+## `links[]`
+
+| Field | |
+|---|---|
+| `from`, `to` | slug, note filename, issue reference or path |
+| `kind` | `note`, `wikilink`, `mention`, `issue` or `path` |
+| `inferred` | false when authored explicitly, true when derived |
+
+## `surfaces[]`
+
+| Field | |
+|---|---|
+| `path` | as declared in `staff.yaml` |
+| `render` | `memory`, `doc`, `gallery`, `table` or `code` |
+| `files[]` | `{ path, bytes, modified, ext }` |
+
+Only surfaces that exist on disk appear. A declared surface that is missing shows up in
+`rig.missingSurfaces` instead.
+
+## `problems[]`
+
+| Field | |
+|---|---|
+| `level` | `error` or `warning` |
+| `rule` | see [memory](memory.md) |
+| `message` | |
+| `line` | in `INDEX.md`, when there is one |
+| `slug` | the fact, when there is one |
+
+## `rig`
+
+| Field | |
+|---|---|
+| `workflows[]` | filenames under `.github/workflows/` |
+| `hasCharter`, `hasManifest` | |
+| `missingSurfaces[]` | declared, not on disk |
+| `memoryBytes` | size of `INDEX.md` |
+| `notesBytes` | total size of `memory/notes/` |
+| `lastCommit` | `{ sha, date, subject, author }` |
+| `lastMemoryCommit` | the last commit touching `memory/` |
+
+`lastMemoryCommit` is the one worth watching. A staff member committing daily but not touching
+memory in a fortnight has stopped learning anything.
+
+## Stability
+
+This shape is not versioned and will change as the portal does. It is a convenience for reading
+your own org, not an API to build a product on.

package/docs/extending.md

@@ -0,0 +1,97 @@
+---
+title: "Extending it"
+description: "The four seams, and which one to reach for."
+sidebar_order: 6
+---
+
+# Extending it for your business
+
+Four seams, in the order you are likely to reach for them.
+
+## 1. Change how everyone works
+
+Edit `org/*.md` in the ops repo. It reaches every staff member on their next run.
+
+| File | For |
+|---|---|
+| `business.md` | what the business is. The one everything else is downstream of. |
+| `voice.md` | house style. How anything anyone writes should read. |
+| `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.
+
+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.
+
+## 2. Change what a staff member is sent
+
+`prompts/` holds the fragments `compose.mjs` assembles.
+
+```
+_identity.md    who you are posting as, and where
+_paths.md       where things are in the runner checkout
+daily.md        the scheduled session
+mention.md      a focused task from a comment
+pr-mention.md   a review comment forwarded from the product repo
+```
+
+The syntax is small on purpose: `{{ path.to.value }}`, `{{> partial.md }}`,
+`{{>? optional.md }}` and `{{#if path}}...{{/if}}`. Conditionals do not nest.
+
+**Guard anything that assumes a manifest field.** `{{staff.product.repo}}` is empty for a staff
+member whose `works_in` is empty, and an unresolved placeholder is a hard error rather than a
+blank. Wrap it:
+
+```
+{{#if staff.product}}
+... anything that mentions the product repo ...
+{{/if}}
+```
+
+A staff member can override a fragment for themselves. `{{>? staff:prompts/work.md}}` in
+`daily.md` renders `prompts/work.md` from their own brain repo if it exists, and nothing if it
+does not. That is how one role gets a different working ritual without changing anybody else's.
+
+See what you actually built:
+
+```bash
+roster prompt cto --kind daily
+```
+
+## 3. Give a role something new to keep
+
+Declare a surface in `staff.yaml`:
+
+```yaml
+surfaces:
+  - { path: assets/, render: gallery }
+  - { path: data/,   render: table }
+```
+
+The portal renders it without knowing what the role is. `render` is one of `memory`, `doc`,
+`gallery`, `table` or `code`.
+
+A surface is also a promise: `roster doctor` warns when one is declared and not on disk.
+
+## 4. Change what a new hire starts with
+
+`templates/brain/` in the framework is what `roster hire` renders. Editing it changes every
+future hire and nothing that already exists.
+
+Filenames are rendered too, which is why the callers are `%%STAFF%%-daily.yaml`.
+
+Two classes of file, and the difference decides what `roster upgrade` does later:
+
+- **The caller workflows** are generated. They track the template forever and are regenerated
+  wholesale.
+- **Everything else** is scaffold. It belongs to the staff member from the moment it is
+  created, and upgrade only ever adds a new one, never rewrites an existing one. That is why a
+  working agent's `CHARTER.md` and `memory/INDEX.md` are safe from you.
+
+## What not to extend
+
+`compose.mjs`, `agents.mjs`, `runner-plan.mjs` and `session.yaml` are the framework's. Change
+them in the framework and run `roster upgrade`. Editing them in the tenant works until the
+framework touches the same file, and `roster upgrade --check` fails on it for that reason.