@sublang/playbook 4.0.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +69 -122
  2. package/docs/assets/playbook-venn.svg +13 -0
  3. package/docs/cli.md +43 -26
  4. package/docs/configuration.md +63 -18
  5. package/docs/embedding.md +24 -16
  6. package/package.json +43 -22
  7. package/reference/sdlc/captain.md +70 -83
  8. package/reference/sdlc/captain.playbook/captain.fsm.d.ts +127 -142
  9. package/reference/sdlc/captain.playbook/captain.fsm.js +349 -470
  10. package/reference/sdlc/captain.playbook/captain.fsm.ts +535 -598
  11. package/reference/sdlc/captain.playbook/captain.gears.md +37 -41
  12. package/reference/sdlc/captain.playbook/captain.playbook.d.ts +90 -15
  13. package/reference/sdlc/captain.playbook/captain.playbook.js +466 -976
  14. package/reference/sdlc/captain.playbook/captain.playbook.ts +698 -1001
  15. package/reference/sdlc/code.md +55 -97
  16. package/reference/sdlc/code.playbook/code.fsm.d.ts +229 -94
  17. package/reference/sdlc/code.playbook/code.fsm.introspect.d.ts +26 -44
  18. package/reference/sdlc/code.playbook/code.fsm.introspect.js +61 -66
  19. package/reference/sdlc/code.playbook/code.fsm.introspect.ts +100 -149
  20. package/reference/sdlc/code.playbook/code.fsm.js +587 -1347
  21. package/reference/sdlc/code.playbook/code.fsm.ts +809 -1650
  22. package/reference/sdlc/code.playbook/code.gears.md +51 -263
  23. package/reference/sdlc/code.playbook/code.playbook.d.ts +8 -47
  24. package/reference/sdlc/code.playbook/code.playbook.js +69 -639
  25. package/reference/sdlc/code.playbook/code.playbook.ts +90 -850
  26. package/reference/sdlc/code.playbook/code.registry.d.ts +9 -25
  27. package/reference/sdlc/code.playbook/code.registry.js +20 -78
  28. package/reference/sdlc/code.playbook/code.registry.ts +58 -122
  29. package/reference/sdlc/code.playbook/playbook-captain.d.ts +2 -0
  30. package/reference/sdlc/code.playbook/playbook-captain.js +1877 -251
  31. package/reference/sdlc/code.playbook/playbook-captain.ts +2385 -352
  32. package/reference/sdlc/code.playbook/playbook.config.template.yaml +33 -22
  33. package/reference/sdlc/decide.md +54 -0
  34. package/reference/sdlc/decide.playbook/decide.fsm.d.ts +261 -0
  35. package/reference/sdlc/decide.playbook/decide.fsm.js +894 -0
  36. package/reference/sdlc/decide.playbook/decide.fsm.ts +1152 -0
  37. package/reference/sdlc/decide.playbook/decide.gears.md +88 -0
  38. package/reference/sdlc/decide.playbook/decide.playbook.d.ts +67 -0
  39. package/reference/sdlc/{discuss.playbook/discuss.playbook.js → decide.playbook/decide.playbook.js} +511 -370
  40. package/reference/sdlc/{discuss.playbook/discuss.playbook.ts → decide.playbook/decide.playbook.ts} +616 -451
  41. package/reference/sdlc/decide.playbook/decide.registry.d.ts +41 -0
  42. package/reference/sdlc/decide.playbook/decide.registry.js +60 -0
  43. package/reference/sdlc/decide.playbook/decide.registry.ts +125 -0
  44. package/reference/sdlc/review.md +81 -0
  45. package/reference/sdlc/review.playbook/review.fsm.d.ts +183 -0
  46. package/reference/sdlc/review.playbook/review.fsm.js +524 -0
  47. package/reference/sdlc/review.playbook/review.fsm.ts +652 -0
  48. package/reference/sdlc/review.playbook/review.gears.md +112 -0
  49. package/reference/sdlc/review.playbook/review.playbook.d.ts +12 -0
  50. package/reference/sdlc/review.playbook/review.playbook.js +112 -0
  51. package/reference/sdlc/review.playbook/review.playbook.ts +201 -0
  52. package/reference/sdlc/review.playbook/review.registry.d.ts +43 -0
  53. package/reference/sdlc/review.playbook/review.registry.js +73 -0
  54. package/reference/sdlc/review.playbook/review.registry.ts +138 -0
  55. package/slc/gears2fsm.md +67 -6
  56. package/slc/link.md +339 -25
  57. package/slc/text2gears.md +22 -2
  58. package/src/runtime.d.ts +36 -1
  59. package/src/runtime.ts +59 -0
  60. package/src/xstate-playbook-runtime.d.ts +96 -7
  61. package/src/xstate-playbook-runtime.js +1018 -49
  62. package/src/xstate-playbook-runtime.ts +1283 -59
  63. package/src/xstate-runtime.js +25 -0
  64. package/src/xstate-runtime.ts +51 -0
  65. package/reference/sdlc/discuss.md +0 -93
  66. package/reference/sdlc/discuss.playbook/discuss.fsm.d.ts +0 -396
  67. package/reference/sdlc/discuss.playbook/discuss.fsm.js +0 -2067
  68. package/reference/sdlc/discuss.playbook/discuss.fsm.ts +0 -2465
  69. package/reference/sdlc/discuss.playbook/discuss.gears.md +0 -258
  70. package/reference/sdlc/discuss.playbook/discuss.playbook.d.ts +0 -113
  71. package/reference/sdlc/discuss.playbook/discuss.registry.d.ts +0 -58
  72. package/reference/sdlc/discuss.playbook/discuss.registry.js +0 -97
  73. package/reference/sdlc/discuss.playbook/discuss.registry.ts +0 -153
