@sublang/playbook 17.4.0 → 17.5.0

package/docs/cli.md

@@ -181,6 +181,7 @@ stderr, and `--verbose` adds only telemetry topic names to stderr.
 | Flag | Meaning |
 | --- | --- |
 | `--with <path>` | overlay current config for a fresh session or compatible ordinary reopen; repeatable |
+| `--module <id>=<specifier>` | supply playbook `<id>`'s registry module ahead of its `playbooks.<id>.from`; repeatable, one per id; a relative path resolves against the current directory |
 | `--no-provision` | do not create missing engine links for configured filesystem registries |
 | `--json` | print exactly one `sessionId` / `reply` object |
 | `--verbose` | add Captain telemetry topic names to stderr |
@@ -243,6 +244,26 @@ A directory where both imports already resolve is untouched, and
 module's directory is a git repository, add `node_modules/` to its
 `.gitignore` so provisioned links never enter player commits.
 
+A launch can also supply a playbook's module, which is never written back to
+your config files, for example when an embedding host keeps each playbook
+installed in an environment of its own. `--module <id>=<specifier>` (or
+`--module=<id>=<specifier>`) is accepted by `playbook`, `playbook --session`,
+`--list`, `--theme-diagnostics`, and fresh or continuing `playbook run`, and
+wins over that playbook's `from` the way a `--with` fragment wins over the
+file. An absolute path becomes a file URL, a relative path resolves against
+the directory where you run the command, and a file URL or package specifier
+is kept. The flag is never forwarded to tmux-play or sent as Boss input; it is
+refused beside a raw `--config`, during uncertain-turn recovery, for an id
+given twice, and for an id the config does not enable
+([[playbook-cli-94](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-94)],
+[[playbook-cli-96](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-96)],
+[DR-083](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/083-module-locations-supplied-at-launch.md)).
+
+```sh
+playbook --module code=/opt/env/code/registry.mjs
+playbook run --module review=@sublang/playbook/review/registry "/review the last commit"
+```
+
 ### Continuing a Captain session
 
 Interactive and headless commands write the same logical-session records in
@@ -279,9 +300,15 @@ competing front end fails closed instead of forking the history.
 
 An ordinary reopen reads current config and any opening `--with` fragments,
 projects them to the stored catalog and player roster, and requires the stored
-role bindings plus every structural setting to remain exact. Compatible
-current `model`, `effort`, and optional `fastMode`, `subagentModel`, and
-`subagentEffort` settings apply to the next call. Boolean `false` explicitly
+role bindings plus every structural setting to remain exact. A playbook whose
+current config names no `from` and receives no `--module` keeps the module the
+session records. Otherwise the module so taken — the supplied one, else a
+present `from` — must equal the stored module; a present `from` beside a
+supplied module is checked for form only. A `--module` for a playbook your
+config enables but the session does not hold is ignored, while one naming no
+playbook of your config is refused. Compatible current `model`, `effort`, and
+optional `fastMode`, `subagentModel`, and `subagentEffort` settings apply to
+the next call. Boolean `false` explicitly
 resets model, effort, subagent model, or subagent effort to the provider
 default, but `fastMode: false` is a literal
 disabled request; omission selects the provider default or inherits the player

package/docs/configuration.md

@@ -57,8 +57,11 @@ preflight their auth.
 
 Within a `playbooks.<id>` block, `from` (the registry module), `command` (an
 optional slash-command override), and `roles` are launcher-owned; every other
