paseo-room 0.4.1 → 0.5.0

package/README.md

@@ -89,7 +89,9 @@ starts, its exit code is preserved; a signal is returned using the conventional
 ~/.paseo-room/
   room.json                       # what this CLI created; verify and remove read it
   AUTHENTICATION.md               # exact per-role login commands; contains no secrets
-  room/WORKSPACE_PROTOCOL.md      # the default protocol Lead and Supervisor carry, as one readable file
+  room/skills/paseo-project-onboarding/   # Lead-only Agent Skill: draft a repository protocol
+    SKILL.md, references/         # procedure plus a scaffold loaded only when the skill runs
+  room/skill-projections/<agent>/lead/     # exact Lead skill aggregate for each seated agent
   plugin/                         # Claude only: trusted creation-time system-prompt append carrier
     paseo-plugin.json             # accepts Paseo >=0.8.0 <0.9.0
     index.server.ts, server/      # exact provider map + generated role contracts
@@ -98,20 +100,20 @@ starts, its exit code is preserved; a signal is returned using the conventional
     role-instructions.md          # readable copy of what this seat was told
     model-catalog.json            # generated copy of your catalog, native multi-agent metadata removed
     auth.json                       # created and owned by Codex after role login, if file-backed
-    AGENTS.md, skills, plugins, hooks.json              → symlinks into ~/.codex when present (Peer: see below)
+    AGENTS.md, skills, plugins, hooks.json              → shared resources (Lead/Peer: see below)
   roles/claude/<role>/
     CLAUDE.md                     # your global memory + role instructions (contract omitted with --no-claude-memory-contract)
-    settings.json                 # your settings.json + PASEO_ROOM_ROLE
+    settings.json                 # minimal room-owned env, deny and control-plane policy
     .claude.json                  # seeded once from yours, then owned by Claude
     .credentials.json                # created and owned by Claude after role login, if file-backed
     skills, plugins, commands, hooks, rules, output-styles,
-    keybindings.json, themes                          → symlinks into ~/.claude when present (Peer: see below)
+    keybindings.json, themes                          → shared resources (Lead/Peer: see below)
   roles/pi/<role>/
     settings.json                 # your settings minus package/extension declarations
     APPEND_SYSTEM.md              # your append + style/runtime capsules + role instructions
     auth.json                         # created and owned by Pi after role login, if used
     models.json, AGENTS.md, skills, prompts, themes,