@@ -1,258 +0,0 @@
1
- <!-- SPDX-License-Identifier: Apache-2.0 -->
2
- <!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
3
-
4
- # Discuss
5
-
6
- ## Players
7
-
8
- - Boss: the human user (default)
9
- - Captain: the coordinating agent (default)
10
- - Host
11
- - Participant
12
- - Committer = Host | Participant
13
-
14
- ## Initial Discussion
15
-
16
- Host and Participant make their initial proposals in parallel.
17
- Each later reconciliation round also runs Host and Participant in parallel, with both receiving only the proposals promoted by the previous completed round.
18
- Captain shall wait for both branch results and promote them together before starting the next round.
19
- If one branch asks Boss a question, only that branch waits; the sibling branch continues, and a completed sibling branch is not restarted when Boss replies.
20
- Boss interrupts target the whole `initialProposalRound` or `reconciliationRound`; the four branch working states are resumable question destinations but are not independently jumpable.
21
- Rounds continue until both Host and Participant state the end of initial discussion.
22
-
23
- ### DISCUSS-1
24
-
25
- Parallel group: initial-proposal-round
26
-
27
- When Boss gives a topic, Captain shall prompt Host:
28
-
29
- > Boss's topic: <topic>
30
- > Assess whether Boss's topic above is better expressed as a few spec items (per @specs/meta.md) or requires one or more DRs added to @specs/decisions/.
31
- > Consult @specs/map.md, if necessary, to find relevant context.
32
- > Each DR should be coherent and focused.
33
- > Propose your design in reply.
34
- > DRs, if any, need not include full detail here - describe the key points at a high level.
35
- > Don't change any code.
36
-
37
- ### DISCUSS-2
38
-
39
- Parallel group: initial-proposal-round
40
-
41
- When Boss gives a topic, Captain shall prompt Participant:
42
-
43
- > Boss's topic: <topic>
44
- > Assess whether Boss's topic above is better expressed as a few spec items (per @specs/meta.md) or requires one or more DRs added to @specs/decisions/.
45
- > Consult @specs/map.md, if necessary, to find relevant context.
46
- > Each DR should be coherent and focused.
47
- > Propose your design in reply.
48
- > DRs, if any, need not include full detail here - describe the key points at a high level.
49
- > Don't change any code.
50
-
51
- ### DISCUSS-3
52
-
53
- Parallel group: reconciliation-round
54
-
55
- While the initial discussion is not ended and Participant made a proposal in the previous round, when a new initial-discussion round begins, Captain shall prompt Host:
56
-
57
- > Other agent's proposal: <participant-proposal>
58
- > Your previous proposal: <host-previous-proposal>
59
- > Consider the other agent's proposal below.
60
- > (1) If there are essentially different points (including creation or division of DRs), list them, accept any reasonable ones, and challenge the rest with strong reasoning, solid evidence, and comprehensive thinking - make your argument.
61
- > (2) Only if your proposal of the previous round is equivalent to the other's, with nothing to reconcile, state the end of initial discussion.
62
- > Don't change any code.
63
-
64
- ### DISCUSS-4
65
-
66
- Parallel group: reconciliation-round
67
-
68
- While the initial discussion is not ended and Host made a proposal in the previous round, when a new initial-discussion round begins, Captain shall prompt Participant:
69
-
70
- > Other agent's proposal: <host-proposal>
71
- > Your previous proposal: <participant-previous-proposal>
72
- > Consider the other agent's proposal below.
73
- > (1) If there are essentially different points (including creation or division of DRs), list them, accept any reasonable ones, and challenge the rest with strong reasoning, solid evidence, and comprehensive thinking - make your argument.
74
- > (2) Only if your proposal of the previous round is equivalent to the other's, with nothing to reconcile, state the end of initial discussion.
75
- > Don't change any code.
76
-
77
- ### DISCUSS-5
78
-
79
- When Host and Participant both state the end of initial discussion, Captain shall prompt Host:
80
-
81
- > Agreement: <agreement>
82
- > Write spec items or DRs according to the agreement.
83
- > Update @specs/map.md to reflect your changes (if any) when done.
84
-
85
- ## Review
86
-
87
- Review rounds proceed without waiting for Boss.
88
- In the first step of each review round, Participant reviews the latest changes, addresses any rebuttals, and raises any findings.
89
- In the second step of each review round, Host addresses any findings.
90
- Rounds continue until Participant raises no findings.
91
-
92
- Spec item files are the files under @specs/ that hold spec items — @specs/packages/ and @specs/compositions/ in the current layout, or @specs/user/, @specs/dev/, and @specs/test/ in the legacy one; decision and intent records (iteration records in older scaffolds), @specs/map.md, and @specs/meta.md are not spec item files.
93
-
94
- ### DISCUSS-6
95
-
96
- While new or updated spec items (in spec item files) are under review and no new or updated DR is under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
97
-
98
- > Latest changes: <changes>
99
- > Rebuttals to address, if any: <rebuttals>
100
- > Review the latest spec changes, address any rebuttals, and raise any findings.
101
- > Verify any new or updated spec items are:
102
- > Complete & coherent: sufficient for you to reimplement code.
103
- > Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
104
- > Minimal: essential and concise; every item earns its place; also check with other items.
105
- > Well organized: spec packages are finely scoped, with high cohesion and low coupling.
106
- > Flag anything missing, redundant, over-specified, or under-specified.
107
- > Think thoroughly - don't just approve or reject.
108
- > For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
109
- > Verify @specs/map.md reflects the changes.
110
- > If the change is ready to commit or push, don't raise nitpicks.
111
- > Do not edit files or commit; report findings only.
112
-
113
- ### DISCUSS-7
114
-
115
- While new or updated spec items (in spec item files) are under review and no new or updated DR is under review, when Host addresses findings with changes, Captain shall prompt Participant:
116
-
117
- > Latest changes: <changes>
118
- > Rebuttals to address, if any: <rebuttals>
119
- > Review the latest spec changes, address any rebuttals, and raise any findings.
120
- > Verify any new or updated spec items are:
121
- > Complete & coherent: sufficient for you to reimplement code.
122
- > Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
123
- > Minimal: essential and concise; every item earns its place; also check with other items.
124
- > Well organized: spec packages are finely scoped, with high cohesion and low coupling.
125
- > Flag anything missing, redundant, over-specified, or under-specified.
126
- > Think thoroughly - don't just approve or reject.
127
- > For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
128
- > Verify @specs/map.md reflects the changes.
129
- > If the change is ready to commit or push, don't raise nitpicks.
130
- > Do not edit files or commit; report findings only.
131
-
132
- ### DISCUSS-8
133
-
134
- While new or updated DRs are under review and no new or updated spec item (in spec item files) is under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
135
-
136
- > Latest changes: <changes>
137
- > Rebuttals to address, if any: <rebuttals>
138
- > Review the latest spec changes, address any rebuttals, and raise any findings.
139
- > Review any new/updated decision following @specs/meta.md (reread if necessary).
140
- > Flag any issues or propose any design suggestions (numbered; no duplication), with strong reasoning and evidence.
141
- > Key statements must be backed by references unless they are common sense or widely acknowledged best practices.
142
- > If the decision is well-thought-out and well-written, don't raise nitpicks.
143
- > Remember to keep the DR simple and minimal.
144
- > Think thoroughly - don't just approve or reject.
145
- > For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
146
- > Verify @specs/map.md reflects the changes.
147
- > If the change is ready to commit or push, don't raise nitpicks.
148
- > Do not edit files or commit; report findings only.
149
-
150
- ### DISCUSS-9
151
-
152
- While new or updated DRs are under review and no new or updated spec item (in spec item files) is under review, when Host addresses findings with changes, Captain shall prompt Participant:
153
-
154
- > Latest changes: <changes>
155
- > Rebuttals to address, if any: <rebuttals>
156
- > Review the latest spec changes, address any rebuttals, and raise any findings.
157
- > Review any new/updated decision following @specs/meta.md (reread if necessary).
158
- > Flag any issues or propose any design suggestions (numbered; no duplication), with strong reasoning and evidence.
159
- > Key statements must be backed by references unless they are common sense or widely acknowledged best practices.
160
- > If the decision is well-thought-out and well-written, don't raise nitpicks.
161
- > Remember to keep the DR simple and minimal.
162
- > Think thoroughly - don't just approve or reject.
163
- > For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
164
- > Verify @specs/map.md reflects the changes.
165
- > If the change is ready to commit or push, don't raise nitpicks.
166
- > Do not edit files or commit; report findings only.
167
-
168
- ### DISCUSS-10
169
-
170
- While new or updated spec items (in spec item files) are under review and new or updated DRs are under review, when Committer commits at the end of the initial discussion, Captain shall prompt Participant:
171
-
172
- > Latest changes: <changes>
173
- > Rebuttals to address, if any: <rebuttals>
174
- > Review the latest spec changes, address any rebuttals, and raise any findings.
175
- > Verify any new or updated spec items are:
176
- > Complete & coherent: sufficient for you to reimplement code.
177
- > Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
178
- > Minimal: essential and concise; every item earns its place; also check with other items.
179
- > Well organized: spec packages are finely scoped, with high cohesion and low coupling.
180
- > Flag anything missing, redundant, over-specified, or under-specified.
181
- > Review any new/updated decision following @specs/meta.md (reread if necessary).
182
- > Flag any issues or propose any design suggestions (numbered; no duplication), with strong reasoning and evidence.
183
- > Key statements must be backed by references unless they are common sense or widely acknowledged best practices.
184
- > If the decision is well-thought-out and well-written, don't raise nitpicks.
185
- > Remember to keep the DR simple and minimal.
186
- > Think thoroughly - don't just approve or reject.
187
- > For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
188
- > Verify @specs/map.md reflects the changes.
189
- > If the change is ready to commit or push, don't raise nitpicks.
190
- > Do not edit files or commit; report findings only.
191
-
192
- ### DISCUSS-11
193
-
194
- While new or updated spec items (in spec item files) are under review and new or updated DRs are under review, when Host addresses findings with changes, Captain shall prompt Participant:
195
-
196
- > Latest changes: <changes>
197
- > Rebuttals to address, if any: <rebuttals>
198
- > Review the latest spec changes, address any rebuttals, and raise any findings.
199
- > Verify any new or updated spec items are:
200
- > Complete & coherent: sufficient for you to reimplement code.
201
- > Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
202
- > Minimal: essential and concise; every item earns its place; also check with other items.
203
- > Well organized: spec packages are finely scoped, with high cohesion and low coupling.
204
- > Flag anything missing, redundant, over-specified, or under-specified.
205
- > Review any new/updated decision following @specs/meta.md (reread if necessary).
206
- > Flag any issues or propose any design suggestions (numbered; no duplication), with strong reasoning and evidence.
207
- > Key statements must be backed by references unless they are common sense or widely acknowledged best practices.
208
- > If the decision is well-thought-out and well-written, don't raise nitpicks.
209
- > Remember to keep the DR simple and minimal.
210
- > Think thoroughly - don't just approve or reject.
211
- > For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
212
- > Verify @specs/map.md reflects the changes.
213
- > If the change is ready to commit or push, don't raise nitpicks.
214
- > Do not edit files or commit; report findings only.
215
-
216
- ### DISCUSS-12
217
-
218
- When Participant raises any findings, Captain shall prompt Host:
219
-
220
- > Review items: <review-items>
221
- > For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
222
- > Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.
223
-
224
- ### DISCUSS-13
225
-
226
- When Host raises any rebuttals, Captain shall prompt Participant:
227
-
228
- > Rebuttals: <rebuttals>
229
- > For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
230
-
231
- ## Commit
232
-
233
- Model ID formatting examples: `claude-opus-4-7` becomes `Claude-Opus-4.7`; `gpt-5.5` becomes `GPT-5.5`.
234
-
235
- ### DISCUSS-14
236
-
237
- When the spec items or DRs are written at the end of the initial discussion, Captain shall prompt Committer:
238
-
239
- > Then make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
240
- > If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
241
- > Write the commit message concisely.
242
- > Host is <host-llm>.
243
- > Participant is <participant-llm>.
244
- > Format the Host and Participant model IDs as conventional human forms.
245
-
246
- Results:
247
- - `committed`: Committer made the initial-discussion commit. Output may include `latestChanges: <summary>` and `reviewScope: "specItems" | "decisionRecords" | "mixed"`.
248
-
249
- ### DISCUSS-15
250
-
251
- When Participant raises no findings on uncommitted changes, Captain shall prompt Committer:
252
-
253
- > Then make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
254
- > If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
255
- > Write the commit message concisely.
256
- > Host is <host-llm>.
257
- > Participant is <participant-llm>.
258
- > Format the Host and Participant model IDs as conventional human forms.
@@ -1,113 +0,0 @@
1
- import { type PlayerInput, type PlayerOutput, type DiscussEvent, type DiscussInput, type PendingBossQuestion } from './discuss.fsm.js';
2
- import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType } from '@sublang/playbook/runtime';
3
- export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, };
4
- type PlayerName = 'Host' | 'Participant' | 'Committer';
5
- export interface PlaybookRuntimeOptions extends DiscussInput {
6
- playerBinding?: Partial<Record<PlayerName, string>>;
7
- }
8
- declare function composePlayerPrompt(input: PlayerInput): string;
9
- declare function resolvePlayerId(input: PlayerInput, binding: Record<PlayerName, string>): string;
10
- declare function requiredFieldsFor(description: string): string[];
11
- declare function extractJson(raw: string): Record<string, unknown> | null;
12
- declare function buildClassifierPrompt(text: string, ctx: {
13
- state: PlaybookState;
14
- pendingQuestions: readonly PendingBossQuestion[];
15
- }): string;
16
- declare function parseClassification(raw: string, pendingQuestionIds?: readonly string[]): DiscussEvent | null;
17
- declare function buildAdjudicatorPrompt(input: PlayerInput, playerOutput: string): string;
18
- declare function parseAdjudication(raw: string, input: PlayerInput): PlayerOutput;
19
- declare function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal;
20
- declare function normalizeErrorCompact(err: unknown): {
21
- name: string;
22
- message: string;
23
- } | undefined;
24
- declare function normalizeErrorFull(err: unknown): {
25
- name: string;
26
- message: string;
27
- stack?: string;
28
- } | undefined;
29
- declare function pendingQuestionsFromContext(context: Record<string, unknown>): PendingBossQuestion[];
30
- export declare const createPlaybookRuntime: PlaybookRuntimeFactory<PlaybookRuntimeOptions>;
31
- export declare const _internal: {
32
- composePlayerPrompt: typeof composePlayerPrompt;
33
- resolvePlayerId: typeof resolvePlayerId;
34
- requiredFieldsFor: typeof requiredFieldsFor;
35
- extractJson: typeof extractJson;
36
- buildClassifierPrompt: typeof buildClassifierPrompt;
37
- parseClassification: typeof parseClassification;
38
- buildAdjudicatorPrompt: typeof buildAdjudicatorPrompt;
39
- parseAdjudication: typeof parseAdjudication;
40
- combineSignals: typeof combineSignals;
41
- pendingQuestionsFromContext: typeof pendingQuestionsFromContext;
42
- normalizeErrorCompact: typeof normalizeErrorCompact;
43
- normalizeErrorFull: typeof normalizeErrorFull;
44
- DEFAULT_PLAYER_BINDING: Readonly<Record<PlayerName, string>>;
45
- ALIAS_RESOLUTION: Readonly<Record<string, string>>;
46
- STATE_DESCRIPTIONS: Readonly<Record<string, string>>;
47
- CAPTAIN_STATES: readonly [{
48
- readonly stateId: "askHostInitial";
49
- readonly player: "Host";
50
- readonly sourceItem: "DISCUSS-1";
51
- }, {
52
- readonly stateId: "askParticipantInitial";
53
- readonly player: "Participant";
54
- readonly sourceItem: "DISCUSS-2";
55
- }, {
56
- readonly stateId: "hostInitialRound";
57
- readonly player: "Host";
58
- readonly sourceItem: "DISCUSS-3";
59
- }, {
60
- readonly stateId: "participantInitialRound";
61
- readonly player: "Participant";
62
- readonly sourceItem: "DISCUSS-4";
63
- }, {
64
- readonly stateId: "hostWritesAgreement";
65
- readonly player: "Host";
66
- readonly sourceItem: "DISCUSS-5";
67
- }, {
68
- readonly stateId: "commitInitialChanges";
69
- readonly player: "Committer";
70
- readonly sourceItem: "DISCUSS-14";
71
- }, {
72
- readonly stateId: "reviewSpecInitialCommit";
73
- readonly player: "Participant";
74
- readonly sourceItem: "DISCUSS-6";
75
- }, {
76
- readonly stateId: "reviewSpecHostChanges";
77
- readonly player: "Participant";
78
- readonly sourceItem: "DISCUSS-7";
79
- }, {
80
- readonly stateId: "reviewDrInitialCommit";
81
- readonly player: "Participant";
82
- readonly sourceItem: "DISCUSS-8";
83
- }, {
84
- readonly stateId: "reviewDrHostChanges";
85
- readonly player: "Participant";
86
- readonly sourceItem: "DISCUSS-9";
87
- }, {
88
- readonly stateId: "reviewMixedInitialCommit";
89
- readonly player: "Participant";
90
- readonly sourceItem: "DISCUSS-10";
91
- }, {
92
- readonly stateId: "reviewMixedHostChanges";
93
- readonly player: "Participant";
94
- readonly sourceItem: "DISCUSS-11";
95
- }, {
96
- readonly stateId: "hostAddressesFindings";
97
- readonly player: "Host";
98
- readonly sourceItem: "DISCUSS-12";
99
- }, {
100
- readonly stateId: "participantAddressesRebuttals";
101
- readonly player: "Participant";
102
- readonly sourceItem: "DISCUSS-13";
103
- }, {
104
- readonly stateId: "commitReviewedChanges";
105
- readonly player: "Committer";
106
- readonly sourceItem: "DISCUSS-15";
107
- }];
108
- CAPTAIN_STATE_IDS: ReadonlySet<string>;
109
- BOSS_INTERRUPT_TARGETS: readonly ["ready", "initialProposalRound", "reconciliationRound", "hostWritesAgreement", "commitInitialChanges", "reviewSpecInitialCommit", "reviewSpecHostChanges", "reviewDrInitialCommit", "reviewDrHostChanges", "reviewMixedInitialCommit", "reviewMixedHostChanges", "hostAddressesFindings", "participantAddressesRebuttals", "commitReviewedChanges", "failed"];
110
- CONTINUATION_PREAMBLE: string;
111
- TELEMETRY_TOPIC: string;
112
- };
113
- export default createPlaybookRuntime;
@@ -1,58 +0,0 @@
1
- import type { PlaybookRuntime } from '@sublang/playbook/runtime';
2
- import type { PlaybookRuntimeOptions } from './discuss.playbook.js';
3
- export interface RegistryPlayer {
4
- id: string;
5
- adapter?: string;
6
- model?: string;
7
- }
8
- export interface CreateDiscussRuntimeOptions {
9
- captainOptions: unknown;
10
- players: readonly RegistryPlayer[];
11
- }
12
- export interface DiscussOptions {
13
- /** Which alias alternative runs `Committer` commits; defaults to `host`. */
14
- committer?: 'host' | 'participant';
15
- }
16
- export declare function validateDiscussOptions(optionSlice: unknown): DiscussOptions;
17
- export declare function createDiscussRuntimeOptions({ captainOptions, players, }: CreateDiscussRuntimeOptions): PlaybookRuntimeOptions;
18
- export declare function discussSavedCountsLine(counts: {
19
- interruptions: number;
20
- copyPastes: number;
21
- }, rounds: number): string;
22
- export declare const discussSummaryPolicy: {
23
- stateCountLabels: {
24
- readonly initialProposalRound: "proposal round";
25
- readonly reconciliationRound: "proposal round";
26
- readonly reviewSpecInitialCommit: "review round";
27
- readonly reviewSpecHostChanges: "review round";
28
- readonly reviewDrInitialCommit: "review round";
29
- readonly reviewDrHostChanges: "review round";
30
- readonly reviewMixedInitialCommit: "review round";
31
- readonly reviewMixedHostChanges: "review round";
32
- };
33
- copyPasteGuardNames: readonly ["proposalMade", "findingsRaised", "rebuttalsRaised", "rebuttalsAddressed", "changesMade"];
34
- savedCountsLine: typeof discussSavedCountsLine;
35
- };
36
- export declare const discussPlaybookRegistryEntry: {
37
- id: string;
38
- command: string;
39
- intent: string;
40
- requiredRoleIds: string[];
41
- summaryPolicy: {
42
- stateCountLabels: {
43
- readonly initialProposalRound: "proposal round";
44
- readonly reconciliationRound: "proposal round";
45
- readonly reviewSpecInitialCommit: "review round";
46
- readonly reviewSpecHostChanges: "review round";
47
- readonly reviewDrInitialCommit: "review round";
48
- readonly reviewDrHostChanges: "review round";
49
- readonly reviewMixedInitialCommit: "review round";
50
- readonly reviewMixedHostChanges: "review round";
51
- };
52
- copyPasteGuardNames: readonly ["proposalMade", "findingsRaised", "rebuttalsRaised", "rebuttalsAddressed", "changesMade"];
53
- savedCountsLine: typeof discussSavedCountsLine;
54
- };
55
- validateOptions: typeof validateDiscussOptions;
56
- createRuntime(options: CreateDiscussRuntimeOptions): PlaybookRuntime;
57
- };
58
- export default discussPlaybookRegistryEntry;
@@ -1,97 +0,0 @@
1
- // SPDX-License-Identifier: Apache-2.0
2
- // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
3
- import createPlaybookRuntime from './discuss.playbook.js';
4
- const DISCUSS_OPTION_KEYS = new Set(['committer']);
5
- const COMMITTER_PLAYER_IDS = new Set(['host', 'participant']);
6
- export function validateDiscussOptions(optionSlice) {
7
- if (optionSlice === undefined)
8
- return {};
9
- if (typeof optionSlice !== 'object' ||
10
- optionSlice === null ||
11
- Array.isArray(optionSlice)) {
12
- throw new Error('captain.options.playbooks.discuss.options must be an object');
13
- }
14
- const slice = optionSlice;
15
- for (const key of Object.keys(slice)) {
16
- if (!DISCUSS_OPTION_KEYS.has(key)) {
17
- throw new Error(`Unknown config field captain.options.playbooks.discuss.options.${key}`);
18
- }
19
- }
20
- const options = {};
21
- const committer = slice.committer;
22
- if (committer !== undefined) {
23
- if (typeof committer !== 'string' || !COMMITTER_PLAYER_IDS.has(committer)) {
24
- throw new Error("captain.options.playbooks.discuss.options.committer must be " +
25
- "'host' or 'participant'");
26
- }
27
- options.committer = committer;
28
- }
29
- return options;
30
- }
31
- function playerIdentity(players, id) {
32
- const entry = players.find((p) => p.id === id);
33
- return entry?.model ?? entry?.adapter;
34
- }
35
- export function createDiscussRuntimeOptions({ captainOptions, players, }) {
36
- const discussOptions = validateDiscussOptions(captainOptions);
37
- const options = {
38
- host: playerIdentity(players, 'host'),
39
- participant: playerIdentity(players, 'participant'),
40
- };
41
- if (discussOptions.committer !== undefined) {
42
- options.committer = discussOptions.committer;
43
- }
44
- return options;
45
- }
46
- // CAPTAIN-19/20: the DISCUSS turn-summary policy — counted round states,
47
- // the payload-carrying guards whose content Boss would otherwise relay
48
- // between the players by hand, and the saved-counts wording — so the shell
49
- // reports how many interruptions a run saved.
50
- const discussStateCountLabels = {
51
- initialProposalRound: 'proposal round',
52
- reconciliationRound: 'proposal round',
53
- reviewSpecInitialCommit: 'review round',
54
- reviewSpecHostChanges: 'review round',
55
- reviewDrInitialCommit: 'review round',
56
- reviewDrHostChanges: 'review round',
57
- reviewMixedInitialCommit: 'review round',
58
- reviewMixedHostChanges: 'review round',
59
- };
60
- const discussCopyPasteGuardNames = [
61
- 'proposalMade',
62
- 'findingsRaised',
63
- 'rebuttalsRaised',
64
- 'rebuttalsAddressed',
65
- 'changesMade',
66
- ];
67
- function countNoun(count, singular, plural = `${singular}s`) {
68
- return `${count} ${count === 1 ? singular : plural}`;
69
- }
70
- export function discussSavedCountsLine(counts, rounds) {
71
- return [
72
- 'Saved you',
73
- countNoun(counts.interruptions, 'interruption'),
74
- 'and',
75
- countNoun(counts.copyPastes, 'copy-paste'),
76
- 'across',
77
- countNoun(rounds, 'round'),
78
- 'of proposals/reviews.',
79
- ].join(' ');
80
- }
81
- export const discussSummaryPolicy = {
82
- stateCountLabels: discussStateCountLabels,
83
- copyPasteGuardNames: discussCopyPasteGuardNames,
84
- savedCountsLine: discussSavedCountsLine,
85
- };
86
- export const discussPlaybookRegistryEntry = {
87
- id: 'discuss',
88
- command: 'discuss',
89
- intent: 'design discussion: two agents converge on spec items or decision records',
90
- requiredRoleIds: ['host', 'participant'],
91
- summaryPolicy: discussSummaryPolicy,
92
- validateOptions: validateDiscussOptions,
93
- createRuntime(options) {
94
- return createPlaybookRuntime(createDiscussRuntimeOptions(options));
95
- },
96
- };
97
- export default discussPlaybookRegistryEntry;