@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,83 @@
1
+ // Multi-phase plan: the lead writes the plan, a list of pull requests in landing order with what each depends on, as
2
+ // a revision of a plan in niwa; the owner's go is then asked for that revision and attested node by node. The plan is
3
+ // the deliverable: nothing is implemented. A change too small to plan is said to be so, and nothing is written.
4
+
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { askGo } from "./lib/go.ts";
8
+ import { playbookInput } from "./lib/inputs.ts";
9
+ import { api, forgeRepo, roles, seatOptions, stepTag } from "./lib/script.ts";
10
+ import { brief } from "./lib/texts.ts";
11
+ import text from "./texts/multi-phase-plan.json";
12
+
13
+ declare const workflow: ScriptApi["workflow"];
14
+ declare const z: ScriptApi["z"];
15
+ declare function phase(title: string): void;
16
+
17
+ const node = z.strictObject({
18
+ id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,40}$/),
19
+ text: z.string().min(1).max(2000),
20
+ after: z.array(z.string()).max(20).default([]),
21
+ files: z.array(z.string()).max(50).default([]),
22
+ });
23
+ const written = z.discriminatedUnion("kind", [
24
+ z.strictObject({ kind: z.literal("plan"), goal: z.string().min(1).max(2000), nodes: z.array(node).min(1).max(30) }),
25
+ z.strictObject({ kind: z.literal("skip"), why: z.string().min(1).max(2000) }),
26
+ ]);
27
+
28
+ export default workflow(
29
+ {
30
+ name: "pstack-multi-phase-plan",
31
+ description: "Write a plan of pull requests and ask the owner's go",
32
+ input: playbookInput().extend({
33
+ plan: z.string().min(1).max(200).describe("The plan's subject in niwa"),
34
+ ask: z.boolean().default(true).describe("Ask the owner's go once the plan is written"),
35
+ }),
36
+ output: z.discriminatedUnion("status", [
37
+ z.strictObject({ status: z.literal("planned"), plan: z.strictObject({ of: z.string(), rev: z.number() }), nodes: z.array(node), go: z.boolean() }),
38
+ z.strictObject({ status: z.literal("skipped"), why: z.string() }),
39
+ ]),
40
+ uses: ["pstack.roles", "session.start.*", "plan.set", "request.ask", "evidence.attest"],
41
+ phases: [
42
+ { title: "Plan", detail: "The lead writes the pull requests in landing order" },
43
+ { title: "Go", detail: "The owner's go on this revision, one attestation per node" },
44
+ ],
45
+ },
46
+ async ({ task, repo, plan, ask }) => {
47
+ const seats = await roles();
48
+ phase("Plan");
49
+ const wrote = await api().ask(
50
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: written, label: "plan" },
51
+ brief(stepTag("multi-phase-plan", "plan"), text, task, [
52
+ "Answer the plan as nodes, one per pull request in landing order: an id, the one change it builds with its visible result and verification, the ids it waits for, and the files it may touch.",
53
+ "When the change is one or two files with an obvious approach, answer skip with why.",
54
+ ]),
55
+ );
56
+ if (wrote.kind === "skip") return { status: "skipped" as const, why: wrote.why };
57
+ const ids = new Set(wrote.nodes.map((one) => one.id));
58
+ for (const one of wrote.nodes) {
59
+ const unknown = one.after.filter((id) => !ids.has(id) || id === one.id);
60
+ if (unknown.length > 0) throw new Error(`the node ${one.id} waits for ${unknown.join(", ")}, which the plan does not hold before it`);
61
+ }
62
+ const set = (await api().call(
63
+ "plan.set",
64
+ {
65
+ of: plan,
66
+ goal: wrote.goal,
67
+ items: wrote.nodes.map((one) => ({
68
+ id: one.id,
69
+ text: one.text,
70
+ state: "open",
71
+ ...(one.after.length + one.files.length === 0 ? {} : { note: [one.after.length > 0 ? `after ${one.after.join(", ")}` : "", one.files.length > 0 ? `files ${one.files.join(", ")}` : ""].filter(Boolean).join("; ") }),
72
+ })),
73
+ },
74
+ { label: "set" },
75
+ )) as { of: string; rev: number };
76
+ const revision = { of: set.of, rev: set.rev };
77
+ if (!ask) return { status: "planned" as const, plan: revision, nodes: wrote.nodes, go: false };
78
+ phase("Go");
79
+ const target = forgeRepo(repo);
80
+ const go = await askGo("go", { plan: revision, nodes: wrote.nodes, change: `${target.host}/${target.path}` });
81
+ return { status: "planned" as const, plan: revision, nodes: wrote.nodes, go };
82
+ },
83
+ );
@@ -0,0 +1,62 @@
1
+ // Opening a PR: a branch the work is on, published, becomes a pull request that is ready for review: the lead reads
2
+ // the branch against trunk and writes the title and the one-minute briefing under the headings upstream asks for.
3
+
4
+ import { makeWorktree, removeWorktree } from "@niwa-labs/flow-code";
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { gitOut } from "./lib/git.ts";
8
+ import { playbookInput } from "./lib/inputs.ts";
9
+ import { api, forgeRepo, roles, seatOptions, stepTag } from "./lib/script.ts";
10
+ import { brief } from "./lib/texts.ts";
11
+ import text from "./texts/opening-a-pr.json";
12
+
13
+ declare const workflow: ScriptApi["workflow"];
14
+ declare const z: ScriptApi["z"];
15
+ declare function phase(title: string): void;
16
+
17
+ const HEADINGS = ["Why", "What changed", "Scope", "Tradeoffs", "Blast Radius", "Verification"] as const;
18
+
19
+ const written = z.strictObject({
20
+ title: z.string().regex(/^[a-z]+(\([^)]+\))?: .+$/, "type(scope): subject").max(120),
21
+ sections: z.array(z.strictObject({ heading: z.enum(HEADINGS), body: z.string().min(1).max(4000) })).min(1),
22
+ });
23
+
24
+ /** The body: the sections in upstream's order, empty ones dropped, at most 40 lines. */
25
+ function bodyOf(sections: Array<{ heading: (typeof HEADINGS)[number]; body: string }>): string {
26
+ const ordered = HEADINGS.flatMap((heading) => sections.filter((one) => one.heading === heading).map((one) => `## ${heading}\n\n${one.body.trim()}`));
27
+ const lines = ordered.join("\n\n").split("\n");
28
+ return lines.length <= 40 ? lines.join("\n") : [...lines.slice(0, 39), "(trimmed to 40 lines)"].join("\n");
29
+ }
30
+
31
+ export default workflow(
32
+ {
33
+ name: "pstack-opening-a-pr",
34
+ description: "Open a ready pull request for a published branch",
35
+ input: playbookInput().extend({
36
+ branch: z.string().min(1).max(200).describe("The published branch the work is on"),
37
+ number: z.number().int().positive().optional().describe("The pull request of the branch, when one is open: it is made ready and rewritten"),
38
+ }),
39
+ output: z.strictObject({ status: z.literal("opened"), pr: z.number(), head: z.string(), title: z.string(), body: z.string() }),
40
+ uses: ["pstack.roles", "session.start.*", "git.worktree.create", "git.worktree.get", "git.worktree.remove", "proc.run@{worktrees}/*", "forge.pr.ensure@{repo.host}/{repo.path}/pr/*"],
41
+ phases: [
42
+ { title: "Write", detail: "The title and the briefing from the branch" },
43
+ { title: "Open", detail: "Ready for review, not a draft" },
44
+ ],
45
+ },
46
+ async ({ task, repo, base, branch, number }) => {
47
+ const seats = await roles();
48
+ phase("Write");
49
+ const wt = await makeWorktree({ repo: repo.local, base: branch, description: `Read ${branch} against ${base}` });
50
+ const log = await gitOut("log", wt.path, ["log", "--oneline", `${base}..HEAD`]);
51
+ const stat = await gitOut("stat", wt.path, ["diff", "--stat", `${base}...HEAD`]);
52
+ await removeWorktree(wt, true);
53
+ const got = await api().ask(
54
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: written, label: "write" },
55
+ brief(stepTag("opening-a-pr", "write"), text, task, [`The branch ${branch} against ${base}:`, log, stat, "Answer the title as type(scope): subject, and the sections of the body."]),
56
+ );
57
+ phase("Open");
58
+ const body = bodyOf(got.sections);
59
+ const opened = (await api().call("forge.pr.ensure", { repo: forgeRepo(repo), ...(number === undefined ? {} : { number }), branch, base, title: got.title, description: body, draft: false }, { label: "open" })) as { pr: { number: number }; head: string };
60
+ return { status: "opened" as const, pr: opened.pr.number, head: opened.head, title: got.title, body };
61
+ },
62
+ );
@@ -0,0 +1,50 @@
1
+ // Pause safely: a clean stop with a checkpoint a cold start resumes from. An author boxed to the worktree the work is
2
+ // in commits what is uncommitted as one `wip:` commit on its branch, takes nothing irreversible, and writes the resume
3
+ // note; the run answers the note and the commit. It runs only when asked: "keep going" is not a pause.
4
+
5
+ import type { ScriptApi } from "@niwa-labs/script";
6
+
7
+ import { gitOut } from "./lib/git.ts";
8
+ import { playbookInput } from "./lib/inputs.ts";
9
+ import { api, authorOptions, stepTag } from "./lib/script.ts";
10
+ import { brief } from "./lib/texts.ts";
11
+ import text from "./texts/pause-safely.json";
12
+
13
+ declare const workflow: ScriptApi["workflow"];
14
+ declare const z: ScriptApi["z"];
15
+ declare function phase(title: string): void;
16
+
17
+ const note = z.strictObject({
18
+ intent: z.string().min(1).max(2000),
19
+ state: z.string().min(1).max(2000),
20
+ verified: z.array(z.string().max(1000)).max(20),
21
+ next: z.string().min(1).max(2000),
22
+ files: z.array(z.string().max(500)).max(30),
23
+ gotchas: z.array(z.string().max(1000)).max(20),
24
+ });
25
+
26
+ export default workflow(
27
+ {
28
+ name: "pstack-pause-safely",
29
+ description: "Stop cleanly with a checkpoint to resume from",
30
+ input: playbookInput().extend({ worktree: z.string().min(1).describe("The niwa worktree the work is in") }),
31
+ output: z.strictObject({ status: z.literal("paused"), head: z.string(), clean: z.boolean(), note }),
32
+ uses: ["session.start.*", "pstack.author.options", "session.ask", "session.end", "proc.run@{worktrees}/*"],
33
+ phases: [{ title: "Checkpoint", detail: "A wip commit and the resume note" }],
34
+ },
35
+ async ({ task, worktree }) => {
36
+ phase("Checkpoint");
37
+ const author = await api().session({ ...await authorOptions("author", worktree), label: "author" });
38
+ const written = await author.ask(
39
+ brief(stepTag("pause-safely", "checkpoint"), text, task, [
40
+ `Stop at a safe boundary in ${worktree}. Commit what is uncommitted as one commit whose message starts with "wip:", and push nothing new.`,
41
+ "Answer the resume note.",
42
+ ]),
43
+ { schema: note, label: "checkpoint" },
44
+ );
45
+ await author.end();
46
+ const head = await gitOut("head", worktree, ["rev-parse", "HEAD"]);
47
+ const status = await gitOut("status", worktree, ["status", "--porcelain"]);
48
+ return { status: "paused" as const, head, clean: status === "", note: written };
49
+ },
50
+ );
@@ -0,0 +1,87 @@
1
+ // Perf issue: the lead names the measurement and the target; the baseline is measured on trunk in a worktree of its
2
+ // own, an owner lane carries the fix to a verified pull request, and the same measurement runs on the fix. The
3
+ // numbers are measured, never read off the source.
4
+
5
+ import { makeWorktree, removeWorktree } from "@niwa-labs/flow-code";
6
+ import type { ScriptApi } from "@niwa-labs/script";
7
+
8
+ import { change, changedSchema, frame, titleOf } from "./lib/change.ts";
9
+ import { playbookInput } from "./lib/inputs.ts";
10
+ import { measure } from "./lib/measure.ts";
11
+ import { roles } from "./lib/script.ts";
12
+ import text from "./texts/perf-issue.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
+ measure: z.string().min(1).max(2000).describe("A shell command whose last printed number is the metric"),
20
+ direction: z.enum(["lower", "higher"]),
21
+ target: z.number(),
22
+ });
23
+
24
+ export default workflow(
25
+ {
26
+ name: "pstack-perf-issue",
27
+ description: "Measure a slow path, fix it, and measure the fix",
28
+ input: playbookInput(),
29
+ output: changedSchema().extend({ framed, baseline: z.number().nullable(), after: z.number().nullable(), met: z.boolean() }),
30
+ uses: [
31
+ "pstack.roles",
32
+ "session.start.*",
33
+ "harness.list",
34
+ "session.start",
35
+ "session.ask",
36
+ "session.end",
37
+ "pstack.author.options",
38
+ "box.net@{repo.host}",
39
+ "git.worktree.create",
40
+ "git.worktree.get",
41
+ "git.worktree.remove",
42
+ "proc.run@{worktrees}/*",
43
+ "pstack.pr.bind",
44
+ "forge.pr.ensure@{repo.host}/{repo.path}/pr/*",
45
+ "forge.pr.read@{repo.host}/{repo.path}",
46
+ "forge.pipeline.read@{repo.host}/{repo.path}",
47
+ "evidence.attest",
48
+ "evidence.covers",
49
+ ],
50
+ phases: [
51
+ { title: "Frame", detail: "The measurement and the target" },
52
+ { title: "Baseline", detail: "Measured on trunk" },
53
+ { title: "Fix", detail: "An owner lane carries the fix to a verified pull request" },
54
+ { title: "Measure", detail: "The same measurement on the fix" },
55
+ ],
56
+ },
57
+ async ({ task, repo, worktrees, base }) => {
58
+ const seats = await roles();
59
+ phase("Frame");
60
+ const got = await frame(text, {
61
+ task,
62
+ repo,
63
+ roles: seats,
64
+ schema: framed,
65
+ ask: ["Name one shell command, run from the repository's root, whose last printed number is the metric; whether lower or higher is better; and the target."],
66
+ });
67
+ phase("Baseline");
68
+ const trunk = await makeWorktree({ repo: repo.local, base, description: "Measure the baseline on trunk" });
69
+ const baseline = await measure("baseline", trunk.path, got.measure);
70
+ await removeWorktree(trunk, true);
71
+ phase("Fix");
72
+ const done = await change("change", {
73
+ playbook: text,
74
+ repo,
75
+ base,
76
+ worktrees,
77
+ roles: seats,
78
+ task,
79
+ title: titleOf(task),
80
+ extra: [`The measurement: ${got.measure}`, `The baseline: ${String(baseline)}; ${got.direction} is better; the target: ${String(got.target)}.`],
81
+ });
82
+ phase("Measure");
83
+ const after = await measure("after", done.worktree, got.measure);
84
+ const met = after !== null && (got.direction === "lower" ? after <= got.target : after >= got.target);
85
+ return { ...done, framed: got, baseline, after, met };
86
+ },
87
+ );
@@ -0,0 +1,76 @@
1
+ // Prototype: a throwaway instrument for one decision. The lead scopes the decision and the variants worth trying;
2
+ // an author boxed to a scratch worktree of its own builds each variant and observes the thing being decided, and the
3
+ // lead recommends one. Nothing is opened for review: the variants stay in their worktrees for the owner to look at.
4
+
5
+ import { makeWorktree } from "@niwa-labs/flow-code";
6
+ import type { ScriptApi } from "@niwa-labs/script";
7
+
8
+ import { playbookInput } from "./lib/inputs.ts";
9
+ import { api, authorOptions, roles, seatOptions, stepTag } from "./lib/script.ts";
10
+ import { brief } from "./lib/texts.ts";
11
+ import text from "./texts/prototype.json";
12
+
13
+ declare const workflow: ScriptApi["workflow"];
14
+ declare const z: ScriptApi["z"];
15
+ declare function phase(title: string): void;
16
+
17
+ const scoped = z.discriminatedUnion("kind", [
18
+ z.strictObject({
19
+ kind: z.literal("decide"),
20
+ decision: z.string().min(1).max(2000),
21
+ variants: z.array(z.strictObject({ name: z.string().regex(/^[a-z0-9][a-z0-9-]{0,30}$/), idea: z.string().min(1).max(2000) })).min(2).max(5),
22
+ }),
23
+ z.strictObject({ kind: z.literal("none"), why: z.string().min(1).max(2000) }),
24
+ ]);
25
+
26
+ export default workflow(
27
+ {
28
+ name: "pstack-prototype",
29
+ description: "Settle a design decision with throwaway variants",
30
+ input: playbookInput(),
31
+ output: z.discriminatedUnion("status", [
32
+ z.strictObject({
33
+ status: z.literal("decided"),
34
+ decision: z.string(),
35
+ variants: z.array(z.strictObject({ name: z.string(), path: z.string(), observed: z.string() })),
36
+ recommend: z.string(),
37
+ why: z.string(),
38
+ }),
39
+ z.strictObject({ status: z.literal("no-decision"), why: z.string() }),
40
+ ]),
41
+ uses: ["pstack.roles", "session.start.*", "session.ask", "session.end", "pstack.author.options", "git.worktree.create"],
42
+ phases: [
43
+ { title: "Scope", detail: "The decision and the variants" },
44
+ { title: "Build", detail: "Each variant in a scratch worktree, observed" },
45
+ { title: "Recommend", detail: "The lead picks one" },
46
+ ],
47
+ },
48
+ async ({ task, repo, base }) => {
49
+ const seats = await roles();
50
+ phase("Scope");
51
+ const scope = await api().ask(
52
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: scoped, label: "scope" },
53
+ brief(stepTag("prototype", "scope"), text, task, ["Name the decision the prototype exists to make and two to five variants. No decision: answer none and route to Feature."]),
54
+ );
55
+ if (scope.kind === "none") return { status: "no-decision" as const, why: scope.why };
56
+ phase("Build");
57
+ const built: Array<{ name: string; path: string; observed: string }> = [];
58
+ for (const variant of scope.variants) {
59
+ const wt = await makeWorktree({ repo: repo.local, base, description: `Prototype ${variant.name}: ${scope.decision}`.slice(0, 120) });
60
+ const author = await api().session({ ...await authorOptions(`author-${variant.name}`, wt.path), label: `author-${variant.name}` });
61
+ const seen = await author.ask(
62
+ brief(stepTag("prototype", "build"), text, task, [`The decision: ${scope.decision}`, `Build the variant ${variant.name} as a throwaway in ${wt.path}: ${variant.idea}`, "Observe the thing being decided and answer what you saw."]),
63
+ { schema: z.strictObject({ observed: z.string().min(1).max(4000) }), label: `build-${variant.name}` },
64
+ );
65
+ await author.end();
66
+ built.push({ name: variant.name, path: wt.path, observed: seen.observed });
67
+ }
68
+ phase("Recommend");
69
+ const names = scope.variants.map((one) => one.name) as [string, ...string[]];
70
+ const picked = await api().ask(
71
+ { ...seatOptions(seats.lead), mode: "ask", cwd: repo.local, schema: z.strictObject({ recommend: z.enum(names), why: z.string().min(1).max(4000) }), label: "recommend" },
72
+ brief(stepTag("prototype", "recommend"), text, task, [`The decision: ${scope.decision}`, ...built.map((one) => `- ${one.name}: ${one.observed}`), "Recommend one variant and say why."]),
73
+ );
74
+ return { status: "decided" as const, decision: scope.decision, variants: built, recommend: picked.recommend, why: picked.why };
75
+ },
76
+ );
@@ -0,0 +1,54 @@
1
+ // Refactoring: the lead names the contract, the pin that holds it, and the shape the code should have; the owner
2
+ // lane pins the behaviour first and moves the structure under it.
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/refactoring.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({ contract: z.string().min(1).max(4000), pin: z.string().min(1).max(2000), target: z.string().min(1).max(4000) });
16
+
17
+ export default workflow(
18
+ {
19
+ name: "pstack-refactoring",
20
+ description: "Reshape code behind a pinned contract",
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: ["Name the behaviour contract the structure keeps, the test or harness that pins it, and the target shape."] });
50
+ phase("Build");
51
+ const done = await change("change", { playbook: text, repo, base, worktrees, roles: seats, task, title: titleOf(task), extra: [`The contract: ${got.contract}`, `Pin it first with: ${got.pin}`, `The target shape: ${got.target}`, "Move in small steps that keep the pin green; no compatibility shims."] });
52
+ return { ...done, framed: got };
53
+ },
54
+ );
@@ -0,0 +1,26 @@
1
+ // Runtime forensics: the lead watches the program run, instruments it where its state is unclear, and answers which
2
+ // hypotheses the runtime evidence confirmed, refuted or left open, and the cause when one is left. Nothing is changed.
3
+
4
+ import type { ScriptApi } from "@niwa-labs/script";
5
+
6
+ import { forensics, forensicsSchema } from "./lib/forensics.ts";
7
+ import { playbookInput } from "./lib/inputs.ts";
8
+ import text from "./texts/runtime-forensics.json";
9
+
10
+ declare const workflow: ScriptApi["workflow"];
11
+ declare function phase(title: string): void;
12
+
13
+ export default workflow(
14
+ {
15
+ name: "pstack-runtime-forensics",
16
+ description: "Find the cause of a symptom from the program running",
17
+ input: playbookInput(),
18
+ output: forensicsSchema(),
19
+ uses: ["pstack.roles", "session.start.*", "harness.list", "session.start", "session.ask", "session.end"],
20
+ phases: [{ title: "Observe", detail: "Hypotheses held against runtime evidence" }],
21
+ },
22
+ async ({ task, repo }) => {
23
+ phase("Observe");
24
+ return await forensics(text, { task, repo, extra: ["Get runtime evidence for each hypothesis: run it, log it, read it as it runs."] });
25
+ },
26
+ );