@niwa-labs/pstack 0.0.0-stage → 0.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 (163) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +260 -2
  3. package/package.json +28 -4
  4. package/scripts/upstream-map.ts +90 -0
  5. package/src/author.ts +57 -0
  6. package/src/binding.ts +32 -0
  7. package/src/catalog.ts +86 -0
  8. package/src/composition.ts +66 -0
  9. package/src/index.ts +50 -0
  10. package/src/mapping/analyze.ts +223 -0
  11. package/src/mapping/assemble.ts +96 -0
  12. package/src/mapping/diff.ts +139 -0
  13. package/src/mapping/format.ts +67 -0
  14. package/src/mapping/git.ts +69 -0
  15. package/src/mapping/index.ts +18 -0
  16. package/src/mapping/maintain.ts +36 -0
  17. package/src/mapping/schema.ts +50 -0
  18. package/src/mapping/sources.ts +108 -0
  19. package/src/mapping/tool.ts +77 -0
  20. package/src/mapping/verify.ts +130 -0
  21. package/src/plugin.ts +136 -0
  22. package/src/policy.ts +115 -0
  23. package/src/ports.ts +184 -0
  24. package/src/pr-binding.ts +88 -0
  25. package/src/records.ts +61 -0
  26. package/src/roles.ts +49 -0
  27. package/src/trunk.ts +59 -0
  28. package/src/upstream-actions.ts +135 -0
  29. package/src/upstream-records.ts +71 -0
  30. package/src/upstream.ts +151 -0
  31. package/src/workflows/adapted.md +780 -0
  32. package/src/workflows/authoring-a-skill.ts +52 -0
  33. package/src/workflows/autonomous-run.ts +56 -0
  34. package/src/workflows/autopilot-full.ts +90 -0
  35. package/src/workflows/autopilot-stack.ts +125 -0
  36. package/src/workflows/babysit.ts +124 -0
  37. package/src/workflows/benny-reproduce.ts +122 -0
  38. package/src/workflows/benny-triage.ts +89 -0
  39. package/src/workflows/bug-fix.ts +54 -0
  40. package/src/workflows/entry.ts +130 -0
  41. package/src/workflows/eval.ts +63 -0
  42. package/src/workflows/feature.ts +54 -0
  43. package/src/workflows/hillclimb.ts +78 -0
  44. package/src/workflows/investigation.ts +41 -0
  45. package/src/workflows/lib/catalog.ts +45 -0
  46. package/src/workflows/lib/change.ts +70 -0
  47. package/src/workflows/lib/forensics.ts +37 -0
  48. package/src/workflows/lib/git.ts +30 -0
  49. package/src/workflows/lib/go.ts +58 -0
  50. package/src/workflows/lib/inputs.ts +34 -0
  51. package/src/workflows/lib/lane.ts +170 -0
  52. package/src/workflows/lib/measure.ts +34 -0
  53. package/src/workflows/lib/plan.ts +24 -0
  54. package/src/workflows/lib/script.ts +79 -0
  55. package/src/workflows/lib/ship.ts +110 -0
  56. package/src/workflows/lib/texts.ts +18 -0
  57. package/src/workflows/lib/trunk.ts +91 -0
  58. package/src/workflows/multi-phase-plan.ts +83 -0
  59. package/src/workflows/opening-a-pr.ts +62 -0
  60. package/src/workflows/pause-safely.ts +50 -0
  61. package/src/workflows/perf-issue.ts +87 -0
  62. package/src/workflows/prototype.ts +76 -0
  63. package/src/workflows/refactoring.ts +54 -0
  64. package/src/workflows/runtime-forensics.ts +26 -0
  65. package/src/workflows/scenarios.ts +380 -0
  66. package/src/workflows/session-pickup.ts +57 -0
  67. package/src/workflows/shipping.ts +63 -0
  68. package/src/workflows/suite.ts +129 -0
  69. package/src/workflows/texts/authoring-a-skill.json +5 -0
  70. package/src/workflows/texts/autonomous-run.json +5 -0
  71. package/src/workflows/texts/autopilot-full.json +5 -0
  72. package/src/workflows/texts/autopilot-stack.json +5 -0
  73. package/src/workflows/texts/babysit.json +5 -0
  74. package/src/workflows/texts/benny-reproduce.json +5 -0
  75. package/src/workflows/texts/benny-triage.json +5 -0
  76. package/src/workflows/texts/bug-fix.json +5 -0
  77. package/src/workflows/texts/bugbot-triage.json +5 -0
  78. package/src/workflows/texts/eval.json +5 -0
  79. package/src/workflows/texts/feature.json +5 -0
  80. package/src/workflows/texts/hillclimb.json +5 -0
  81. package/src/workflows/texts/investigation.json +5 -0
  82. package/src/workflows/texts/multi-phase-plan.json +5 -0
  83. package/src/workflows/texts/opening-a-pr.json +5 -0
  84. package/src/workflows/texts/pause-safely.json +5 -0
  85. package/src/workflows/texts/perf-issue.json +5 -0
  86. package/src/workflows/texts/prototype.json +5 -0
  87. package/src/workflows/texts/refactoring.json +5 -0
  88. package/src/workflows/texts/runtime-forensics.json +5 -0
  89. package/src/workflows/texts/session-pickup.json +5 -0
  90. package/src/workflows/texts/trace-forensics.json +5 -0
  91. package/src/workflows/texts/visual-parity.json +5 -0
  92. package/src/workflows/texts/worker.json +5 -0
  93. package/src/workflows/trace-forensics.ts +27 -0
  94. package/src/workflows/upstream-sync.ts +182 -0
  95. package/src/workflows/visual-parity.ts +52 -0
  96. package/src/workflows/worktree-cleanup.ts +57 -0
  97. package/test/author.test.ts +61 -0
  98. package/test/benny.test.ts +138 -0
  99. package/test/binding.test.ts +54 -0
  100. package/test/catalog-helpers.test.ts +49 -0
  101. package/test/closure.test.ts +45 -0
  102. package/test/composition.test.ts +23 -0
  103. package/test/eval.test.ts +23 -0
  104. package/test/lanes.test.ts +334 -0
  105. package/test/mapping-diff.test.ts +64 -0
  106. package/test/mapping-support.ts +110 -0
  107. package/test/mapping-texts.test.ts +106 -0
  108. package/test/mapping.test.ts +276 -0
  109. package/test/package-layout.ts +68 -0
  110. package/test/policy.test.ts +98 -0
  111. package/test/ports.test.ts +45 -0
  112. package/test/ports.ts +173 -0
  113. package/test/roles.test.ts +21 -0
  114. package/test/suite.test.ts +167 -0
  115. package/test/support.ts +541 -0
  116. package/test/texts.test.ts +174 -0
  117. package/test/tool.test.ts +48 -0
  118. package/test/trunk-helpers.test.ts +149 -0
  119. package/test/trunk.test.ts +24 -0
  120. package/test/upstream-sync.test.ts +246 -0
  121. package/test/upstream.test.ts +106 -0
  122. package/test/worktree-cleanup.test.ts +107 -0
  123. package/tsconfig.json +7 -0
  124. package/upstream/LICENSE +21 -0
  125. package/upstream/SOURCE.json +5 -0
  126. package/upstream/benny/FOR_AGENTS.md +89 -0
  127. package/upstream/benny/README.md +23 -0
  128. package/upstream/benny/skills/reproduce-and-fix-issues/SKILL.md +310 -0
  129. package/upstream/benny/skills/reproduce-and-fix-issues/references/control-adapter.md +169 -0
  130. package/upstream/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md +205 -0
  131. package/upstream/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md +93 -0
  132. package/upstream/benny/skills/setup-benny/SKILL.md +265 -0
  133. package/upstream/benny/skills/triage-issue-reports/SKILL.md +240 -0
  134. package/upstream/benny/skills/triage-issue-reports/references/routing.example.md +61 -0
  135. package/upstream/benny/templates/configuration.example.yaml +84 -0
  136. package/upstream/benny/templates/reproduce-automation-prompt.md +33 -0
  137. package/upstream/benny/templates/triage-automation-prompt.md +39 -0
  138. package/upstream/mapping.json +699 -0
  139. package/upstream/poteto-mode/SKILL.md +110 -0
  140. package/upstream/poteto-mode/playbooks/authoring-a-skill.md +12 -0
  141. package/upstream/poteto-mode/playbooks/autonomous-run.md +13 -0
  142. package/upstream/poteto-mode/playbooks/autopilot-full.md +25 -0
  143. package/upstream/poteto-mode/playbooks/autopilot-stack.md +8 -0
  144. package/upstream/poteto-mode/playbooks/babysit.md +10 -0
  145. package/upstream/poteto-mode/playbooks/bug-fix.md +15 -0
  146. package/upstream/poteto-mode/playbooks/eval.md +25 -0
  147. package/upstream/poteto-mode/playbooks/feature.md +21 -0
  148. package/upstream/poteto-mode/playbooks/hillclimb.md +21 -0
  149. package/upstream/poteto-mode/playbooks/investigation.md +14 -0
  150. package/upstream/poteto-mode/playbooks/multi-phase-plan.md +11 -0
  151. package/upstream/poteto-mode/playbooks/opening-a-pr.md +9 -0
  152. package/upstream/poteto-mode/playbooks/pause-safely.md +10 -0
  153. package/upstream/poteto-mode/playbooks/perf-issue.md +25 -0
  154. package/upstream/poteto-mode/playbooks/prototype.md +14 -0
  155. package/upstream/poteto-mode/playbooks/refactoring.md +16 -0
  156. package/upstream/poteto-mode/playbooks/runtime-forensics.md +11 -0
  157. package/upstream/poteto-mode/playbooks/session-pickup.md +11 -0
  158. package/upstream/poteto-mode/playbooks/shipping.md +12 -0
  159. package/upstream/poteto-mode/playbooks/trace-forensics.md +14 -0
  160. package/upstream/poteto-mode/playbooks/visual-parity.md +11 -0
  161. package/upstream/poteto-mode/playbooks/worktree-cleanup.md +12 -0
  162. package/upstream/poteto-mode/references/bugbot-triage.md +142 -0
  163. package/upstream/poteto-mode/worker.md +11 -0
