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`: `{