-key is that playbook's option slice. Every manifest role must be present
-exactly once. The launcher injects the rest — you do not write host wiring by
+key is that playbook's option slice. `from` is required unless the launch
+supplies that playbook's module with `--module <id>=<specifier>` (or an
+embedding host's `modules` option), or a reopened session already records
+one; see [Modules supplied at launch](#modules-supplied-at-launch). Every
+manifest role must be present exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
 The launcher seeds one adapter for the Captain and all stable players from
@@ -422,6 +425,33 @@ Before either front end imports a filesystem registry, the shared launcher
 checks and, unless `--no-provision` is set, provisions its runtime engine
 links as described in [Using the CLI](cli.md#external-playbooks-and-engine-provisioning).
 
+### Modules supplied at launch
+
+A config may leave `playbooks.<id>.from` out when the launch supplies the
+module instead, so the shared file names no machine-specific path:
+
+```yaml
+playbooks:
+  my-workflow:
+    roles:
+      worker: my.worker
+```
+
+```sh
+playbook run --module my-workflow=/opt/env/my-workflow.js "/my-workflow perform the task"
+```
+
+A supplied module wins over a `from` the file does carry, and it is never
+written back to your config files. A playbook with neither is refused before any import:
+`playbooks.<id> names no module: set playbooks.<id>.from or supply a module for
+<id> (--module <id>=<specifier>)`. A malformed `from` is still refused even
+when a module is supplied. Reopening a recorded session needs neither: with
+no `from` and no `--module`, it uses the module the session already records.
+Otherwise the module so taken — the supplied one, else a present `from` — must
+equal the stored module; a present `from` beside a supplied module is checked
+for form only
+([DR-083](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/083-module-locations-supplied-at-launch.md)).
+
 ## Migrating per-playbook players
 
 The former `playbooks.<id>.players` shape made agent configuration and local

package/docs/embedding.md

@@ -402,6 +402,35 @@ The controller owns uncertainty, reconciliation, settlement and lease release;
 observers receive presentation events or exact appended envelopes through
 `onStoredRecord`. Keep the controller open for successive turns.
 
+`loadLaunchPlan()` and `normalizeLaunchPlan()` accept an optional `modules`
+option, a read-only record from playbook id to module specifier. A host that
+keeps each playbook installed somewhere of its own hands the module locations
+there instead of writing them into the shared config, whose
+`playbooks.<id>.from` may then be left out:
+
+```ts
+import { loadLaunchPlan } from '@sublang/playbook/session-host';
+
+const plan = await loadLaunchPlan({
+  userConfigPath,
+  modules: { code: '/opt/env/code/registry.mjs', review: '@sublang/playbook/review/registry' },
+});
+```
+
+Each enabled playbook takes `modules[id]` ahead of its `from`. An absolute
+path becomes a file URL, while a file URL or package specifier is kept; a
+relative path is refused, so resolve it against your own working directory
+first. On a new launch, a module naming no enabled playbook is refused before
+any import; with `selectedMembers`, one for a current playbook outside the
+selection is skipped, while one naming no current playbook is still refused.
+These loaders hold no stored session record, so they refuse a playbook with
+neither a supplied module nor `from`, with or without `selectedMembers`; only
+the CLI's reopen of a recorded session falls back to the module that record
+holds. The preparation hook, single import, registry checks and the plan's
+canonical `from` are unchanged, and a supplied module is never written back to
+your config files
+([DR-083](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/083-module-locations-supplied-at-launch.md)).
+
 `shared.readLeaseState(sessionId)` reports `active`, `idle` or `unknown` without
 changing files. Use it for presentation; mutations still require a lease.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.4.0",
+  "version": "17.5.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -272,7 +272,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.33.1",
+    "@sublang/cligent": "^0.33.2",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.md

@@ -12,7 +12,7 @@ The caller supplies a coding request together with any relevant context.
 
 A new coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase followed by one phase for each IR task.
 An existing IR follows one IR-task phase for each remaining unfinished task, starting with its next unfinished task.
-Each phase ends with one new Coder commit (owned by `code`).
+Each completed phase ends with one new Coder commit (owned by `code`).
 After each `code`-owned commit, Captain shall call the `review` playbook and wait until it passes with no unsettled findings.
 Playbook `review` owns every review round and every review-fix commit.
 Do not rewrite any existing commit.
@@ -40,22 +40,37 @@ Plan affected spec updates before, with, or after their corresponding code chang
 For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 Do not implement a later task in this phase.
 Mark the IR's progress and deliverables when relevant.
+After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+Report only what the IR and completed work establish, in ordinary prose without a required marker.
 If the IR will be finished after this phase, double-check that all acceptance criteria are met.
 
 Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 ```
 
-At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, and any relevant run results in quotes (`>`), along with the following instruction:
+On each successful nested REVIEW, Captain shall freeze the previous phase review as one record from the canonical child result and the phase's accepted receipt-owned scope: exact phase kind (direct, new intent or IR task), phase outcome, CODE scope commit, REVIEW evaluated revision, and IR/task identity when present.
+CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
+No caller option, player prose or repository status text supplies this record.
+The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
+
+At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, any relevant run results, and that previous phase review as quoted evidence in quotes (`>`), along with the following instruction; when absent, the record reads "No accepted prior-phase review is available.":
 
 > Original request: <caller-input>
 > IR number: <ir-number>
 > Run results: <run-results>
+> Previous phase review: <previous-phase-review>
 
 ```markdown
 Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 Do not implement a later task in this phase.
 Mark the IR's progress and deliverables when relevant.
+After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+Report only what the IR and completed work establish, in ordinary prose without a required marker.
 If the IR will be finished after this phase, double-check that all acceptance criteria are met.
+Use the quoted previous-phase review only for its exact recorded scope; committed pending-review text may predate that canonical result.
+Before treating it as current review evidence, verify clean current HEAD equals its evaluatedRevision; a mismatch is not approval.
+It does not replace independent review of this task or any new owner or release decision.
 ```
 
 At the start of *every* phase, Captain shall append the following instruction:
@@ -63,7 +78,10 @@ At the start of *every* phase, Captain shall append the following instruction:
 ```markdown
 Keep to the original intent and follow what it asks.
 Do not re-run tests or builds whose inputs have not changed since any previous reported run.
-Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
+If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.
+Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.
+After the answer allows completion, make exactly one phase-owned commit before REVIEW.
+When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
 Make the commit message explain concisely what changed and why, including relevant verification.
 Identify every new commit you make.
 Credit every AI that contributed to this commit: Coder <coder-llm>.
@@ -73,9 +91,11 @@ Every new-intent phase has two semantic outcomes: direct implementation and new
 Every IR-task phase, including the first phase for an existing IR, identifies the IR and the implemented task, and has two semantic outcomes: more tasks and final task.
 The first phase therefore has four semantic outcomes — direct implementation, new IR, more tasks, and final task — plus the Boss question when the continued IR is ambiguous.
 Each semantic outcome requires affirmative support in Coder's result, but no phase transition shall depend on a fixed presentation format of Coder's reply.
+The Boss-question outcome means that, at the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome.
+A commit statement alone does not establish semantic completion, and contradictory or insufficient evidence supports no forced commit outcome.
 Captain shall use the repository-effect receipt as the authoritative identity of the phase's new commit.
 
-At the end of every phase, Captain shall call playbook `review` and input the following in quotes (`>`):
+At the end of every completed phase, Captain shall call playbook `review` and input the following in quotes (`>`):
 
 > Original intent: \<caller-input\>
 > Review scope: the commit \<code-commit\> from this coding phase and its resulting repository state.