@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,54 @@
1
+ // Bug fix: the lead reproduces the bug and narrows it to the cause the evidence leaves; the owner lane commits the
2
+ // failing repro before the fix, and verifiers that did not write it show the repro passing.
3
+
4
+ import type { ScriptApi } from "@niwa-labs/script";
5
+
6
+ import { change, changedSchema, frame, titleOf } from "./lib/change.ts";
7
+ import { playbookInput } from "./lib/inputs.ts";
8
+ import { roles } from "./lib/script.ts";
9
+ import text from "./texts/bug-fix.json";
10
+
11
+ declare const workflow: ScriptApi["workflow"];
12
+ declare const z: ScriptApi["z"];
13
+ declare function phase(title: string): void;
14
+
15
+ const framed = z.strictObject({ repro: z.string().min(1).max(4000), cause: z.string().min(1).max(4000), evidence: z.string().min(1).max(4000) });
16
+
17
+ export default workflow(
18
+ {
19
+ name: "pstack-bug-fix",
20
+ description: "Find a bug's cause and carry its fix to a pull request",
21
+ input: playbookInput(),
22
+ output: changedSchema().extend({ framed }),
23
+ uses: [
24
+ "pstack.roles",
25
+ "session.start.*",
26
+ "harness.list",
27
+ "session.start",
28
+ "session.ask",
29
+ "session.end",
30
+ "pstack.author.options",
31
+ "box.net@{repo.host}",
32
+ "git.worktree.create",
33
+ "proc.run@{worktrees}/*",
34
+ "pstack.pr.bind",
35
+ "forge.pr.ensure@{repo.host}/{repo.path}/pr/*",
36
+ "forge.pr.read@{repo.host}/{repo.path}",
37
+ "forge.pipeline.read@{repo.host}/{repo.path}",
38
+ "evidence.attest",
39
+ "evidence.covers",
40
+ ],
41
+ phases: [
42
+ { title: "Frame", detail: "The lead frames the work, read-only" },
43
+ { title: "Build", detail: "An owner lane carries it to a verified pull request" },
44
+ ],
45
+ },
46
+ async ({ task, repo, worktrees, base }) => {
47
+ const seats = await roles();
48
+ phase("Frame");
49
+ const got = await frame(text, { task, repo, roles: seats, schema: framed, ask: ["Reproduce the bug on the surface it shows on, and narrow it to the one cause runtime evidence leaves.", "Answer the repro, the cause, and the evidence that confirms it."] });
50
+ phase("Build");
51
+ const done = await change("change", { playbook: text, repo, base, worktrees, roles: seats, task, title: titleOf(task), extra: [`The repro: ${got.repro}`, `The cause: ${got.cause}`, "Commit the failing repro first, then the fix on top of it."] });
52
+ return { ...done, framed: got };
53
+ },
54
+ );
@@ -0,0 +1,130 @@
1
+ // The entry: the lead reads the request, picks the playbook it needs, and the entry runs that playbook as a child
2
+ // run with the same repository. Its rights are given by target templates, filled from the repository it is started
3
+ // on, so a run of the entry merges, opens pull requests and runs commands only there.
4
+
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { runBuiltin } from "./lib/catalog.ts";
8
+ import { repoSchema } from "./lib/inputs.ts";
9
+ import { api, roles, seatOptions, stepTag } from "./lib/script.ts";
10
+ import worker from "./texts/worker.json";
11
+
12
+ declare const workflow: ScriptApi["workflow"];
13
+ declare const z: ScriptApi["z"];
14
+ declare function phase(title: string): void;
15
+
16
+ /** The playbooks the lead may pick, with what each is for. */
17
+ const PLAYBOOKS = {
18
+ investigation: "a read-only question about the code, answered with sources",
19
+ "trace-forensics": "the cause of a symptom, read from a trace (more: trace)",
20
+ "runtime-forensics": "the cause of a symptom, from the program running",
21
+ "bug-fix": "a bug to reproduce, find the cause of and fix",
22
+ feature: "new behaviour to design and build",
23
+ refactoring: "a structure to change while the behaviour stays",
24
+ "perf-issue": "a slow path to measure and fix",
25
+ hillclimb: "one metric to improve step by step (more: metric, direction, target)",
26
+ "autonomous-run": "work to drive until a done predicate holds (more: predicate)",
27
+ prototype: "a design decision to settle with throwaway variants",
28
+ eval: "variants to compare blind on a rubric (more: variants)",
29
+ "visual-parity": "a surface to match to its reference",
30
+ "authoring-a-skill": "a skill to write or change",
31
+ "multi-phase-plan": "a change of several pull requests that needs a plan and the owner's go before anything is built (more: plan)",
32
+ "autopilot-full": "carry out a plan the owner said go for, to merged pull requests (more: plan)",
33
+ "autopilot-stack": "carry out a plan to verified pull requests without merging (more: plan)",
34
+ shipping: "land a verified stack of pull requests (more: plan, prs)",
35
+ "opening-a-pr": "open a ready pull request for a published branch (more: branch)",
36
+ babysit: "watch one pull request's conflicts, threads and CI (more: pr, mode)",
37
+ "pause-safely": "stop work in a worktree with a checkpoint (more: worktree)",
38
+ "session-pickup": "pick work up again from its trail (more: plan)",
39
+ } as const;
40
+
41
+ const NAMES = Object.keys(PLAYBOOKS) as [keyof typeof PLAYBOOKS, ...Array<keyof typeof PLAYBOOKS>];
42
+
43
+ const decision = z.discriminatedUnion("kind", [
44
+ z.strictObject({
45
+ kind: z.literal("run"),
46
+ playbook: z.enum(NAMES),
47
+ task: z.string().min(1).max(4000),
48
+ more: z.record(z.string(), z.json()).default({}).describe("What else the playbook takes, by field: the plan's subject, a pull request's number"),
49
+ }),
50
+ z.strictObject({ kind: z.literal("finish"), summary: z.string().min(1).max(2000) }),
51
+ ]);
52
+
53
+ export default workflow(
54
+ {
55
+ name: "pstack-entry",
56
+ description: "Pick the playbook a request needs and run it",
57
+ input: z.strictObject({
58
+ request: z.string().min(1).max(4000),
59
+ repo: repoSchema(),
60
+ worktrees: z.string().min(1).describe("The real path of the folder niwa keeps its worktrees in, <home>/worktrees"),
61
+ base: z.string().min(1).default("main"),
62
+ }),
63
+ output: z.discriminatedUnion("status", [
64
+ z.strictObject({ status: z.literal("ran"), playbook: z.string(), result: z.json() }),
65
+ z.strictObject({ status: z.literal("finished"), summary: z.string() }),
66
+ ]),
67
+ uses: [
68
+ "pstack.pr.binding",
69
+ "forge.pr.merge@{repo.host}/{repo.path}/pr/*",
70
+ "pstack.pr.bind",
71
+ "forge.pr.ensure@{repo.host}/{repo.path}/pr/*",
72
+ "proc.run@{worktrees}/*",
73
+ "git.*@{repo.local}",
74
+ // The git module's actions carry no target, so the rule above cannot reach them: worktrees are named here.
75
+ "git.worktree.create",
76
+ "git.worktree.get",
77
+ "git.worktree.list",
78
+ "git.worktree.remove",
79
+ "forge.pr.read@{repo.host}/{repo.path}",
80
+ "forge.checks.read@{repo.host}/{repo.path}",
81
+ "forge.pipeline.read@{repo.host}/{repo.path}",
82
+ "forge.comment.read@{repo.host}/{repo.path}",
83
+ "pstack.roles",
84
+ "session.start.*",
85
+ "harness.list",
86
+ "session.start",
87
+ "pstack.author.options",
88
+ "box.net@{repo.host}",
89
+ "session.ask",
90
+ "session.end",
91
+ "request.ask",
92
+ "workflow.list",
93
+ "workflow.start",
94
+ "niwa.records.read",
95
+ "evidence.attest",
96
+ "evidence.covers",
97
+ "evidence.list",
98
+ "plan.set",
99
+ "plan.get",
100
+ ],
101
+ phases: [
102
+ { title: "Route", detail: "The lead picks the playbook" },
103
+ { title: "Run", detail: "The playbook runs as a child of the entry" },
104
+ ],
105
+ },
106
+ async ({ request, repo, worktrees, base }) => {
107
+ const seats = await roles();
108
+ phase("Route");
109
+ const picked = await api().ask(
110
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: decision, label: "route" },
111
+ [
112
+ stepTag("entry", "route"),
113
+ "",
114
+ worker.text.trim(),
115
+ "",
116
+ "You lead pstack. Pick the one playbook this request needs and restate the task for it, or finish with the reason none fits.",
117
+ "Give in `more` what else the playbook takes that the request names, such as the subject of a plan.",
118
+ "Do not do the work yourself.",
119
+ "",
120
+ ...Object.entries(PLAYBOOKS).map(([name, what]) => `- ${name}: ${what}`),
121
+ "",
122
+ `Request: ${request}`,
123
+ ].join("\n"),
124
+ );
125
+ if (picked.kind === "finish") return { status: "finished" as const, summary: picked.summary };
126
+ phase("Run");
127
+ const result = await runBuiltin("play", picked.playbook, { ...picked.more, task: picked.task, repo, worktrees, base });
128
+ return { status: "ran" as const, playbook: picked.playbook, result: result as never };
129
+ },
130
+ );
@@ -0,0 +1,63 @@
1
+ // Eval: the lead frames what is under test and writes the rubric, held back from the candidates, and an organic
2
+ // prompt; each variant answers the cases in a session of its own harness, blind to the others, and a judge of
3
+ // another vendor grades every answer by a label it cannot trace to a model. The best variant is recommended, or none
4
+ // on a tie.
5
+
6
+ import { evalSuite } from "@niwa-labs/flow-eval";
7
+ import type { ScriptApi } from "@niwa-labs/script";
8
+
9
+ import { playbookInput } from "./lib/inputs.ts";
10
+ import { api, roles, seatOptions, stepTag } from "./lib/script.ts";
11
+ import { brief } from "./lib/texts.ts";
12
+ import text from "./texts/eval.json";
13
+
14
+ declare const workflow: ScriptApi["workflow"];
15
+ declare const z: ScriptApi["z"];
16
+ declare function phase(title: string): void;
17
+
18
+ const framed = z.strictObject({
19
+ success: z.string().min(1).max(2000),
20
+ rubric: z.array(z.strictObject({ id: z.string().regex(/^[a-z][a-z0-9-]{0,30}$/), text: z.string().min(1).max(500) })).min(3).max(6),
21
+ cases: z.array(z.strictObject({ id: z.string().regex(/^[a-z][a-z0-9-]{0,30}$/), prompt: z.string().min(1).max(4000) })).min(1).max(10),
22
+ });
23
+
24
+ export default workflow(
25
+ {
26
+ name: "pstack-eval",
27
+ description: "Compare variants blind on a rubric they never see",
28
+ input: playbookInput().extend({
29
+ variants: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,30}$/), z.string().min(1)).describe("The variants under test, each the harness its candidates run on"),
30
+ }),
31
+ output: z.strictObject({
32
+ status: z.literal("judged"),
33
+ success: z.string(),
34
+ rubric: z.array(z.strictObject({ id: z.string(), text: z.string() })),
35
+ table: z.record(z.string(), z.record(z.string(), z.number().nullable())),
36
+ recommend: z.string().nullable(),
37
+ }),
38
+ uses: ["pstack.roles", "session.start.*"],
39
+ phases: [
40
+ { title: "Frame", detail: "What is under test, the rubric and the organic prompt" },
41
+ { title: "Run", detail: "Each variant answers, blind, and a judge grades" },
42
+ ],
43
+ },
44
+ async ({ task, repo, variants }) => {
45
+ const seats = await roles();
46
+ phase("Frame");
47
+ const frame = await api().ask(
48
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: framed, label: "frame" },
49
+ brief(stepTag("eval", "frame"), text, task, ["Name what counts as success, a rubric of three to six criteria for the judge only, and the organic prompts the candidates get, as cases."]),
50
+ );
51
+ phase("Run");
52
+ const judge = seats.judge ?? seats.reviewer;
53
+ const result = await evalSuite("suite", {
54
+ cases: frame.cases,
55
+ variants,
56
+ run: async (harness, one) => (await api().ask({ harness, mode: "ask", cwd: repo.local }, one.prompt)).answer,
57
+ rubric: frame.rubric,
58
+ graders: [{ harness: judge.harness, vendor: judge.vendor ?? judge.harness }],
59
+ vendorOf: (variant) => variants[variant] ?? variant,
60
+ });
61
+ return { status: "judged" as const, success: frame.success, rubric: frame.rubric, table: result.table, recommend: result.recommend };
62
+ },
63
+ );
@@ -0,0 +1,54 @@
1
+ // Feature: the lead traces the subsystem and names the shape the change is built on and the throughput checkpoint;
2
+ // an owner lane builds it in a boxed worktree and carries it to a verified pull request.
3
+
4
+ import type { ScriptApi } from "@niwa-labs/script";
5
+
6
+ import { change, changedSchema, frame, titleOf } from "./lib/change.ts";
7
+ import { playbookInput } from "./lib/inputs.ts";
8
+ import { roles } from "./lib/script.ts";
9
+ import text from "./texts/feature.json";
10
+
11
+ declare const workflow: ScriptApi["workflow"];
12
+ declare const z: ScriptApi["z"];
13
+ declare function phase(title: string): void;
14
+
15
+ const framed = z.strictObject({ shape: z.string().min(1).max(4000), checkpoint: z.strictObject({ blocking: z.string(), independent: z.string(), shared: z.string(), decomposition: z.string() }) });
16
+
17
+ export default workflow(
18
+ {
19
+ name: "pstack-feature",
20
+ description: "Design a feature and carry it to a verified pull request",
21
+ input: playbookInput(),
22
+ output: changedSchema().extend({ framed }),
23
+ uses: [
24
+ "pstack.roles",
25
+ "session.start.*",
26
+ "harness.list",
27
+ "session.start",
28
+ "session.ask",
29
+ "session.end",
30
+ "pstack.author.options",
31
+ "box.net@{repo.host}",
32
+ "git.worktree.create",
33
+ "proc.run@{worktrees}/*",
34
+ "pstack.pr.bind",
35
+ "forge.pr.ensure@{repo.host}/{repo.path}/pr/*",
36
+ "forge.pr.read@{repo.host}/{repo.path}",
37
+ "forge.pipeline.read@{repo.host}/{repo.path}",
38
+ "evidence.attest",
39
+ "evidence.covers",
40
+ ],
41
+ phases: [
42
+ { title: "Frame", detail: "The lead frames the work, read-only" },
43
+ { title: "Build", detail: "An owner lane carries it to a verified pull request" },
44
+ ],
45
+ },
46
+ async ({ task, repo, worktrees, base }) => {
47
+ const seats = await roles();
48
+ phase("Frame");
49
+ const got = await frame(text, { task, repo, roles: seats, schema: framed, ask: ["Trace the affected subsystem and name the data shape the change is built on.", "Write the throughput checkpoint: blocking first steps, independent workstreams, shared mutable state, smallest safe decomposition; an item that does not apply says n/a and why."] });
50
+ phase("Build");
51
+ const done = await change("change", { playbook: text, repo, base, worktrees, roles: seats, task, title: titleOf(task), extra: [`The data shape: ${got.shape}`, `The throughput checkpoint: ${JSON.stringify(got.checkpoint)}`] });
52
+ return { ...done, framed: got };
53
+ },
54
+ );
@@ -0,0 +1,78 @@
1
+ // Hillclimb: one metric, one change at a time. The baseline is measured first; each attempt is one hypothesis an
2
+ // author boxed to the worktree commits, measured with the same command, and kept only when the metric moved the way
3
+ // that counts, else reverted in full. It stops when the target is met after the least number of attempts, or when the
4
+ // attempts run out; every attempt is a row of the decision log.
5
+
6
+ import { makeWorktree } from "@niwa-labs/flow-code";
7
+ import type { ScriptApi } from "@niwa-labs/script";
8
+
9
+ import { gitOut } from "./lib/git.ts";
10
+ import { playbookInput } from "./lib/inputs.ts";
11
+ import { better, measure } from "./lib/measure.ts";
12
+ import { api, authorOptions, stepTag } from "./lib/script.ts";
13
+ import { brief } from "./lib/texts.ts";
14
+ import text from "./texts/hillclimb.json";
15
+
16
+ declare const workflow: ScriptApi["workflow"];
17
+ declare const z: ScriptApi["z"];
18
+ declare function phase(title: string): void;
19
+
20
+ const row = z.strictObject({
21
+ attempt: z.number(),
22
+ hypothesis: z.string(),
23
+ before: z.number(),
24
+ after: z.number().nullable(),
25
+ verdict: z.enum(["kept", "reverted"]),
26
+ });
27
+
28
+ export default workflow(
29
+ {
30
+ name: "pstack-hillclimb",
31
+ description: "Improve one metric an attempt at a time",
32
+ input: playbookInput().extend({
33
+ metric: z.string().min(1).max(2000).describe("A shell command, run in the worktree, whose last printed number is the metric"),
34
+ direction: z.enum(["lower", "higher"]),
35
+ target: z.number(),
36
+ min: z.number().int().min(1).max(100).default(3).describe("The least number of attempts before the target may end the run"),
37
+ max: z.number().int().min(1).max(100).default(10),
38
+ }),
39
+ output: z.strictObject({ status: z.enum(["reached", "stopped"]), baseline: z.number().nullable(), final: z.number().nullable(), worktree: z.string(), head: z.string(), rows: z.array(row) }),
40
+ uses: ["session.start.*", "harness.list", "session.start", "pstack.author.options", "session.ask", "session.end", "git.worktree.create", "proc.run@{worktrees}/*"],
41
+ phases: [
42
+ { title: "Baseline", detail: "The metric before any change" },
43
+ { title: "Climb", detail: "One change, one measurement, keep or revert" },
44
+ ],
45
+ },
46
+ async ({ task, repo, base, metric, direction, target, min, max }) => {
47
+ phase("Baseline");
48
+ const wt = await makeWorktree({ repo: repo.local, base, description: `Hillclimb: ${task}`.slice(0, 120) });
49
+ const baseline = await measure("baseline", wt.path, metric);
50
+ if (baseline === null) throw new Error(`the metric \`${metric}\` printed no number on trunk: fix the measurement before climbing`);
51
+ phase("Climb");
52
+ const author = await api().session({ ...await authorOptions("author", wt.path, true), label: "author" });
53
+ const rows: Array<{ attempt: number; hypothesis: string; before: number; after: number | null; verdict: "kept" | "reverted" }> = [];
54
+ let best = baseline;
55
+ const reached = () => (direction === "lower" ? best <= target : best >= target);
56
+ for (let attempt = 1; attempt <= max && !(reached() && attempt > min); attempt += 1) {
57
+ const before = await gitOut(`before-${String(attempt)}`, wt.path, ["rev-parse", "HEAD"]);
58
+ const was = best;
59
+ const tried = await author.ask(
60
+ brief(stepTag("hillclimb", "attempt"), text, task, [
61
+ `The metric is \`${metric}\`; ${direction} is better; it is ${String(best)} now, the target ${String(target)}.`,
62
+ `The log so far: ${JSON.stringify(rows)}`,
63
+ `If you use a helper, start it on ${author.address.harness}.`,
64
+ "Make one change for one hypothesis that names its mechanism, and commit it. Answer the hypothesis.",
65
+ ]),
66
+ { schema: z.strictObject({ hypothesis: z.string().min(1).max(2000) }), label: `attempt-${String(attempt)}` },
67
+ );
68
+ const after = await measure(`measure-${String(attempt)}`, wt.path, metric);
69
+ const kept = after !== null && better(after, best, direction);
70
+ if (kept) best = after;
71
+ else await gitOut(`revert-${String(attempt)}`, wt.path, ["reset", "-q", "--hard", before]);
72
+ rows.push({ attempt, hypothesis: tried.hypothesis, before: was, after, verdict: kept ? "kept" : "reverted" });
73
+ }
74
+ await author.end();
75
+ const head = await gitOut("head", wt.path, ["rev-parse", "HEAD"]);
76
+ return { status: reached() ? ("reached" as const) : ("stopped" as const), baseline, final: best, worktree: wt.path, head, rows };
77
+ },
78
+ );
@@ -0,0 +1,41 @@
1
+ // Investigation: a read-only answer to a question about the code, with the sources it rests on. The lead traces
2
+ // the code in the local clone and answers; nothing is changed and no pull request is opened.
3
+
4
+ import type { ScriptApi } from "@niwa-labs/script";
5
+
6
+ import { playbookInput } from "./lib/inputs.ts";
7
+ import { api, roles, seatOptions, stepTag } from "./lib/script.ts";
8
+ import { brief } from "./lib/texts.ts";
9
+ import text from "./texts/investigation.json";
10
+
11
+ declare const workflow: ScriptApi["workflow"];
12
+ declare const z: ScriptApi["z"];
13
+ declare function phase(title: string): void;
14
+
15
+ const answer = z.strictObject({
16
+ summary: z.string().min(1).max(4000),
17
+ sources: z.array(z.strictObject({ file: z.string().min(1), line: z.number().int().positive() })).max(20),
18
+ });
19
+
20
+ export default workflow(
21
+ {
22
+ name: "pstack-investigation",
23
+ description: "Answer a question about the code with cited sources",
24
+ input: playbookInput(),
25
+ output: z.strictObject({ status: z.literal("answered"), answer }),
26
+ uses: ["pstack.roles", "session.start.*"],
27
+ phases: [{ title: "Trace", detail: "The lead traces the code and answers with its sources" }],
28
+ },
29
+ async ({ task, repo }) => {
30
+ const seats = await roles();
31
+ phase("Trace");
32
+ const found = await api().ask({
33
+ ...seatOptions(seats.lead),
34
+ mode: "ask",
35
+ cwd: repo.local,
36
+ schema: answer,
37
+ label: "trace",
38
+ }, brief(stepTag("investigation", "trace"), text, task, ["Work read-only. Cite each claim with a file and a line."]));
39
+ return { status: "answered" as const, answer: found };
40
+ },
41
+ );
@@ -0,0 +1,45 @@
1
+ /**
2
+ * pstack's built-ins as the host registered them: the id and the versions of each, read through the workflow module.
3
+ */
4
+
5
+ import { api } from "./script.ts";
6
+
7
+ /** How a run ended, as `workflow.run.finished` records it. */
8
+ type Outcome = { status: "done"; result: unknown } | { status: "failed"; error: { message: string } } | { status: "cancelled" };
9
+
10
+ /** Run the host-selected version of a built-in as a child. The journal read and cursor cover a child that already ended. */
11
+ export async function runBuiltin(key: string, name: string, args: unknown): Promise<unknown> {
12
+ const listed = (await api().call("workflow.list", {}, { label: `${key}-list` })) as { items: Array<{ id: string; builtin?: { plugin: string; name: string } }> };
13
+ const builtin = listed.items.find((item) => item.builtin?.plugin === "pstack" && item.builtin.name === name);
14
+ if (builtin === undefined) throw new Error(`pstack has no built-in "${name}"`);
15
+ const { run } = (await api().call("workflow.start", { id: builtin.id, args }, { label: `${key}-start` })) as { run: string };
16
+ const read = await api().read.records({ types: ["workflow.run.finished"], filter: { run } }, { label: `${key}-ended` });
17
+ const ended = read.records[0]?.data ?? (await api().wait("workflow.run.finished", { filter: { run }, from: read.next, label: `${key}-end` })).data;
18
+ const outcome = (ended as { outcome: Outcome }).outcome;
19
+ if (outcome.status === "done") return outcome.result;
20
+ throw new Error(`the playbook "${name}" (${run}) ended ${outcome.status}${outcome.status === "failed" ? `: ${outcome.error.message}` : ""}`);
21
+ }
22
+
23
+ /** Whether an error is a refusal a script may catch, not a signal of the runtime that pauses or cancels the run. */
24
+ export function isRefusal(error: unknown): boolean {
25
+ return error instanceof Error && error.name !== "PauseSignal" && error.name !== "Cancelled";
26
+ }
27
+
28
+ /** How long the suite gives one scenario to end. */
29
+ export const SCENARIO_MS = 30 * 60_000;
30
+
31
+ /** Start a version of a built-in and wait for it to end, for at most `timeoutMs`: how it ended, or that it did not. */
32
+ export async function tryVersion(key: string, id: string, version: string, args: unknown, timeoutMs = SCENARIO_MS): Promise<{ ok: true; value: unknown } | { ok: false; error: { name: string; message: string } }> {
33
+ let started: { run: string; state?: string; outcome?: Outcome; reason?: string };
34
+ try {
35
+ started = (await api().call("workflow.start", { id, version, args, wait: true, timeoutMs }, { label: `${key}-start` })) as typeof started;
36
+ } catch (error) {
37
+ // A refusal of the start is the scenario's failure; a step that failed pauses this run, as it should.
38
+ if (!isRefusal(error)) throw error;
39
+ return { ok: false, error: { name: (error as Error).name, message: (error as Error).message } };
40
+ }
41
+ if (started.state === "finished" && started.outcome?.status === "done") return { ok: true, value: started.outcome.result };
42
+ if (started.state === "finished") return { ok: false, error: { name: "Ended", message: `the run ended ${started.outcome?.status ?? "with no outcome"}` } };
43
+ await api().call("workflow.cancel", { run: started.run }, { label: `${key}-cancel` });
44
+ return { ok: false, error: { name: "NotEnded", message: `the run was ${started.state ?? "running"}${started.reason === undefined ? "" : ` (${started.reason})`} and was cancelled` } };
45
+ }
@@ -0,0 +1,70 @@
1
+ /**
2
+ * What the playbooks that change code share: the lead frames the work first, in a read-only session, and an owner
3
+ * lane carries the change to a verified pull request. None of them merges: landing is shipping's, under the policy.
4
+ */
5
+
6
+ import type { z as Z } from "zod";
7
+
8
+ import { zod } from "./inputs.ts";
9
+ import { deliver } from "./lane.ts";
10
+ import type { LaneOpts } from "./lane.ts";
11
+ import { api, seatOptions, stepTag } from "./script.ts";
12
+ import type { Repo, Roles, SessionAddress } from "./script.ts";
13
+ import { brief } from "./texts.ts";
14
+ import type { PlaybookText } from "./texts.ts";
15
+
16
+ /** Ask the lead, read-only in the local clone, to frame the work before anything is built. */
17
+ export async function frame<S extends Z.ZodType>(playbook: PlaybookText, opts: { task: string; repo: Repo; roles: Roles; schema: S; ask: string[] }): Promise<Z.output<S>> {
18
+ return await api().ask({
19
+ ...seatOptions(opts.roles.lead),
20
+ mode: "ask",
21
+ cwd: opts.repo.local,
22
+ schema: opts.schema,
23
+ label: "frame",
24
+ }, brief(stepTag(playbook.name, "frame"), playbook, opts.task, ["Work read-only: do not change anything.", ...opts.ask]));
25
+ }
26
+
27
+ /** A change carried to a pull request, as the change playbooks answer it. */
28
+ export interface Changed {
29
+ status: "verified" | "unverified";
30
+ pr: number;
31
+ head: string;
32
+ worktree: string;
33
+ author: SessionAddress;
34
+ verdicts: Array<{ name: string; covered: boolean; why?: string }>;
35
+ ci: "green" | "red" | "timed-out";
36
+ summary: string;
37
+ }
38
+
39
+ /** The output schema of a change: what `Changed` is, for a script's `output`. */
40
+ export function changedSchema() {
41
+ const z = zod();
42
+ return z.strictObject({
43
+ status: z.enum(["verified", "unverified"]),
44
+ pr: z.number(),
45
+ head: z.string(),
46
+ worktree: z.string(),
47
+ author: z.strictObject({ kind: z.literal("session"), harness: z.string(), id: z.string() }),
48
+ verdicts: z.array(z.strictObject({ name: z.string(), covered: z.boolean(), why: z.string().optional() })),
49
+ ci: z.enum(["green", "red", "timed-out"]),
50
+ summary: z.string(),
51
+ });
52
+ }
53
+
54
+ /** Carry one change through an owner lane to a verified pull request. */
55
+ export async function change(key: string, opts: LaneOpts & { task: string; title: string; extra?: string[]; draft?: boolean }): Promise<Changed> {
56
+ const done = await deliver(key, opts);
57
+ return {
58
+ status: done.verified ? "verified" : "unverified",
59
+ pr: done.pr.number,
60
+ head: done.pr.head,
61
+ worktree: done.built.wt.path,
62
+ author: done.built.author,
63
+ verdicts: done.verdicts.map((one) => ({ name: one.name, covered: one.covered, ...(one.why === undefined ? {} : { why: one.why }) })),
64
+ ci: done.ci.outcome,
65
+ summary: done.built.summary,
66
+ };
67
+ }
68
+
69
+ /** The first line of a text, cut to a title. */
70
+ export const titleOf = (text: string): string => (text.split("\n")[0] ?? text).trim().slice(0, 120) || "Change";
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The forensic playbooks: the lead, in a read-only session, holds hypotheses against evidence and answers the status
3
+ * of each, with the cause when exactly one survived. A cause with no confirmed hypothesis behind it is no cause.
4
+ */
5
+
6
+ import { zod } from "./inputs.ts";
7
+ import { HELPER_ACTIONS, api, roles, seatOptions, stepTag } from "./script.ts";
8
+ import type { Repo } from "./script.ts";
9
+ import { brief } from "./texts.ts";
10
+ import type { PlaybookText } from "./texts.ts";
11
+
12
+ export function forensicsSchema() {
13
+ const z = zod();
14
+ return z.strictObject({
15
+ status: z.enum(["found", "open"]),
16
+ cause: z.string().nullable(),
17
+ hypotheses: z.array(z.strictObject({ claim: z.string().min(1).max(1000), status: z.enum(["confirmed", "refuted", "open"]), evidence: z.string().max(2000) })).min(1).max(20),
18
+ });
19
+ }
20
+
21
+ /** Ask the lead for the hypotheses and their status, and hold the cause to a confirmed one. */
22
+ export async function forensics(playbook: PlaybookText, opts: { task: string; repo: Repo; extra: string[] }) {
23
+ const z = zod();
24
+ const seats = await roles();
25
+ const answer = z.strictObject({ cause: z.string().max(2000).nullable(), hypotheses: forensicsSchema().shape.hypotheses });
26
+ const found = await api().ask(
27
+ { ...seatOptions(seats.lead), mode: "ask", cwd: opts.repo.local, schema: answer, label: "investigate", visible: HELPER_ACTIONS },
28
+ brief(stepTag(playbook.name, "investigate"), playbook, opts.task, [
29
+ "Work read-only. Form the candidate hypotheses and hold each against evidence; mark each confirmed, refuted or open with the evidence.",
30
+ "Answer the cause only when one confirmed hypothesis is it.",
31
+ ...opts.extra,
32
+ ]),
33
+ );
34
+ const confirmed = found.hypotheses.some((one) => one.status === "confirmed");
35
+ const cause = confirmed ? found.cause : null;
36
+ return { status: cause === null ? ("open" as const) : ("found" as const), cause, hypotheses: found.hypotheses };
37
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Git read in a checkout through `proc.run`: the command runs in the checkout, boxed to it, with no network. What
3
+ * pstack reads of a repository it reads this way, so a run needs no right but `proc.run` on its worktrees.
4
+ */
5
+
6
+ import { api } from "./script.ts";
7
+
8
+ /** What a git command answered: its exit and the end of its output. */
9
+ export interface GitRan {
10
+ exit: number | null;
11
+ out: string;
12
+ truncated: boolean;
13
+ }
14
+
15
+ /** Run git in a checkout. */
16
+ export async function gitRun(key: string, cwd: string, args: readonly string[]): Promise<GitRan> {
17
+ const ran = (await api().call("proc.run", { cmd: ["git", ...args], cwd, timeout: 60_000 }, { label: key })) as { exit: number | null; tail: string; truncated: boolean };
18
+ return { exit: ran.exit, out: ran.tail, truncated: ran.truncated };
19
+ }
20
+
21
+ /** Run git in a checkout and answer its output, trimmed; a command that fails throws. */
22
+ export async function gitOut(key: string, cwd: string, args: readonly string[]): Promise<string> {
23
+ const ran = await gitRun(key, cwd, args);
24
+ if (ran.exit !== 0) throw new Error(`git ${args.join(" ")} failed (${String(ran.exit)}): ${ran.out.trim().slice(-500)}`);
25
+ if (ran.truncated) throw new Error(`git ${args.join(" ")} answered more than a read keeps`);
26
+ return ran.out.trim();
27
+ }
28
+
29
+ /** The lines of an output, without empty ones. */
30
+ export const linesOf = (text: string): string[] => text.split("\n").map((line) => line.trim()).filter((line) => line !== "");