@sublang/playbook 11.0.0 → 12.1.0

package/docs/cli.md

@@ -105,8 +105,8 @@ its exit status or signal and exit `127` when it cannot be spawned
 
 The Boss pane starts at the Playbook Captain shell, where the session
 Captain runs for the whole session and sees every turn. Use `/code`,
-`/review`, or `/decide` followed by a task to select one of the bundled
-playbooks explicitly. A registered command resolves deterministically,
+`/review`, `/decide`, or `/dev` followed by a task to select one of the
+bundled playbooks explicitly. A registered command resolves deterministically,
 with no model call parsing it: at idle it starts that playbook, at its
 own leaf it delivers the rest of the line, an enabled command absent
 from the active path switches to it, and a bare command answers with
@@ -121,9 +121,11 @@ untouched
 ([[playbook-captain-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-1)],
 [[playbook-captain-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-2)]).
 
-The current CODE, REVIEW, and DECIDE workflows take their deterministic
+The current CODE, REVIEW, DECIDE, and DEV workflows take their deterministic
 initial event from the selecting Boss turn. CODE and DECIDE then call REVIEW
-as a nested playbook. Local role names do not imply continuity: each frame
+as a nested playbook, while DEV — the repository-aware planner behind
+`/dev` — analyzes a development request and itself calls CODE, or DECIDE and
+then CODE, as nested playbooks. Local role names do not imply continuity: each frame
 uses the exact stable player IDs configured under its `roles` map. Equal IDs
 share one pane and provider conversation across nested and later root
 engagements; distinct IDs remain isolated even when their agent settings are
@@ -321,8 +323,9 @@ to present the `incomplete` status it receives
 For each governed player call, Playbook records a Git baseline before the call
 and a durable receipt afterward. CODE and DECIDE commit arms, and REVIEW's
 Coder commit arm, accept a commit only when the receipt proves exactly one
-descendant commit with no residual repository change; REVIEW's Reviewer calls
-and DECIDE's proposal calls require the repository to remain exact. The
+descendant commit with no residual repository change; REVIEW's Reviewer calls,
+DECIDE's proposal calls, and every DEV Analyst planning call require the
+repository to remain exact. The
 player's prose, including any `Commit:` line, is presentation rather than
 proof.
 

package/docs/configuration.md

@@ -84,6 +84,13 @@ players:
     permissions:
       mode: auto # protected auto mode for the Claude Reviewer
 
+  dev.analyst:
+    adapter: claude
+    model: claude-opus-5
+    effort: xhigh
+    permissions:
+      mode: auto # protected auto mode for the Claude Analyst
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
@@ -101,6 +108,11 @@ playbooks:
     roles:
       coder: dev.coder
       reviewer: dev.reviewer
