diff --git a/docs/plans/2026-11-12_starter-packs-design.md b/docs/plans/2026-11-12_starter-packs-design.md index c791968c1..7fb4edfb9 100644 --- a/docs/plans/2026-11-12_starter-packs-design.md +++ b/docs/plans/2026-11-12_starter-packs-design.md @@ -728,33 +728,246 @@ proposals. The workflow's "relevant officer" step lists all four in its ## 8. Build slices -Each slice lands with its own tests. "Sign-off" marks a slice that touches -`roles/`, `contracts/`, a schema or a security boundary; Jason approves it -before build. +The slices run in order, SP1 to SP10, each landing with its own tests and +the full suites green. They are written so that one go from Jason covers all +of them; nothing in a slice waits on a further design choice. -| Slice | Scope | Acceptance | Test that fails first | Sign-off | -|---|---|---|---|---| -| SP1 | `checkPack` and `narrowsTemplate` in `packages/plugins/src/starter-pack.mjs`; kind `starter-pack` in `kinds.mjs`; loader listing with origin set by the loader | A valid pack loads; each forbidden key, stale template hash, role wider than its template, credential line wider than its template, root hire, ninth hire, unpinned hire definition and bad state refuses with its code; a shipped or installed pack with a `packs` key or a role without `from` refuses | `packages/plugins/tests/starter-pack.test.mjs`: a pack whose definition carries `copyBindings` loads (red until `checkPack` exists) | Yes: new plug-in kind, a pack schema | -| SP2 | The five shipped pack modules, each with a checked-in list of the flagged and credential lines its proposed hires carry | Each loads through SP1; every template pin equals `templateHash` now; for each proposed hire the lines `checkComposition` computes against `roles/chief-of-staff.json` equal the checked-in list (section 7); `chief-marketing-officer` is the only plain proposal | A test that loads `starter-pack/coding` and compares its pins against `templateHashes` and its computed lines against the list | No (data only, built on SP1) | -| SP3 | Org file keys `packs`, `board`, `workflows`, `projects.

.board`, `projects.