@@ -0,0 +1,380 @@
1
+ /**
2
+ * The scenarios the suite runs before it promotes a set of built-ins.
3
+ *
4
+ * The scenarios run in this order, each on the version of its built-in that the set under trial holds, and may hand
5
+ * what one produced to the next: a plan written by one is carried out by the next. They work on the suite's fixture,
6
+ * a repository the suite may change on a forge project it may merge into. Every gated built-in has a scenario: a
7
+ * candidate with none is not promoted.
8
+ */
9
+
10
+ import { GO, goDigest, goSubject } from "../policy.ts";
11
+ import { api } from "./lib/script.ts";
12
+
13
+ /** What the suite is started on: a repository it may work in, and the versions of the set it tries. */
14
+ export interface Fixture {
15
+ repo: { host: string; path: string; local: string };
16
+ worktrees: string;
17
+ base: string;
18
+ /** The version the suite tries of each built-in, by name. */
19
+ /** A name that is new to each run of the suite, for the plans its scenarios write. */
20
+ run: string;
21
+ }
22
+
23
+ /** What the scenarios hand on to the ones after them. */
24
+ export type Context = Record<string, unknown>;
25
+
26
+ /** How a run of a built-in ended. */
27
+ export type Ended = { ok: true; value: unknown } | { ok: false; error: { name: string; message: string } };
28
+
29
+ /** Built-ins a pstack plugin offers only when it is asked to: their scenarios are skipped when they are not registered. */
30
+ export const OPTIONAL = new Set(["benny-triage", "benny-reproduce"]);
31
+
32
+ /** A scenario: the built-in it runs, its name, the input it gives, and why its outcome fails, or null when it passes. */
33
+ export interface Scenario {
34
+ builtin: string;
35
+ name: string;
36
+ args(fixture: Fixture, context: Context): unknown | Promise<unknown>;
37
+ check(ended: Ended, context: Context): string | null;
38
+ /** What the scenario seeded and no longer needs, removed once its outcome was checked. */
39
+ after?(fixture: Fixture, context: Context): Promise<void>;
40
+ }
41
+
42
+ /** The value of a run that ended well, or why it did not. */
43
+ function valueOf(ended: Ended): { value: Record<string, any> } | { failed: string } {
44
+ if (!ended.ok) return { failed: `the run failed: ${ended.error.name}: ${ended.error.message}` };
45
+ if (typeof ended.value !== "object" || ended.value === null) return { failed: `the run answered ${JSON.stringify(ended.value)}` };
46
+ return { value: ended.value as Record<string, any> };
47
+ }
48
+
49
+ /** A check that the run answered a status, and whatever else `more` wants of the value. */
50
+ function answered(status: string, more: (value: Record<string, any>, context: Context) => string | null = () => null): Scenario["check"] {
51
+ return (ended, context) => {
52
+ const got = valueOf(ended);
53
+ if ("failed" in got) return got.failed;
54
+ if (got.value["status"] !== status) return `the run answered status ${JSON.stringify(got.value["status"])}, not ${status}: ${JSON.stringify(got.value).slice(0, 500)}`;
55
+ return more(got.value, context);
56
+ };
57
+ }
58
+
59
+ const playbook = (f: Fixture, task: string) => ({ task, repo: f.repo, worktrees: f.worktrees, base: f.base });
60
+
61
+ /** A plan a scenario wrote: its revision and nodes. */
62
+ interface Written {
63
+ plan: { of: string; rev: number };
64
+ nodes: Array<{ id: string; after: string[] }>;
65
+ }
66
+
67
+ /**
68
+ * Give the go on every node of a plan the suite's own scenario wrote, as a run may: the suite stands in for the owner
69
+ * on the plans of its fixture, and on nothing else.
70
+ */
71
+ async function goOn(key: string, f: Fixture, written: Written): Promise<void> {
72
+ const change = `${f.repo.host}/${f.repo.path}`;
73
+ for (const node of written.nodes) {
74
+ await api().call(
75
+ "evidence.attest",
76
+ { subject: goSubject(written.plan, node.id), claim: { kind: "verdict", name: GO, outcome: "pass", sha: goDigest(written.plan, node.id, change) } },
77
+ { label: `${key}-go-${node.id}` },
78
+ );
79
+ }
80
+ }
81
+
82
+ const written = (context: Context, key: string): Written => {
83
+ const found = context[key] as Written | undefined;
84
+ if (found === undefined) throw new Error(`no plan was written for ${key} by an earlier scenario`);
85
+ return found;
86
+ };
87
+
88
+ export const SCENARIOS: readonly Scenario[] = [
89
+ {
90
+ builtin: "entry",
91
+ name: "routes a question to the investigation",
92
+ args: (f) => ({ request: "Where does this repository describe itself?", repo: f.repo, worktrees: f.worktrees, base: f.base }),
93
+ check: answered("ran", (value) => (value["playbook"] === "investigation" ? null : `the entry ran ${JSON.stringify(value["playbook"])}, not the investigation`)),
94
+ },
95
+ {
96
+ builtin: "investigation",
97
+ name: "answers with sources",
98
+ args: (f) => playbook(f, "Where does this repository describe itself?"),
99
+ check: answered("answered", (value) => ((value["answer"]?.sources ?? []).length > 0 ? null : "the answer cites no source")),
100
+ },
101
+ {
102
+ builtin: "multi-phase-plan",
103
+ name: "writes a plan of two independent pull requests",
104
+ args: (f) => ({ ...playbook(f, "Add a changelog and a contributing guide, each in its own pull request."), plan: `suite/${f.run}/parallel`, ask: false }),
105
+ check: answered("planned", (value, context) => {
106
+ if ((value["nodes"] ?? []).length < 2) return "the plan has fewer than two nodes";
107
+ context["parallel"] = value;
108
+ return null;
109
+ }),
110
+ },
111
+ {
112
+ builtin: "autopilot-full",
113
+ name: "checks the landing precondition for every verified plan node",
114
+ args: async (f, context) => {
115
+ await goOn("parallel", f, written(context, "parallel"));
116
+ return { ...playbook(f, "Carry out the plan."), plan: written(context, "parallel").plan.of };
117
+ },
118
+ check: answered("done", (value, context) => {
119
+ const nodes = value["nodes"] as Array<{ node: string; pr: number; head: string; verified: boolean; go: boolean; landed?: { outcome: string; missing?: Array<{ name: string; why: string }> } }>;
120
+ context["landed"] = nodes.filter(one => one.landed?.outcome === "merged");
121
+ context["verifiedForCleanup"] = nodes.filter(one => one.verified && one.go);
122
+ return nodes.length > 0 && nodes.every(one => one.verified && one.go && gatedLanding(one.landed)) ? null : "an unverified pair reached landing, or a verified pair failed for an unexpected reason";
123
+ }),
124
+ },
125
+ {
126
+ builtin: "multi-phase-plan",
127
+ name: "writes a stack of two pull requests",
128
+ args: (f) => ({ ...playbook(f, "Add a settings module, then a page that uses it, the page building on the module."), plan: `suite/${f.run}/stack`, ask: false }),
129
+ check: answered("planned", (value, context) => {
130
+ const nodes = value["nodes"] as Array<{ after: string[] }>;
131
+ if (!nodes.some((one) => one.after.length > 0)) return "the plan stacks no node on another";
132
+ context["stack"] = value;
133
+ return null;
134
+ }),
135
+ },
136
+ {
137
+ builtin: "autopilot-stack",
138
+ name: "stacks and verifies without merging",
139
+ args: (f, context) => ({ ...playbook(f, "Carry out the plan."), plan: written(context, "stack").plan.of }),
140
+ check: answered("verified", (value, context) => {
141
+ const nodes = value["nodes"] as Array<{ node: string; pr: number; base: string; verified: boolean; author: unknown }>;
142
+ if (nodes.length < 2 || !nodes.every((one) => one.verified)) return `not every node verified: ${JSON.stringify(nodes).slice(0, 500)}`;
143
+ if (!nodes.slice(1).some((one) => one.base !== "main")) return "no pull request was stacked on another";
144
+ context["stacked"] = nodes;
145
+ return null;
146
+ }),
147
+ },
148
+ {
149
+ builtin: "shipping",
150
+ name: "stops before landing a stack on a forge without a target precondition",
151
+ args: async (f, context) => {
152
+ const plan = written(context, "stack");
153
+ await goOn("stack", f, plan);
154
+ const [bottom] = context["stacked"] as Array<{ node: string; pr: number; author: unknown }>;
155
+ if (bottom === undefined) throw new Error("no stack was verified by an earlier scenario");
156
+ return { ...playbook(f, "Land the bottom of the stack."), plan: plan.plan.of, prs: [{ number: bottom.pr, nodes: [bottom.node], author: bottom.author }] };
157
+ },
158
+ check: answered("stopped", value => gatedLanding(value["prs"]?.[0]) ? null : "expected refusal of an unconditioned merge"),
159
+ },
160
+ {
161
+ builtin: "worktree-cleanup",
162
+ name: "keeps a registered checkout until the forge has recorded its merge",
163
+ args: async (f, context) => {
164
+ const candidate = (context["verifiedForCleanup"] as Array<{ pr: number; head: string }> | undefined)?.[0]
165
+ ?? (context["landed"] as Array<{ pr: number; head: string }> | undefined)?.[0];
166
+ if (candidate === undefined) throw new Error("no pull request was verified by an earlier scenario");
167
+ const { host, path } = f.repo;
168
+ const { binding } = await api().call("pstack.pr.binding", { repo: { host, path }, number: candidate.pr, head: candidate.head }, { label: "cleanup-fixture" }) as {
169
+ binding?: { worktree: { id: string } };
170
+ };
171
+ if (binding === undefined) throw new Error("no checkout was recorded for the fixture pull request");
172
+ context["cleanupCheckout"] = { id: binding.worktree.id, head: candidate.head };
173
+ return {
174
+ id: "suite-unobserved",
175
+ type: "forge.pr.merged",
176
+ data: {
177
+ pr: { repo: { host, path, projectId: 1 }, number: candidate.pr },
178
+ base: f.base,
179
+ head: candidate.head,
180
+ source: { kind: "observed", version: 1 },
181
+ },
182
+ };
183
+ },
184
+ check: (ended) => {
185
+ const got = valueOf(ended);
186
+ if ("failed" in got) return got.failed;
187
+ if (!Array.isArray(got.value["removed"]) || got.value["removed"].length !== 0) {
188
+ return `removed a checkout without a forge observation: ${JSON.stringify(got.value)}`;
189
+ }
190
+ return null;
191
+ },
192
+ after: async (_f, context) => {
193
+ const expected = context["cleanupCheckout"] as { id: string; head: string };
194
+ const result = await api().call("git.worktree.get", { id: expected.id }, { label: "cleanup-checkout-kept" }) as { head?: string };
195
+ if (result.head !== expected.head) throw new Error(`the fixture checkout ${expected.id} was changed or removed`);
196
+ },
197
+ },
198
+ {
199
+ builtin: "opening-a-pr",
200
+ name: "makes the top of the stack ready for review",
201
+ args: (f, context) => ({ ...playbook(f, "Open the page's pull request."), branch: top(context).branch, number: top(context).pr }),
202
+ check: answered("opened", (value, context) => (value["pr"] === top(context).pr ? null : `opened ${JSON.stringify(value["pr"])}, not the branch's own pull request`)),
203
+ },
204
+ {
205
+ builtin: "babysit",
206
+ name: "checks the top of the stack and finds it ready",
207
+ args: (f, context) => ({ ...playbook(f, "Watch the page's pull request."), pr: top(context).pr, mode: "check" }),
208
+ check: answered("merge-ready"),
209
+ },
210
+ {
211
+ builtin: "pause-safely",
212
+ name: "checkpoints the top of the stack's worktree",
213
+ args: (f, context) => ({ ...playbook(f, "Pause the page's work."), worktree: top(context).worktree }),
214
+ check: answered("paused", (value) => (value["clean"] === true ? null : "the worktree was left with uncommitted work")),
215
+ },
216
+ {
217
+ builtin: "session-pickup",
218
+ name: "picks the first plan up from its trail",
219
+ args: (f) => ({ ...playbook(f, "Where does the work stand?"), plan: `suite/${f.run}/parallel` }),
220
+ check: answered("picked-up"),
221
+ },
222
+ ...(["trace-forensics", "runtime-forensics"] as const).map(
223
+ (builtin): Scenario => ({
224
+ builtin,
225
+ name: "holds hypotheses against evidence",
226
+ args: (f) => ({ ...playbook(f, "The README describes the service wrongly: why?"), ...(builtin === "trace-forensics" ? { trace: "README.md" } : {}) }),
227
+ check: (ended) => {
228
+ const got = valueOf(ended);
229
+ if ("failed" in got) return got.failed;
230
+ return (got.value["hypotheses"] ?? []).length > 0 ? null : "no hypothesis was held";
231
+ },
232
+ }),
233
+ ),
234
+ ...(["bug-fix", "feature", "refactoring", "authoring-a-skill", "visual-parity", "perf-issue"] as const).map(
235
+ (builtin): Scenario => ({
236
+ builtin,
237
+ name: "carries a change to a verified pull request",
238
+ args: (f) => playbook(f, `A small ${builtin} on the README of the fixture.`),
239
+ check: answered("verified", (value) => (builtin === "perf-issue" && value["after"] === null ? "the fix was not measured" : null)),
240
+ }),
241
+ ),
242
+ {
243
+ builtin: "autonomous-run",
244
+ name: "drives a change until its predicate holds",
245
+ args: (f) => ({ ...playbook(f, "Add a change note."), predicate: "ls change-*.md >/dev/null 2>&1", max: 3 }),
246
+ check: answered("met"),
247
+ },
248
+ {
249
+ builtin: "hillclimb",
250
+ name: "keeps changes that move the metric",
251
+ args: (f) => ({ ...playbook(f, "Add change notes."), metric: "ls change-*.md 2>/dev/null | wc -l", direction: "higher", target: 2, min: 2, max: 4 }),
252
+ check: answered("reached"),
253
+ },
254
+ {
255
+ builtin: "prototype",
256
+ name: "settles a decision with variants",
257
+ args: (f) => playbook(f, "Should the README lead with usage or with the architecture?"),
258
+ check: answered("decided", (value) => ((value["variants"] ?? []).length >= 2 ? null : "fewer than two variants were built")),
259
+ },
260
+ {
261
+ builtin: "eval",
262
+ name: "grades two variants blind",
263
+ args: async (f) => {
264
+ const seats = (await api().call("pstack.roles", {}, { label: "eval-roles" })) as { lead: { harness: string }; reviewer: { harness: string } };
265
+ return { ...playbook(f, "Which seat explains the README better?"), variants: { lead: seats.lead.harness, reviewer: seats.reviewer.harness } };
266
+ },
267
+ check: answered("judged", (value) => (Object.keys(value["table"] ?? {}).length === 2 ? null : "not every variant was graded")),
268
+ },
269
+ {
270
+ builtin: "upstream-sync",
271
+ name: "carries the map of a reworded upstream to its new snapshot",
272
+ args: (f, context) => seedSync(f, context),
273
+ check: answered("synced", (value) => {
274
+ if (value["summary"]?.touched !== 0 || value["summary"]?.textProblems !== 0) return `the map was not settled: ${JSON.stringify(value["summary"])}`;
275
+ return (value["changed"] ?? []).some((file: string) => file.endsWith("texts/worker.json")) ? null : "the texts were not assembled from the map";
276
+ }),
277
+ after: async (_f, context) => {
278
+ const seeded = context["sync"] as { up: string; pkg: string } | undefined;
279
+ if (seeded === undefined) return;
280
+ for (const id of [seeded.pkg, seeded.up]) await api().call("git.worktree.remove", { id, force: true }, { label: `sync-clean-${id}` });
281
+ },
282
+ },
283
+ {
284
+ builtin: "benny-triage",
285
+ name: "triages a bug report as a bug",
286
+ args: (f) => ({ id: "suite", type: "benny.reported", data: { report: REPORT, repo: f.repo, worktrees: f.worktrees, base: f.base } }),
287
+ check: (ended, context) => {
288
+ const got = valueOf(ended);
289
+ if ("failed" in got) return got.failed;
290
+ if (got.value["verdict"] !== "bug") return `the report was triaged as ${JSON.stringify(got.value["verdict"])}`;
291
+ context["triaged"] = got.value;
292
+ return null;
293
+ },
294
+ },
295
+ {
296
+ builtin: "benny-reproduce",
297
+ name: "reproduces a triaged bug and fixes it in a draft",
298
+ args: (f, context) => {
299
+ const triaged = context["triaged"] as Record<string, unknown> | undefined;
300
+ if (triaged === undefined) throw new Error("no report was triaged by an earlier scenario");
301
+ return { id: "suite", type: "wf.pstack-benny-triage.triaged", data: { report: REPORT, ...triaged, repo: f.repo, worktrees: f.worktrees, base: f.base } };
302
+ },
303
+ check: answered("verified"),
304
+ },
305
+ ];
306
+
307
+ /** A tiny upstream pstack, as a checkout holds it, and the same one reworded: what the sync scenario carries the map across. */
308
+ const SYNC_UPSTREAM: Record<string, string> = {
309
+ LICENSE: "MIT License\n",
310
+ "skills/poteto-mode/SKILL.md": "# Mode\n\nAlpha block.\n",
311
+ "skills/poteto-mode/worker.md": "Work for the operator.\n",
312
+ "skills/poteto-mode/playbooks/bug-fix.md": "### Bug fix\n\nReproduce it.\n\nFix the cause.\n",
313
+ };
314
+ const SYNC_REWORDED = { "skills/poteto-mode/worker.md": "Work for the operator, always.\n" };
315
+
316
+ /** The files of the snapshot the checkout above gives, by their paths in it, and what the sync's map does with each. */
317
+ const SYNC_SNAPSHOT: Array<{ file: string; from: string; kind: "dropped" | "prompt" }> = [
318
+ { file: "poteto-mode/SKILL.md", from: "skills/poteto-mode/SKILL.md", kind: "dropped" },
319
+ { file: "poteto-mode/worker.md", from: "skills/poteto-mode/worker.md", kind: "prompt" },
320
+ { file: "poteto-mode/playbooks/bug-fix.md", from: "skills/poteto-mode/playbooks/bug-fix.md", kind: "prompt" },
321
+ ];
322
+
323
+ /** A worktree of the fixture's repository, for the scenario to seed. */
324
+ async function seedWorktree(key: string, f: Fixture, what: string): Promise<{ id: string; path: string; branch: string }> {
325
+ return (await api().call("git.worktree.create", { repo: f.repo.local, base: f.base, description: what }, { label: key })) as { id: string; path: string; branch: string };
326
+ }
327
+
328
+ /** Write a file in a worktree and answer nothing: a command in a box that writes only there. */
329
+ async function seedFile(key: string, cwd: string, file: string, text: string): Promise<void> {
330
+ const ran = (await api().call("proc.run", { cmd: ["sh", "-c", 'mkdir -p "$(dirname "$1")" && printf %s "$2" > "$1"', "sh", file, text], cwd, timeout: 60_000 }, { label: key })) as { exit: number | null; tail: string };
331
+ if (ran.exit !== 0) throw new Error(`${file} was not written in ${cwd}: ${ran.tail.slice(-300)}`);
332
+ }
333
+
334
+ /** Commit what is under `paths` in a seeded worktree, on the host (the plugin's own step): the commit. */
335
+ async function seedCommit(key: string, place: string, message: string, paths: string[]): Promise<string> {
336
+ return ((await api().call("pstack.upstream.commit", { place, message, paths }, { label: key })) as { head: string }).head;
337
+ }
338
+
339
+ /**
340
+ * What the sync scenario seeds: an upstream checkout of one worktree, and a branch of the fixture's repository whose
341
+ * package folder holds the snapshot of it and a map that covers the snapshot. Upstream is then reworded, so the sync has
342
+ * a real round of work: the entry that holds the reworded block is touched.
343
+ */
344
+ async function seedSync(f: Fixture, context: Context): Promise<unknown> {
345
+ const up = await seedWorktree("sync-up", f, "A tiny upstream pstack for the sync");
346
+ for (const [index, [file, text]] of Object.entries(SYNC_UPSTREAM).entries()) await seedFile(`sync-up-${String(index)}`, up.path, file, text);
347
+ const first = await seedCommit("sync-up-commit", up.path, "Upstream pstack", ["LICENSE", "skills"]);
348
+ const pkg = await seedWorktree("sync-pkg", f, "A tiny pstack package for the sync");
349
+ const oursCommit = ((await api().call("pstack.upstream.state", { place: pkg.path }, { label: "sync-pkg-head" })) as { head: string }).head;
350
+ await api().call("pstack.upstream.refresh", { place: pkg.path, checkout: up.path, commit: first, package: "packages/pstack" }, { label: "sync-pkg-snapshot" });
351
+ const entries = SYNC_SNAPSHOT.map((one, index) => {
352
+ const text = SYNC_UPSTREAM[one.from] as string;
353
+ const upstream = { commit: first, file: one.file, range: [0, text.length] };
354
+ return one.kind === "dropped"
355
+ ? { id: `skill:${String(index)}`, upstream, ours: [], kind: "dropped", note: "Not taken: a skill of Cursor's." }
356
+ : { id: `${one.file.split("/").at(-1)?.replace(/\.md$/, "") ?? one.file}:01`, upstream, ours: [{ commit: oursCommit, file: "README.md", range: [0, 1] }], kind: "prompt" };
357
+ });
358
+ await seedFile("sync-pkg-map", pkg.path, "packages/pstack/upstream/mapping.json", `${JSON.stringify({ entries }, null, 2)}\n`);
359
+ await seedCommit("sync-pkg-commit", pkg.path, "Snapshot and map", ["packages"]);
360
+ for (const [index, [file, text]] of Object.entries(SYNC_REWORDED).entries()) await seedFile(`sync-reword-${String(index)}`, up.path, file, text);
361
+ await seedCommit("sync-up-reword", up.path, "Reword upstream", ["skills"]);
362
+ context["sync"] = { up: up.id, pkg: pkg.id };
363
+ return { repo: { local: f.repo.local }, worktrees: f.worktrees, base: pkg.branch, upstream: { checkout: up.path } };
364
+ }
365
+
366
+ /** What Benny is handed in the scenarios: a report of a bug in the fixture. */
367
+ const REPORT = "The README calls the service payroll; it is the billing service.";
368
+
369
+ /** The top of the stack an earlier scenario verified. */
370
+ function top(context: Context): { pr: number; branch: string; worktree: string } {
371
+ const stacked = context["stacked"] as Array<{ pr: number; branch: string; worktree: string }> | undefined;
372
+ const found = stacked?.at(-1);
373
+ if (found === undefined) throw new Error("no stack was verified by an earlier scenario");
374
+ return found;
375
+ }
376
+
377
+ function gatedLanding(result?: { outcome: string; missing?: Array<{ name: string; why: string }> }): boolean {
378
+ return result?.outcome === "refused" && result.missing?.length === 1 && result.missing[0]?.name === "land"
379
+ && result.missing[0].why === "forge cannot condition a merge on the target commit";
380
+ }
@@ -0,0 +1,57 @@
1
+ // Session pickup: a cold start from the trail. The run reads what niwa keeps of the work, the plan and what was
2
+ // attested on it, and the lead answers where it stands, what is verified, and the first action; the trail is taken as
3
+ // it is, not proven again.
4
+
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { goSubject } from "../policy.ts";
8
+ import { playbookInput } from "./lib/inputs.ts";
9
+ import { HELPER_ACTIONS, api, roles, seatOptions, stepTag } from "./lib/script.ts";
10
+ import { brief } from "./lib/texts.ts";
11
+ import text from "./texts/session-pickup.json";
12
+
13
+ declare const workflow: ScriptApi["workflow"];
14
+ declare const z: ScriptApi["z"];
15
+ declare function phase(title: string): void;
16
+
17
+ const pickup = z.strictObject({
18
+ where: z.string().min(1).max(4000),
19
+ verified: z.array(z.string().max(1000)).max(30),
20
+ next: z.string().min(1).max(2000),
21
+ });
22
+
23
+ export default workflow(
24
+ {
25
+ name: "pstack-session-pickup",
26
+ description: "Pick up work from the trail niwa keeps of it",
27
+ input: playbookInput().extend({ plan: z.string().min(1).max(200).optional().describe("The plan the work follows, when it has one") }),
28
+ output: z.strictObject({ status: z.literal("picked-up"), plan: z.json().optional(), pickup }),
29
+ uses: ["pstack.roles", "session.start.*", "harness.list", "session.start", "session.ask", "session.end", "plan.get", "evidence.list"],
30
+ phases: [
31
+ { title: "Read", detail: "The plan and what was attested on it" },
32
+ { title: "Resume", detail: "Where it stands and the first action" },
33
+ ],
34
+ },
35
+ async ({ task, repo, plan: of }) => {
36
+ phase("Read");
37
+ const trail: string[] = [];
38
+ let plan: { of: string; rev: number; items: Array<{ id: string; text: string; state: string }> } | undefined;
39
+ if (of !== undefined) {
40
+ plan = (await api().call("plan.get", { of }, { label: "plan" })) as NonNullable<typeof plan>;
41
+ trail.push(`The plan ${plan.of}, revision ${String(plan.rev)}:`, ...plan.items.map((item) => `- ${item.id} (${item.state}): ${item.text}`));
42
+ for (const item of plan.items) {
43
+ const listed = (await api().call("evidence.list", { subject: goSubject(plan, item.id) }, { label: `go-${item.id}` })) as { items: unknown[] };
44
+ trail.push(`- ${item.id}: ${String(listed.items.length)} attestation(s) of the go on this revision`);
45
+ }
46
+ }
47
+ const recent = (await api().call("evidence.list", { limit: 50 }, { label: "evidence" })) as { items: Array<{ subject: string; claim: unknown; author: unknown }> };
48
+ trail.push("What was attested:", ...recent.items.map((one) => `- ${one.subject}: ${JSON.stringify(one.claim)} by ${JSON.stringify(one.author)}`));
49
+ phase("Resume");
50
+ const seats = await roles();
51
+ const got = await api().ask(
52
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: pickup, label: "resume", visible: HELPER_ACTIONS },
53
+ brief(stepTag("session-pickup", "resume"), text, task, ["The trail is authoritative: do not prove it again.", "", ...trail, "", "Answer where the work stands, what is verified, and the first action."]),
54
+ );
55
+ return { status: "picked-up" as const, ...(plan === undefined ? {} : { plan: plan as never }), pickup: got };
56
+ },
57
+ );
@@ -0,0 +1,63 @@
1
+ // Shipping: land a verified stack, bottom up, one pull request at a time, each under the merge policy at its current
2
+ // head; the first one the policy refuses stops the rest, which wait on it.
3
+
4
+ import { makeWorktree, removeWorktree } from "@niwa-labs/flow-code";
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { playbookInput } from "./lib/inputs.ts";
8
+ import { ship } from "./lib/ship.ts";
9
+ import type { Shipped } from "./lib/ship.ts";
10
+
11
+ declare const workflow: ScriptApi["workflow"];
12
+ declare const z: ScriptApi["z"];
13
+ declare function phase(title: string): void;
14
+
15
+ export default workflow(
16
+ {
17
+ name: "pstack-shipping",
18
+ description: "Land a verified stack bottom up under the merge policy",
19
+ input: playbookInput().extend({
20
+ plan: z.string().min(1).max(200).describe("The plan whose nodes the pull requests deliver"),
21
+ prs: z
22
+ .array(
23
+ z.strictObject({
24
+ number: z.number().int().positive(),
25
+ nodes: z.array(z.string().min(1)).min(1),
26
+ author: z.strictObject({ kind: z.literal("session"), harness: z.string(), id: z.string() }).optional().describe("Optional assertion of the author in the lane receipt"),
27
+ }),
28
+ )
29
+ .min(1)
30
+ .describe("The stack, bottom first"),
31
+ method: z.enum(["merge", "squash", "rebase"]).default("merge"),
32
+ }),
33
+ output: z.strictObject({ status: z.enum(["landed", "stopped"]), prs: z.array(z.json()) }),
34
+ uses: [
35
+ "git.worktree.create",
36
+ "git.worktree.get",
37
+ "git.worktree.remove",
38
+ "proc.run@{worktrees}/*",
39
+ "pstack.pr.binding",
40
+ "forge.pr.merge@{repo.host}/{repo.path}/pr/*",
41
+ "forge.pr.read@{repo.host}/{repo.path}",
42
+ "forge.pipeline.read@{repo.host}/{repo.path}",
43
+ "evidence.attest",
44
+ "evidence.covers",
45
+ "evidence.list",
46
+ "plan.get",
47
+ ],
48
+ phases: [{ title: "Land", detail: "Bottom up, one at a time" }],
49
+ },
50
+ async ({ repo, base, plan, prs, method }) => {
51
+ phase("Land");
52
+ // A checkout to read the patches against trunk in: the pull requests' heads are in the local clone.
53
+ const wt = await makeWorktree({ repo: repo.local, base, description: "Read the stack against trunk" });
54
+ const done: Shipped[] = [];
55
+ for (const one of prs) {
56
+ const landed = await ship(`pr-${String(one.number)}`, { repo, number: one.number, author: one.author, plan, nodes: one.nodes, cwd: wt.path, method });
57
+ done.push(landed);
58
+ if (landed.outcome !== "merged") break;
59
+ }
60
+ await removeWorktree(wt, true);
61
+ return { status: done.length === prs.length && done.every((one) => one.outcome === "merged") ? ("landed" as const) : ("stopped" as const), prs: done as never[] };
62
+ },
63
+ );
@@ -0,0 +1,129 @@
1
+ // The suite: before the host runs a new version of pstack's entry or playbooks, it runs the scenarios on the
2
+ // candidates, each started by its version, and promotes the whole set in one action when every scenario passes.
3
+ // The playbooks the entry starts are pinned to the set under trial, so the set is tried as it will run.
4
+
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { isRefusal, tryVersion } from "./lib/catalog.ts";
8
+ import { repoSchema } from "./lib/inputs.ts";
9
+ import { api } from "./lib/script.ts";
10
+ import { OPTIONAL, SCENARIOS } from "./scenarios.ts";
11
+ import type { Context, Ended, Fixture } from "./scenarios.ts";
12
+
13
+ declare const workflow: ScriptApi["workflow"];
14
+ declare const z: ScriptApi["z"];
15
+ declare function phase(title: string): void;
16
+
17
+ const row = z.strictObject({ builtin: z.string(), scenario: z.string(), passed: z.boolean(), why: z.string().optional() });
18
+
19
+ export default workflow(
20
+ {
21
+ name: "pstack-suite",
22
+ description: "Run the scenarios on candidate playbooks and promote them",
23
+ input: z.strictObject({
24
+ repo: repoSchema().describe("A repository the scenarios may change, on a forge project they may merge into"),
25
+ worktrees: z.string().min(1).describe("The real path of the folder niwa keeps its worktrees in, <home>/worktrees"),
26
+ base: z.string().min(1).default("main"),
27
+ }),
28
+ output: z.discriminatedUnion("status", [
29
+ z.strictObject({ status: z.literal("nothing"), why: z.string() }),
30
+ z.strictObject({ status: z.literal("promoted"), versions: z.array(z.strictObject({ builtin: z.string(), version: z.string() })), rows: z.array(row) }),
31
+ z.strictObject({ status: z.enum(["failed", "stale"]), rows: z.array(row) }),
32
+ ]),
33
+ uses: [
34
+ "workflow.builtin.trial",
35
+ "workflow.builtin.promote",
36
+ "pstack.pr.binding",
37
+ "forge.pr.merge@{repo.host}/{repo.path}/pr/*",
38
+ "pstack.pr.bind",
39
+ "forge.pr.ensure@{repo.host}/{repo.path}/pr/*",
40
+ "proc.run@{worktrees}/*",
41
+ "git.*@{repo.local}",
42
+ "git.worktree.create",
43
+ "git.worktree.get",
44
+ "git.worktree.list",
45
+ "git.worktree.remove",
46
+ "forge.pr.read@{repo.host}/{repo.path}",
47
+ "forge.checks.read@{repo.host}/{repo.path}",
48
+ "forge.pipeline.read@{repo.host}/{repo.path}",
49
+ "forge.comment.read@{repo.host}/{repo.path}",
50
+ "pstack.roles",
51
+ "session.start.*",
52
+ "harness.list",
53
+ "session.start",
54
+ "pstack.author.options",
55
+ "box.net@{repo.host}",
56
+ "session.ask",
57
+ "session.end",
58
+ "request.ask",
59
+ "workflow.list",
60
+ "workflow.start",
61
+ "niwa.records.read",
62
+ "workflow.cancel",
63
+ "evidence.attest",
64
+ "evidence.covers",
65
+ "evidence.list",
66
+ "plan.set",
67
+ "plan.get",
68
+ // The upstream sync's steps: the scenario seeds with some, and the sync, a child of the suite, calls them all.
69
+ "pstack.upstream.refresh",
70
+ "pstack.upstream.measure",
71
+ "pstack.upstream.record",
72
+ "pstack.upstream.assemble",
73
+ "pstack.upstream.commit",
74
+ "pstack.upstream.state",
75
+ // What Benny's two automations call through the owner's ports: a child run holds no more than the suite does.
76
+ "benny.tracker.*",
77
+ "benny.channel.*",
78
+ "benny.control.*",
79
+ ],
80
+ phases: [
81
+ { title: "Find", detail: "Which built-ins have a candidate version" },
82
+ { title: "Try", detail: "Each scenario runs on its candidate" },
83
+ { title: "Promote", detail: "The tried set is promoted in one action" },
84
+ ],
85
+ },
86
+ async ({ repo, worktrees, base }) => {
87
+ phase("Find");
88
+ const { entries } = (await api().call("workflow.builtin.trial", {}, { label: "pin" })) as {
89
+ entries: Array<{ name: string; workflow: string; version: string; candidate?: true }>;
90
+ };
91
+ const all = new Map(entries.map((entry) => [entry.name, entry]));
92
+ const candidates = entries.filter((entry) => entry.candidate === true);
93
+ if (candidates.length === 0) return { status: "nothing" as const, why: "no built-in of pstack has a candidate version" };
94
+ const fixture: Fixture = { repo, worktrees, base, run: String(await api().random({ label: "run" })).slice(2, 10) };
95
+
96
+ phase("Try");
97
+ const rows: Array<{ builtin: string; scenario: string; passed: boolean; why?: string }> = [];
98
+ for (const one of candidates) {
99
+ if (!SCENARIOS.some((scenario) => scenario.builtin === one.name)) rows.push({ builtin: one.name, scenario: "-", passed: false, why: "the built-in has no scenario" });
100
+ }
101
+ // Every scenario runs, on the version of the set under trial, in order: one hands its plan to the next.
102
+ const context: Context = {};
103
+ for (const [index, scenario] of SCENARIOS.entries()) {
104
+ const found = all.get(scenario.builtin);
105
+ if (found === undefined && OPTIONAL.has(scenario.builtin)) continue;
106
+ if (found === undefined) {
107
+ rows.push({ builtin: scenario.builtin, scenario: scenario.name, passed: false, why: "the built-in is not registered" });
108
+ continue;
109
+ }
110
+ const key = `try-${String(index)}`;
111
+ let ended: Ended;
112
+ try {
113
+ ended = await tryVersion(key, found.workflow, found.version, await scenario.args(fixture, context));
114
+ } catch (error) {
115
+ if (!isRefusal(error)) throw error;
116
+ ended = { ok: false, error: { name: (error as Error).name, message: (error as Error).message } };
117
+ }
118
+ const why = scenario.check(ended, context);
119
+ if (scenario.after !== undefined) await scenario.after(fixture, context);
120
+ rows.push({ builtin: scenario.builtin, scenario: scenario.name, passed: why === null, ...(why === null ? {} : { why }) });
121
+ }
122
+ if (rows.some((one) => !one.passed)) return { status: "failed" as const, rows };
123
+
124
+ phase("Promote");
125
+ const { status } = (await api().call("workflow.builtin.promote", {}, { label: "promote" })) as { status: "promoted" | "stale" };
126
+ if (status === "stale") return { status, rows };
127
+ return { status, versions: candidates.map((entry) => ({ builtin: entry.name, version: entry.version })), rows };
128
+ },
129
+ );
@@ -0,0 +1,5 @@
1
+ {
2
+ "name": "authoring-a-skill",
3
+ "title": "Authoring or modifying a skill",
4
+ "text": "### Authoring or modifying a skill\n\n**You own the skill's voice.**\n\n1. Write the skill as a SKILL.md with a `name` and a `description` in its frontmatter, in the folder of skills the repository keeps.\n2. Validate the skill: frontmatter has `name` and `description`, referenced files exist, cross-skill links resolve.\n3. Test cases if structural. Skip if subjective.\n4. Run **Opening a PR**.\n\nWhen in doubt, delete. Keep only prose that changes a decision. Tell it to do the thing and skip the reason. Explain only when the rule is confusing without one. Match tone to scope. Point at structural sources (types, READMEs, config) and encode a lesson in structure (a lint, a check or a script) rather than in more prose. Delegate to other skills by path. Don't restate. A workflow you keep hitting but isn't captured → propose a new skill.\n\n**Reply:** summary of the skill, key design decisions, validation notes.\n"
5
+ }
@@ -0,0 +1,5 @@
1
+ {
2
+ "name": "autonomous-run",
3
+ "title": "Autonomous run",
4
+ "text": "### Autonomous run\n\n**You own the exit condition. Define done, then drive to it without stopping.**\n\n1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero).\n2. Pick the wake mechanism with niwa's own means (a workflow that waits on a record, a timer that wakes it). An event to watch (CI, a merge, a ref advancing) gets a workflow that waits on the record of the event, with a long timer as fallback. No event gets a timer with a fixed interval sized to when the result is worth re-checking. When Niwa shows the session tools, use `harness.list` to choose an installation and `session.start` without a prompt. The helper joins this run and stays inside its launch limits. Ask a focused, read-only question with `session.ask`, using the returned session id and a schema for the finding. Use the same id for follow-ups and call `session.end` when finished. When the tools are absent, do the work yourself in small verified steps.\n3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that \"might help\" gets reverted, not left to ride.\n Sequence the work in small verifiable units, verifying each unit before the next instead of batching checks at the end.\n4. Mid-run discoveries that support the goal are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself through the playbooks. Put out-of-band fixes in their own PR. Do not park reversible work for the human or ask with `request.ask`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.\n5. Checkpoint every iteration: a row for what changed and whether the predicate moved.\n6. Stop when the predicate is met. A plateau is not a stop, so keep going and pivot your approach to push past it. Surface a genuine dead end rather than spinning, and never relax the predicate to declare victory.\n\n**Reply:** the exit condition, iterations run, what landed, what was discarded, final predicate state.\n"
5
+ }