+
+  dev:
+    from: '@sublang/playbook/dev/registry'
+    roles:
+      analyst: dev.analyst
 ```
 
 The current bundled workflows accept no workflow-specific options.
@@ -146,7 +158,9 @@ Two bindings that name the same player ID deliberately share one sequential
 provider conversation throughout the logical Captain session — across nested
 calls, returns, and later root engagements. CODE's and REVIEW's `coder` roles
 therefore share `dev.coder` in the starter, and DECIDE and its nested REVIEW
-share both starter players. Disposal of one playbook frame does not clear that
+share both starter players. DEV's `analyst` instead binds the distinct
+`dev.analyst` player, so planning context does not bleed into the shared
+review conversation. Disposal of one playbook frame does not clear that
 session ledger.
 
 Two distinct player IDs stay isolated even when their agent blocks are

package/docs/embedding.md

@@ -153,7 +153,9 @@ const playbookSessionId = randomUUID();
 // session lease and resolving the canonical Git worktree. Their authority
 // must name this playbook/session/working directory and their repository and
 // effect-ledger operations must stay live; never put them in configuration,
-// machine input, or a persisted snapshot.
+// machine input, or a persisted snapshot. A host outside the CLI constructs
+// the repository and effect-ledger members through the facade described in
+// "Constructing worktree host capabilities" below.
 declare const hostCapabilities: ReviewPlaybookHostCapabilities;
 
 const runtime = createPlaybookRuntime({
@@ -220,6 +222,86 @@ capability functions never enter Boss-visible status text or configured
 options. Because trace observers do receive opaque resume tokens, persisted
 traces should be protected as sensitive data.
 
+## Constructing worktree host capabilities
+
+A schema-3 artifact takes live `{ repository, effectLedger }` capabilities
+beside its configured options. Rather than reimplementing the engine's
+observation, claim, receipt, and ledger contract, construct them through the
+narrow, semver-stable `@sublang/playbook/host-capabilities` facade. It is the
+CLI host's own implementation, re-exported: every classification the engine
+makes for `playbook run` is the one your host makes too.
+
+```ts
+import {
+  createFailClosedHostCapabilities,
+  createWorktreeHostCapabilities,
+} from '@sublang/playbook/host-capabilities';
+
+declare const workdir: string;
+declare const createPlaybookRuntime: (construction: {
+  configuredOptions: object;
+  hostCapabilities: object;
+}) => unknown;
+
+// One capability per playbook and Git worktree, constructed after the
+// working directory is resolved and before the runtime is. The roles are the
+// artifact's declared roles; an undeclared role is refused at boundary start.
+const hostCapabilities = await createWorktreeHostCapabilities({
+  cwd: workdir,
+  playbookId: 'workflow',
+  requiredRoleIds: ['coder', 'reviewer'],
+});
+const runtime = createPlaybookRuntime({
+  configuredOptions: {},
+  hostCapabilities,
+});
+
+// An artifact declaring no governed player state needs no worktree at all:
+// every repository operation and ledger write rejects, and the ledger stays
+// empty.
+const inert = createPlaybookRuntime({
+  configuredOptions: {},
+  hostCapabilities: createFailClosedHostCapabilities(),
+});
+```
+
+`createWorktreeHostCapabilities()` requires only that `cwd` exist and returns
+exactly `repository: { identity, observe, runExclusive, runDeferred }` and
+`effectLedger: { snapshot, writeAhead }`. The governed worktree is bound at
+every governed call and observation rather than fixed at construction: it is
+the canonical root of the nearest Git worktree containing `cwd`, or — when
+there is none — `cwd` itself as the prospective root `{ worktree, gitDir:
+worktree/.git }` that a later `git init` there binds unchanged. A directory
+that is not a repository yet observes as the null (all-zero) HEAD over its
+non-ignored content, exactly as `git init` would then see it, and an unborn
+HEAD observes as the null OID too; so a workflow whose first step runs
+`test -e .git || git init` in its working directory receives `unchanged`, and
+its first root commit receives `one-descendant-commit` with that commit's OID.
+`identity` is the binding at construction; each boundary records the binding
+its baseline observed. The ledger is in memory and starts from the optional
+`effectLedger` seed, so a host that wants durability keeps
+`effectLedger.snapshot()` at its own boundaries and seeds the next
+construction from it; each construction is one attempt over its seed.
+`runExclusive` and `runDeferred` hold the same cross-process worktree claim the
+CLI uses (process-local until the repository exists, since there is no `.git`
+to publish it in), observe before and after the operation, apply the engine's
+correction-budget `writeAhead` mid-completion, and bind, park, continue, and
+restore deferred Boss questions with the engine's exact checkpoint semantics.
+Overlapping calls on one worktree run one at a time, in no guaranteed order.
+A write the ledger rejects after a boundary has started leaves the worktree
+claim quarantined, exactly as it would under `playbook run`: treat that
+rejection as terminal for the worktree in this process.
+
+The module functions `observeGitRepository(cwd)`,
+`captureRepositoryReceipt(baseline, { allowedDispositions })`, and
+`classifyRepositoryReceipt(baseline, after, { allowedDispositions })` expose
+the same observation and receipt classification for a host that inspects a
+worktree outside a governed call. The declaration is self-contained — it
+re-declares the ledger, receipt, observation, and question types of
+`@sublang/playbook/runtime` name for name — and the facade carries no session
+lease, session record, resume credential, catalog, or recovery member
+([[playbook-cli-87](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-cli.md#playbook-cli-87)]).
+
 ## Sharing the CLI session store
 
 An external host that needs the CLI's canonical session validation and

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "11.0.0",
+  "version": "12.1.0",
   "type": "module",
-  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, and DECIDE workflows driven by GEARS specs.",
+  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, and DEV workflows driven by GEARS specs.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -45,6 +45,7 @@
     "reference/sdlc/code.md",
     "reference/sdlc/review.md",
     "reference/sdlc/decide.md",
+    "reference/sdlc/dev.md",
     "reference/sdlc/captain.playbook/captain.gears.md",
     "reference/sdlc/captain.playbook/captain.fsm.ts",
     "reference/sdlc/captain.playbook/captain.fsm.js",
@@ -69,6 +70,8 @@
     "reference/sdlc/code.playbook/playbook-captain.d.ts",
     "reference/sdlc/code.playbook/session-store.js",
     "reference/sdlc/code.playbook/session-store.d.ts",
+    "reference/sdlc/code.playbook/host-capabilities.js",
+    "reference/sdlc/code.playbook/host-capabilities.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
@@ -100,6 +103,16 @@
     "reference/sdlc/decide.playbook/decide.registry.ts",
     "reference/sdlc/decide.playbook/decide.registry.js",
     "reference/sdlc/decide.playbook/decide.registry.d.ts",
+    "reference/sdlc/dev.playbook/dev.gears.md",
+    "reference/sdlc/dev.playbook/dev.fsm.ts",
+    "reference/sdlc/dev.playbook/dev.fsm.js",
+    "reference/sdlc/dev.playbook/dev.fsm.d.ts",
+    "reference/sdlc/dev.playbook/dev.playbook.ts",
+    "reference/sdlc/dev.playbook/dev.playbook.js",
+    "reference/sdlc/dev.playbook/dev.playbook.d.ts",
+    "reference/sdlc/dev.playbook/dev.registry.ts",
+    "reference/sdlc/dev.playbook/dev.registry.js",
+    "reference/sdlc/dev.playbook/dev.registry.d.ts",
     "docs"
   ],
   "bin": {
@@ -134,6 +147,10 @@
       "types": "./reference/sdlc/code.playbook/session-store.d.ts",
       "default": "./reference/sdlc/code.playbook/session-store.js"
     },
+    "./host-capabilities": {
+      "types": "./reference/sdlc/code.playbook/host-capabilities.d.ts",
+      "default": "./reference/sdlc/code.playbook/host-capabilities.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",
@@ -150,6 +167,14 @@
     "./decide/registry": {
       "types": "./reference/sdlc/decide.playbook/decide.registry.d.ts",
       "default": "./reference/sdlc/decide.playbook/decide.registry.js"
+    },
+    "./dev/playbook": {
+      "types": "./reference/sdlc/dev.playbook/dev.playbook.d.ts",
+      "default": "./reference/sdlc/dev.playbook/dev.playbook.js"
+    },
+    "./dev/registry": {
+      "types": "./reference/sdlc/dev.playbook/dev.registry.d.ts",
+      "default": "./reference/sdlc/dev.playbook/dev.registry.js"
     }
   },
   "scripts": {
@@ -172,7 +197,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.221",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.223",
     "@openai/codex-sdk": "^0.146.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0",