.workflows` in `organization-config.mjs`; writer op `applyPack` in `organization.mjs` | Unknown keys inside each refuse; board needs all five states once; workflow step `roles` name known definitions, templates or `human`; the size caps hold; `applyPack` commits in one write, refuses keys outside its list, refuses `definition-in-use` like `setDefinition`, and refuses `human-required` when an agent actor writes a definition | `organization-config` test: a file with `board` refuses today as an unknown top key; flip to accept the valid shape and refuse the invalid ones | Yes: org file schema and a writer op | -| SP4 | `pack.preview` and `pack.apply` (owner verbs, bus ops, `VERB_RIGHTS`, the saved-origin owner check) on top of `applyPack` | Preview writes nothing and lists flagged lines, credential lines and `noHire` marks; a pack string holding a held credential value refuses at preview and at apply; apply writes add items only and the `packs` entry with `added` and pinned `proposedHires`; stale digest refuses; second apply of the same pack is all `same`; an edited definition is `kept`; a removed item an earlier apply added is `removed` and not re-added; apply raises no decision | Broker test: `pack.apply.console` by a caller without `org.hire` refuses `right-required` (red until the verb exists), then the re-apply case | Yes: new verbs in `VERB_RIGHTS` | -| SP5 | Agent `pack.apply`, `board.set` and `workflow.set` for a role whose file lists `organization.change`; proposed hires surfaced in `packs` | An agent's apply writes no definition and refuses `human-required` if the plan has one; an agent without `organization.change` refuses `not-authorized`; a hire the chief raises from a proposal carries broker-computed flagged lines and refuses when its recorded pin no longer matches; a non-chief raise still refuses `role-not-chief` | Broker test: a coder session calling `pack.apply` refuses (red until the authority check is wired) | Yes: agent authority surface | -| SP6 | Console: pack picker, preview, apply; board labels on `tasks-board.js`; workflow view and editor | Labels and order apply only when the view is filtered to one org or project; the all-orgs view keeps today's labels; the pack layout is a default and the viewer's saved localStorage choice wins | `tasks-board` test: a view filtered to an org with a `board` shows its labels (red today, labels are fixed at line 21) | No | -| SP7 | Workflow guidance in the harness: a read-only workflows section in `prompt()` (`packages/harness/src/bundle.mjs:271`) for the chief, roles holding `task.create` or `task.assign`, and roles a step names | The section lists the org's or project's workflows and says they grant nothing; a role no step names and without those actions gets no section; contract text is unchanged | Bundle test: a chief bundle for an org with a `change` workflow contains the section (red until it is added) | Yes: changes what agents are told | -| SP8 | `template.save` and saved-template apply | Save writes a 0600 file with none of the stripped keys and keeps role credential request lines; instance names, org and project ids, the owner's account and project roots become placeholders; the preview lists every kept free-text field; a seeded held credential value refuses; list shows only the caller's own; apply of a saved template goes through SP4 with the owner check | Test: save an org whose instance has `credentials` and `copyBindings`; assert neither appears anywhere in the output (red until the stripper exists) | Yes: data leaving an organization | -| SP9 | System-type retirement, step 1: `system-type` kept as a retired kind; PRD REQ-SYS-1/2 text; removal of `systemTypesFence` and the Console, CLI and channel system-type surface | An org file with `plugins['system-type']` loads and the key is ignored; a write adding a name refuses `verb-retired`; the next writer commit drops the key and its trail event holds the old list; `project.system-types.set` refuses `verb-retired`; `project_system_types` rows unchanged | Migration test with a fixture org holding `["coding"]`: it loads after `system-types` code is gone (red if the kind is dropped) | Yes: PRD and data migration | -| SP10 | Step 2: remove the retired kind and add the print-only conversion | Runs only once no org file on the instance names `system-type`; the conversion prints a file without the key | Test: the conversion of the SP9 fixture prints no `system-type` key | No (follows SP9) | +**What the go covers.** No slice edits a file under `roles/` or `contracts/`. +The repository has no separate schema files; the schemas are the validators +named below, and every change to one is listed in its slice. The changes +that need sign-off are these: -Order: SP1 to SP10 in number order. SP9 can run after SP4 if the Console -needs the space earlier. SP10 waits at least one release after SP9. +- a new plug-in kind and a new `switch` value (SP1); +- new org file keys (SP3); +- new verbs in `VERB_RIGHTS` (`packages/organization/src/org-rights.mjs:34`) + and in `CONSOLE_VERBS` (`packages/bus/src/broker.mjs:181`) (SP4, SP8); +- an agent authority surface for `organization.change` holders (SP5); +- new text in agents' generated prompts (SP7); +- data leaving an organization (SP8); +- a PRD wording change and a retired kind (SP9). + +New refusal codes are added to `packages/bus/src/refusals.mjs` by the slice +that first uses them: `starter-pack-invalid`, +`starter-pack-template-changed`, `pack-plan-stale`, +`starter-pack-proposal-stale`, `template-secret-suspected` and +`verb-retired`. + +**Owner boundary.** "Owns" lists the files a slice may change. A slice that +needs a change outside its list stops and reports; it does not widen +itself. Tests for a slice live beside the files it owns. + +### SP1: the pack kind and its checker + +- Owns: `packages/plugins/src/starter-pack.mjs` (new), + `packages/plugins/src/kinds.mjs`, `packages/plugins/src/loader.mjs` (only + if the listing needs a hook), `packages/bus/src/refusals.mjs`, + `packages/plugins/tests/starter-pack.test.mjs` (new). +- Schema change: `KINDS` gains `"starter-pack"` with `interfaceVersion: 1`, + `exports: ["starterPack"]` and a new `switch: "none"`. `namesFor` refuses + any setting for a `none` kind with `bad-setting`, so an org file can never + switch a pack on through `plugins`. +- Builds: `checkPack(doc, {origin})` and `narrowsTemplate(role, template)` + as section 2 states; `installedStarterPacks({dataRoot})`, which lists + shipped and installed packs through `loadInstalled` and sets the origin; + `readSavedTemplate(path)` through `parseJsonFileText` with the 256 KiB cap. +- Acceptance: a valid pack loads. Each of these refuses with its code: a + forbidden key, a stale template hash, a role wider than its template, a + credential line wider than its template, a root hire, a ninth hire, a hire + naming no pack definition, a bad state, a duplicate column. A shipped or + installed pack with a `packs` key or a role without `from` refuses; a + saved one with either passes. `plugins: {"starter-pack": ["coding"]}` + refuses `bad-setting`. +- Red before: a pack whose definition carries `copyBindings` passes (there + is no `checkPack`, so nothing refuses it). + +### SP2: the five shipped packs + +- Owns: `packages/plugins/starter-pack/{coding,creative-writing,marketing,montage,business-management}/` + (new: `index.mjs` and `expected-lines.json` each), + `packages/plugins/tests/starter-pack-shipped.test.mjs` (new). +- Schema change: none. +- Builds: the five documents in section 7, each pinned to today's + `templateHash` values. +- Acceptance: each loads through SP1 with origin `shipped`. For each + proposed hire, the flagged and credential lines `checkComposition` + computes against `roles/chief-of-staff.json` equal `expected-lines.json`; + `chief-marketing-officer` is the only proposal with none. A template edit + that moves a hash turns this test red until the pack is re-pinned, which + is the intended review point. +- Red before: loading `starter-pack/coding` finds no module. + +### SP3: org file keys and the writer op + +- Owns: `packages/organization/src/organization-config.mjs`, + `packages/organization/src/organization.mjs`, their tests. +- Schema change: `TOP_KEYS` (`organization-config.mjs:32`) gains `packs`, + `board` and `workflows`. The project entry keys (`organization-config.mjs:306`) + gain `board` and `workflows`. Shapes, each refusing unknown keys: + - `board`: `{columns: [{state, label}] x5, layout}`, all five + `STORE_STATES` once, labels 1 to 32 characters, layout `kanban` or + `list`; + - `workflows`: `{: {title, description, steps: [{title, state, roles}]}}`, + names matching `NAME`, 1 to 20 steps, titles up to 120 characters, + description up to 1,000, each step's `roles` 1 to 8 names that are an + org definition, a V2 template or `human`; + - `packs`: a list of `{id, version, sha256, origin, scope, project, at, by, added, proposedHires}`, + origin one of `shipped`, `installed`, `saved`. +- Builds: `applyPack(id, plan, {revision, actor, assertClean})` on the writer + with the rules in section 3: one commit, `rev: 1` on each added + definition, `checkDefinition` with `assertClean`, `definition-in-use` as + `setDefinition` refuses it, `human-required` when an agent actor writes a + definition, and a refusal for any key outside its list. +- Acceptance: valid shapes load and each invalid one refuses; `applyPack` + writes everything or nothing (a fault injected after the definitions + leaves the file unchanged); an agent actor with a definition in the plan + refuses `human-required`. +- Red before: a file with a `board` key refuses today as an unknown top key + (`organization-config.mjs:259`); the test expects it to load. + +### SP4: preview and apply for people + +- Owns: `packages/bus/src/broker.mjs` (the new verbs only), + `packages/organization/src/org-rights.mjs`, `packages/cli/src/org.mjs` + (the `pack` words), `packages/webui/src/serve.mjs` (the two routes), their + tests. +- Schema change: `VERB_RIGHTS` gains `packs: 'board.read'`, + `'pack.preview.console': 'org.hire'` and `'pack.apply.console': 'org.hire'`. + `CONSOLE_VERBS` gains the two console verbs. A saved-origin pack also + needs the caller to be the owner. +- Builds: `mosaic org pack list|preview|apply`, `POST /api/orgs//packs/preview` + and `POST /api/orgs//packs/apply`, and the merge table in section 3, + including `kept`, `--as` and the `removed` tombstone. +- Acceptance: preview writes nothing and lists flagged lines, credential + lines and `noHire` marks; a pack string holding a held credential value + refuses at preview and at apply; apply writes only `add` items and the + `packs` entry with `added` and pinned `proposedHires`; a stale digest + refuses `pack-plan-stale`; a second apply of the same pack is all `same`; + an edited definition is `kept`; an item an earlier apply added and the + owner then removed is `removed`; apply raises no decision. +- Red before: `pack.apply.console` by a member without `org.hire` refuses + `right-required`, and the verb is unknown today. + +### SP5: apply and board and workflow writes for agents + +- Owns: `packages/bus/src/broker.mjs` (the agent verbs and the hire pin + check only), their tests. +- Schema change: none to files. Authority: agent verbs `pack.preview`, + `pack.apply`, `board.set` and `workflow.set` for a role whose file lists + `organization.change`, the same test `organization.set` uses + (`broker.mjs:6247-6255`). +- Builds: the agent apply in section 3 (no definitions, `human-required` if + the plan has one); the pin check when the chief raises a proposal + (`decision-stale`, `definition-rev-conflict`, and + `starter-pack-proposal-stale` when an inline entry's canonical hash + differs; the broker checks that hash, then passes `{inline}` on). +- Acceptance: an agent without `organization.change` refuses + `not-authorized`; an agent apply with a definition in the plan refuses + `human-required`; a hire the chief raises from a proposal carries the + broker-computed lines; a non-chief raise still refuses `role-not-chief`; + a proposal whose pinned template moved refuses `decision-stale`. +- Red before: a coder session calling `pack.apply` gets an unknown-verb + refusal today; the test expects `not-authorized`. + +### SP6: Console pack picker, board labels and workflow editor + +- Owns: `packages/webui/src/public/tasks-board.js`, a new + `packages/webui/src/public/packs.js`, the workflow view, their tests. +- Schema change: none. +- Builds: pack picker, preview and apply through SP4; labels and order from + `board` when the view is filtered to one org or project; `layout` as a + default under the viewer's saved `localStorage` choice; a workflow list and + editor through `workflow.set` or the owner path. +- Acceptance: a view filtered to an org with a `board` shows its labels; the + all-orgs view keeps today's labels; a saved viewer layout wins over the + pack default. +- Red before: a view filtered to an org with a `board` shows the fixed labels + (`tasks-board.js:21`). + +### SP7: workflow guidance in the prompt + +- Owns: `packages/harness/src/bundle.mjs` (`prompt`, line 271), its tests. +- Schema change: none to files. New prompt text, which is why it needs + sign-off. +- Builds: the read-only workflows section in section 2, for the chief, roles + holding `task.create` or `task.assign`, and roles a step names (their own + steps only). The section says workflows grant nothing and the contract and + rails win. +- Acceptance: a chief bundle for an org with a workflow contains the + section; a role no step names and without those actions gets none; the + contract text is byte-identical to before. +- Red before: a chief bundle for an org with a `change` workflow has no + workflows section. + +### SP8: saving a template + +- Owns: `packages/organization/src/template-save.mjs` (new), + `packages/bus/src/broker.mjs` (`template.save.console` only), + `packages/organization/src/org-rights.mjs`, `packages/cli/src/org.mjs` + (the `template save|list` words), `packages/webui/src/serve.mjs` (the + routes), their tests. +- Schema change: `VERB_RIGHTS` gains `'template.save.console': null` (owner + only). The saved file is a pack document read with origin `saved`; it adds + no new schema. +- Builds: capture, strip, placeholder and preview rules in section 5; the + file at `/templates//.json`, mode 0600, written + with `wx`; `list` shows only the caller's own. +- Acceptance: the file has none of the stripped keys and keeps role + credential request lines; instance names, org and project ids, the owner's + account and project roots become placeholders; the preview lists every + kept free-text field; a seeded held credential value refuses + `template-secret-suspected` naming the field path; a second save to the + same name refuses; applying a saved template goes through SP4 with the + owner check. +- Red before: save an org whose instance has `credentials` and + `copyBindings` and assert neither appears in the output; the verb does not + exist today. + +### SP9: retire system types, step 1 + +- Owns: `packages/plugins/src/kinds.mjs`, `packages/plugins/src/system-types.mjs` + (deleted), `packages/organization/src/organization-config.mjs` and + `organization.mjs` (the retired-key handling only), the system-type code in + `packages/bus/src/broker.mjs`, `packages/cli/src/org.mjs`, + `packages/plugins/channel/cli/index.mjs` and the Console files listed in + section 1, `packages/plugins/system-type/` (deleted), `docs/prd/mosaic-stack.md` + (REQ-SYS-1/2 only), their tests. +- Schema change: `system-type` stays in `KINDS` with `retired: true`. + `checkPlugins` accepts a valid list for it, the reader ignores it, and a + write that adds a name refuses `verb-retired`. The next writer commit drops + the key and its trail event keeps the old list. `project_system_types` is + unchanged (no DDL). The PRD text is section 6's. +- Builds: the removals in section 6; `project.system-types.set` refuses + `verb-retired`; the read verb stays. +- Acceptance: an org file with `plugins['system-type']` loads with the key + ignored; the next commit drops it and its trail event holds the old list; + `project_system_types` rows are unchanged; no system-type route, CLI word + or channel verb is left. +- Red before: a fixture org holding `["coding"]` must still load once the + system-type modules are gone; dropping the kind outright would fail it + with `unknown-kind`. + +### SP10: remove the retired kind + +- Owns: `packages/plugins/src/kinds.mjs`, a print-only conversion beside + `packages/organization/src/migrate-launch.mjs`, their tests. +- Schema change: `system-type` leaves `KINDS`. +- Runs: one release after SP9, and only once no org file on the instance + names `system-type`. The slice checks that first and stops if one does. +- Acceptance: the conversion prints the SP9 fixture without the key; with + no file naming the kind, removal leaves every org file loading. +- Red before: the conversion does not exist. ## 9. Open questions for Jason +Each answer changes what gets built. The slices above follow the +recommendation; a different answer changes the slice named. + 1. **Retire system types as a separate kind?** This design replaces the `system-type` kind with `starter-pack`. Org files that name the old kind keep loading for one release and lose the key on their next write; `project_system_types` stays as history. Recommendation: yes. The modules carry - nothing today, and two surfaces for one idea would confuse users. + nothing today, and two surfaces for one idea would confuse users. A no + drops SP9 and SP10 and keeps the system-type label beside packs. 2. **May the chief change board styles and workflows directly, as it changes limits today?** This design puts `board.set`, `workflow.set` and the non-definition half of `pack.apply` under the chief's existing @@ -762,8 +975,11 @@ needs the space earlier. SP10 waits at least one release after SP9. carry no capability, the trail records each change, and a decision here would be a new gate. Any role listing `organization.change` gets the same writes, so the rule is the grant, not the chief's name. Role and hire - changes stay decisions, and only the chief raises hires. + changes stay decisions, and only the chief raises hires. A no drops the + agent writes from SP5 and leaves agents to propose board and workflow + changes in a message to the owner. 3. **Board styles as labels and order over the five fixed states, or custom states?** Custom states would change the task tracker contract, every tracker module and the Vikunja bucket setup. Recommendation: labels, order - and layout only for now; revisit custom states when a pack needs one. + and layout only for now; revisit custom states when a pack needs one. A + no adds a tracker contract change to SP3 and every tracker module.