-    keybindings.json, mcp.json                        → symlinks into ~/.pi/agent when present (Peer: see below)
+    keybindings.json, mcp.json                        → shared resources (Lead/Peer: see below)
 ```
 
 Each seat gets its own file-backed credential path, sessions, history and projects inside its
@@ -125,7 +127,14 @@ file. Anything else at a managed path — a directory where a file belongs, an u
 symlink — makes setup stop and name the path for you to move aside. Nothing is deleted
 recursively on your behalf.
 
-### What Peer does not receive
+### How Lead and Peer receive skills
+
+Lead's `skills` remains a symlink, but now points to a room-owned managed aggregate containing
+links to every noncolliding operator skill plus the room-owned `paseo-project-onboarding` skill.
+This adds the room skill without writing into your agent home, while keeping the role path
+replaceable by an older package during rollback. An operator skill whose name collides
+case-insensitively remains untouched but is shadowed in the aggregate by the room-owned copy,
+avoiding duplicate names on case-insensitive filesystems.
 
 Peer has no room tools, so the room also stops handing it orchestration surfaces:
 
@@ -138,9 +147,9 @@ Peer has no room tools, so the room also stops handing it orchestration surfaces
   removing one of your skills is drift `verify` reports and `setup --apply` reconciles.
 
 Your own skills directory is never modified: `paseo*` skills stay exactly where they are.
-An existing room upgrades its one legacy Peer `skills` symlink to that projection on the next
-`setup --apply`; setup only unlinks the alias, never your skills, and stops with an actionable
-message if that path has become something it does not recognize.
+On the next `setup --apply`, an existing Lead `skills` symlink is retargeted to its room aggregate,
+while a legacy Peer symlink becomes its managed directory. Setup only replaces or unlinks those
+aliases, never your skills, and stops with an actionable message for an unrecognized Peer shape.
 
 This is capability hygiene, not a sandbox. Peer still has shell access.
 
@@ -170,8 +179,8 @@ and environment-variable names. They never read credential contents, query a key
 a token over the network, or claim OAuth freshness. Authentication findings are warnings and
 do not turn an otherwise valid setup or verify into a failure:
 
-- **configured structurally** — a regular role credential file or supported auth configuration
-  name exists; validity and freshness were not checked;
+- **configured structurally** — a regular role credential file exists; validity and freshness
+  were not checked;
 - **login-required** — no role credential artifact or safely recognizable alternative exists;
 - **legacy-shared-risk** — an older room has a credential symlink, including one whose target
   may now be missing; only its stored link text is read, it is preserved, and the output gives
@@ -206,12 +215,12 @@ argv. No login path reads, copies, links, replaces, validates, or deletes a cred
 
 Codex diagnostics recognize an explicit `cli_auth_credentials_store` of `file`, `ephemeral`,
 `auto`, or `keyring`. An `OPENAI_API_KEY` name in the setup shell does not count as stored role
-auth; Codex's API-key login must create that role's native store. Claude recognizes the
-documented cloud selectors, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`,
-`CLAUDE_CODE_OAUTH_TOKEN`, and `apiKeyHelper` by name. Pi recognizes a bounded list of built-in
-provider API-key environment names. Names found only in the setup process are ambient and
-unverifiable because their values are not copied into Paseo providers; other ambient provider
-authentication may exist but is not validated.
+auth; Codex's API-key login must create that role's native store. Claude role settings do not
+import operator auth helpers; diagnostics recognize only ambient documented cloud selectors,
+`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, and `CLAUDE_CODE_OAUTH_TOKEN` by name. Pi recognizes a
+bounded list of built-in provider API-key environment names. Names found only in the setup process
+are ambient and unverifiable because their values are not copied into Paseo providers; other
+ambient provider authentication may exist but is not validated.
 
 ## What the room changes
 
@@ -286,13 +295,13 @@ attribute `/mcp` to `source: "extension"` at that same canonical path. Missing,
 path-escaped or wrongly attributed adapters fail closed. The probe and setup do not write the
 operator or planned role homes.
 
-Each seat is also pinned at the Paseo provider level, because a provider entry outranks the
-agent's own configuration:
+Each seat combines generated agent configuration with Paseo provider pins. Provider fields are
+still required where Paseo launch state outranks the agent's own configuration:
 
 | Pin | Applies to | Why |
 |---|---|---|
 | `params: {sandbox_mode, approval_policy}` | Codex | Without it Paseo sends its own mode preset (default `auto-review`) to the Codex app-server, and that outranks the generated `config.toml`. |
-| `disallowedTools` for `Task`, `Agent`, `Workflow`, coordination, task-list, cron and team tools | Claude | Blocks legacy/current subagents, dynamic workflows, cross-session coordination and agent teams. |
+| provider `disallowedTools` + role `permissions.deny` for `Task`, `Agent`, `Workflow`, coordination, task-list, cron and team tools | Claude | Blocks legacy/current subagents, dynamic workflows, cross-session coordination and agent teams at both Paseo and Claude's role settings. |
 | `disableAgentView: true` + `CLAUDE_CODE_DISABLE_AGENT_VIEW=1` | Claude | Disables Claude's separate background-agent control plane across settings scopes and at launch. |
 | `disableWorkflows: true` + `CLAUDE_CODE_DISABLE_WORKFLOWS=1` | Claude | Disables dynamic workflows through every entry point, beyond denying the `Workflow` tool. |
 | `crossSessionInbound: "refuse"` | Claude | Prevents another Claude session from injecting a turn into a room seat. |
@@ -302,7 +311,8 @@ agent's own configuration:
 `verify` compares each provider's `command`, `env`, `paseoTools` and pins against what the
 room would write, and fails if one has been dropped — a pin that can be silently removed is
 not a guarantee. The `env` map is compared whole rather than as a subset, because an added key
-can re-enable exactly what a pin closes. Unrelated top-level provider fields stay yours.
+can re-enable exactly what a pin closes. Unrelated top-level provider fields stay yours. Claude
+role `settings.json` is compared separately as a managed file, including `permissions.deny`.
 
 It also saves one **agent profile** per seat, which is what the Paseo picker lists under
 Profiles. A profile is a preset, not a constraint: it decides where a seat *starts*.
@@ -332,10 +342,12 @@ stale room-owned value from an existing Pi profile. Pi has no sandbox or approva
 its permissive runtime is necessary for headless operation but grants no additional authority.
 
 Claude starts in Paseo's `bypassPermissions` mode, while Codex starts in its equivalent
-`full-access` mode. Claude deny rules still apply in bypass mode, so native orchestration
-stays unavailable. The room does not write `permissions.defaultMode` to `settings.json`:
-Paseo passes the profile's mode as a command-line session setting, which outranks that file.
-The two Claude disable environment keys are pinned in both the provider and generated
+`full-access` mode. Claude deny rules still apply in bypass mode, so the canonical native-tool
+list is written to both provider `disallowedTools` and every role's `settings.json` under
+`permissions.deny`. The role file is minimal, deterministic room policy: it does not copy operator
+env, hooks, permissions, or auth helpers. The room does not write `permissions.defaultMode`:
+Paseo passes the profile's mode as a command-line session setting, which outranks that file. The two
+Claude disable environment keys are likewise pinned in both the provider and generated
 `settings.json`, because Claude applies settings-file environment values after launch values.
 The generated top-level `disableAgentView` and `disableWorkflows` settings are also forced to
 `true`; their restrictive value cannot be weakened by another ordinary settings scope.
@@ -349,18 +361,18 @@ the operator.
 Names are not identity. A matching cwd, title, or provider label does not make an existing
 agent a room Lead or Peer. The exact eligibility procedure is model-facing wording and lives
 in the contract itself —
-[Lead Discovery and Recovery](src/room/prompts/contract/supervisor/lead-discovery-and-recovery.md)
-for Supervisor and
-[Peer Seat Lifecycle](src/room/prompts/contract/lead/peer-seat-lifecycle.md) for Lead — rather
-than being restated here. In outline: the seat's evidence is the current live configuration.
-Supervisor reads the exact current `room-<agent>-lead` profile from `list_profiles` and
-materializes every field it defines (agent creation takes no profile id), uses `list_agents(cwd)`
-only to find candidates, then inspects each one's full status for the profile's provider, the
-intended workspace and its mode. For `room-<agent>-peer`, Lead copies provider, mode and
-features exactly, keeps the profile's model unless the root workspace protocol routes models,
-chooses the thinking effort for the brief, and additionally
-requires the live seat's daemon-added `paseo.parent-agent-id` to name itself. Ownership must be
-corroborated by parentage or known Human-opened history; an ambiguous candidate goes to
+the shared [Room Seat Identity](src/room/prompts/contract/shared-seat-identity.md) evidence,
+with the role-specific procedures in
+[the Supervisor contract](src/room/prompts/contract/supervisor.md) and
+[the Lead contract](src/room/prompts/contract/lead.md) — rather than being restated here. In
+outline: the seat's evidence is the current live configuration. Both seats read the exact current
+`room-<agent>-<role>` profile from `list_profiles`, materialize every field it defines (agent
+creation takes no profile id), then inspect the live seat's provider, workspace and mode.
+Supervisor additionally uses `list_agents(cwd)` for discovery and corroborates Lead ownership by
+parentage or known Human-opened history. For `room-<agent>-peer`, Lead copies provider, mode and
+features exactly, keeps the profile's model unless a repository protocol routes models,
+chooses the thinking effort under that repository protocol's policy, and requires the live seat's
+daemon-added `paseo.parent-agent-id` to name itself. An ambiguous Lead candidate goes to
 duplicate recovery and Human escalation instead of being adopted.
 
 Current Paseo agent sessions do not retain `profileId`. A direct launch with the exact
@@ -370,9 +382,10 @@ provider ids or claim that the daemon enforces this procedural eligibility check
 
 ## Keeping the room current
 
-Role homes are generated once, at `setup` time. After you edit `~/.codex/config.toml`,
-`~/.claude/settings.json`, or Pi's `settings.json` / `APPEND_SYSTEM.md`, run setup again to
-fold the change into every seat. The same applies after upgrading `paseo-room`; a release
+Role homes are generated once, at `setup` time. After you edit `~/.codex/config.toml` or Pi's
+`settings.json` / `APPEND_SYSTEM.md`, run setup again to fold the change into every seat. Claude's
+operator `settings.json` is not an input to its minimal room settings. The same applies after
+upgrading `paseo-room`; a release
 that changes generated headings or prompt assets produces expected one-time managed-file
 drift.
 
@@ -392,16 +405,20 @@ seat after the apply; sending another turn to an already-running seat is not a r
 context reloaded them. Only a newly launched seat context is expected to ingest the
 regenerated instructions.
 
-`room.json` records a short `contract` digest of the role documents and workspace protocol
-this room was installed from. When it differs from what the installed package renders — or is
-absent, because the room predates the field — setup and verify warn that the seats are holding
-older text and ask for `setup --apply` plus a restart. It is provenance you compare by eye, not
-a security claim. Rooms written before the field still parse.
+`room.json` records a short `contract` digest of the three rendered role documents this room
+was installed from. When it differs from what the installed package renders — or is absent,
+because the room predates the field — setup and verify warn that the seats are holding older
+text and ask for `setup --apply` plus a restart. It is provenance you compare by eye, not a
+security claim. Rooms written before the field still parse.
+
+The room-owned skill files are live managed entries instead: `verify` compares their exact bytes,
+so a skill update is not reported as stale seat instructions.
 
-One migration happens on the first upgraded apply: an existing Peer `skills` symlink becomes
-the room-owned projection described above. Only the alias is unlinked, never your skills, and
-setup stops with an actionable message rather than guessing if that path has become something
-it does not recognize.
+On the first upgraded apply, each Lead `skills` symlink is retargeted to its room-owned aggregate
+and an existing Peer `skills` symlink becomes the room-owned projection described above. Only
+aliases are replaced or unlinked, never your skills. Lead retains the symlink shape the prior
+package expects, so package-level rollback can retarget it without a reverse migration; setup
+still stops rather than guessing if the Peer path has become something it does not recognize.
 
 To roll back, run the prior package version with the same agent selection and `setup --apply`,
 then restart the affected seats again:
@@ -422,8 +439,7 @@ There are three separate evidence boundaries:
 - `setup --apply` and `verify`, backed by regression tests, prove the generated/live
   configuration chain: each room profile points to its exact role provider and owned mode,
   each provider points to the exact role home, and each provider-selected role home carries
-  the exact prompt input with the applicable role contract and default workspace-protocol
-  sections.
+  the exact prompt input with the applicable role contract.
 - Delivery of those files and arguments into a newly launched model context relies on the
   documented Codex, Claude Code and Pi configuration contracts for
   `developer_instructions`, `CLAUDE.md`, and `--append-system-prompt`.
@@ -446,8 +462,10 @@ command again.
 ## The role contract
 
 The exact model-facing wording every seat reads lives in the canonical Markdown under
-[`src/room/prompts/`](src/room/prompts/). TypeScript selects those semantic sections with
-`instructionKeys()` and `protocolKeys()`; it does not duplicate their prose. In short:
+[`src/room/prompts/`](src/room/prompts/), organised by who reads it: one shared authority body
+for every role, shared room-seat identity evidence for Supervisor and Lead, the shared challenge
+vocabulary for Lead and Peer, and exactly one body per role. TypeScript selects those layers with
+`instructionKeys()`; it does not duplicate their prose. In short:
 
 - **Supervisor** routes Human directives to Lead and observes. Before opening a seat it checks
   for and reuses the project's existing Lead, including an idle or resumable Lead. It observes
@@ -457,8 +475,9 @@ The exact model-facing wording every seat reads lives in the canonical Markdown
 - **Lead** is the durable owner of one project across turns. It owns framing, decomposition,
   routing, integration and technical acceptance. A brief states the outcome and the evidence
   that settles it rather than pre-solving the work; any plan or file list in it is provisional.
-  One moving write scope has exactly one owner, and at most one Peer is writable at a time.
-  Room tools: on.
+  One moving write scope has exactly one owner, and at most one Peer is writable at a time. It
+  explicitly requests native Paseo completion/error/permission notification for Peer creation and
+  every background follow-up, then waits for events rather than polling. Room tools: on.
 - **Peer** owns one bounded assignment — writable inside an assigned scope, or read-only
   against a named candidate, question or area — under exactly one disposition Lead names in the
   brief (Engineer, Architect, Reviewer or Scout), forms its own technical position from the code
@@ -485,24 +504,57 @@ Two further limits are deliberately conservative. **One writable Peer per projec
 per moving scope: the room gives you no writer isolation, so separate scopes are not evidence
 of separate working trees, and no workspace protocol relaxes the limit. Concurrent writable
 Peers in isolated worktrees are a deferred decision, not an oversight. And a seat's **model and
-reasoning effort are not one knob**: the model stays the profile's default unless the root
-`WORKSPACE_PROTOCOL.md` explicitly supplies model routing, while the thinking effort is Lead's
+reasoning effort are not one knob**: the model stays the profile's default unless a repository
+protocol explicitly supplies model routing, while the thinking effort is Lead's
 per-brief choice on task risk, uncertainty, context size and verification burden — lowest that
 reliably answers the task, higher for architecture-sensitive or weakly observable work, only an
 option the live Paseo and provider context establishes as supported, and never up to a tier
 advertising automatic delegation. Provider, mode, workspace, parent and feature values are
 eligibility evidence and copied exactly.
 
-Every seat that owns workflow also carries a **default workspace protocol** — topology by
-difficulty, verification, review, repository conventions — so a project has that layer without
-doing anything. It goes to Lead and Supervisor, not to Peer: Lead reads the protocol and quotes
-what bears on an assignment into the brief, including the exact verification command, so a Peer
-spends its attention on one brief rather than on deciding which repository rules apply. A
-repository that needs different rules writes `WORKSPACE_PROTOCOL.md` at its root, which wins
-wherever it speaks while the default holds wherever it is silent — the root, because it is
-agent guidance rather than project documentation. `~/.paseo-room/room/WORKSPACE_PROTOCOL.md` is
-the whole default as one file, so you can read what is in force and start from it. The CLI
-never writes into a repository.
+The room ships **no default workspace protocol**. A repository's root `WORKSPACE_PROTOCOL.md`
+is optional, and when it exists it is that repository's complete workflow policy — there is no
+hidden room document behind it to reconcile point by point, and no unstated rule survives where
+it is silent. It stays subordinate to the authority floor: repository workflow directs how work
+is done and can never enlarge or weaken role authority. The file lives at the repository root
+because it is agent guidance rather than project documentation. The CLI never writes into a
+repository.
+
+Reading it goes to **Lead alone**, the only standing reader of workflow policy: Lead resolves
+the repository root, reads the file in full when the repository ships one, and quotes what bears
+on an assignment into the brief, including the exact verification command. Supervisor reads a
+repository's protocol only under an explicit Human audit, update or maintenance mandate;
+ordinary routing and observation need none of it, and it may propose a change with causal
+evidence but never impose one. Peer is never told the filename at all, so it spends its attention
+on one brief rather than on deciding which repository rules apply — what it needs unconditionally
+is in its own contract, including the floor that no repository or workspace instruction can
+enlarge or weaken its authority, with conflicts routed to Lead.
+
+Lead's own contract carries a short, visible **operating baseline**, not another workspace
+policy: compact Engineer/Architect/Reviewer/Scout assignment vocabulary; exact profile model and
+thinking defaults absent explicit repository routing; the obligation to name and run the
+repository's own verification gate; and fresh read-only review when Human or a repository
+protocol requires it, or when Lead sees material technical risk. These stated contract rules
+remain visible when a repository protocol is silent; no generic topology matrix, anti-pattern
+catalog, or protocol-evolution policy survives in any prompt.
+
+To write a protocol, Lead has one room-owned **Agent Skill**, `paseo-project-onboarding`,
+delivered to Lead's `skills` directory from `~/.paseo-room/room/skills/` and to no other seat.
+It inspects what the repository actually contains — agent instructions, README/CONTRIBUTING,
+build manifests and scripts, CI, test configuration, architecture and operations docs — and
+returns an evidence map, one standalone complete draft, and the decisions Human still owns,
+separating observed facts from proposals rather than guessing. It is proposal-first: it writes
+nothing by default, and writes the repository's root `WORKSPACE_PROTOCOL.md` only under an
+explicit Human instruction to apply the draft, refusing any non-regular shape at that path and
+leaving unrelated work alone. It cannot change authority, tool policy, the writer limit,
+provider identity or credentials, and cannot make Peer a protocol reader. Its bundled template
+is a scaffold loaded while the skill runs, never appended to a session.
+
+Lead's visible skill inventory is therefore an exact room-owned aggregate behind the role-home
+symlink: one link per skill in your own agent home, plus a link to the room's skill. Your own home
+is never modified, and an operator skill whose name matches `paseo-project-onboarding` under a
+case-insensitive comparison is left exactly where it is — the room-owned copy owns that name
+inside the aggregate only.
 
 ## Working the room
 
@@ -541,9 +593,9 @@ that review; Supervisor must route the request to Lead rather than opening a fre
 
 ## Documentation
 
-- [docs/orchestration-model.md](docs/orchestration-model.md) — the reference model this
-  tool implements: roles, authority, instruction layers, invariants, anti-patterns and
-  operating checklists. Tool-agnostic; useful on its own.
+- [docs/demonthorn-agent-orchestration-deep-dive.md](docs/demonthorn-agent-orchestration-deep-dive.md)
+  — the reference model this tool implements: roles, authority, instruction layers, invariants,
+  anti-patterns and operating checklists. Tool-agnostic; useful on its own.
 - [docs/design.md](docs/design.md) — how and why this tool implements that model, and what
   it deliberately does not do. Read this before changing an override.
 - [AGENTS.md](AGENTS.md) — working rules for contributors and coding agents.