balladeer 1.0.15 → 1.0.17
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.
- package/README.md +2 -0
- package/dist/behavior-map-schema.d.ts +107 -0
- package/dist/behavior-map-schema.js +232 -0
- package/dist/cli.d.ts +6 -1
- package/dist/cli.js +74 -6
- package/dist/commands/guidance.d.ts +2 -1
- package/dist/commands/guidance.js +55 -0
- package/dist/commands/judge.d.ts +430 -0
- package/dist/commands/judge.js +1713 -0
- package/dist/commands/map.d.ts +164 -0
- package/dist/commands/map.js +838 -0
- package/dist/commands/mcp.js +2 -2
- package/dist/commands/offers.d.ts +265 -0
- package/dist/commands/offers.js +801 -0
- package/dist/commands/risk.d.ts +29 -0
- package/dist/commands/risk.js +133 -0
- package/dist/copy.d.ts +24 -1
- package/dist/copy.js +91 -0
- package/dist/guidance-hook.mjs +348 -94
- package/dist/headless-agent.d.ts +166 -0
- package/dist/headless-agent.js +416 -0
- package/dist/hook-trust.d.ts +41 -9
- package/dist/hook-trust.js +98 -16
- package/dist/judge-brief.d.ts +48 -0
- package/dist/judge-brief.js +102 -0
- package/dist/judge-hook.d.ts +258 -0
- package/dist/judge-hook.js +1278 -0
- package/dist/judge-said.d.ts +52 -0
- package/dist/judge-said.js +181 -0
- package/dist/map-brief.d.ts +16 -0
- package/dist/map-brief.js +41 -0
- package/dist/offer-brief.d.ts +95 -0
- package/dist/offer-brief.js +217 -0
- package/dist/owned-process.d.ts +65 -0
- package/dist/owned-process.js +146 -0
- package/dist/promise-meaning.d.ts +134 -0
- package/dist/promise-meaning.js +300 -0
- package/dist/relay.d.ts +71 -0
- package/dist/relay.js +193 -0
- package/dist/remove-earlier.js +4 -2
- package/dist/risk/contract.d.ts +145 -0
- package/dist/risk/contract.js +74 -0
- package/dist/risk/describe.d.ts +7 -0
- package/dist/risk/describe.js +45 -0
- package/dist/risk/diff.d.ts +26 -0
- package/dist/risk/diff.js +174 -0
- package/dist/risk/extract.d.ts +43 -0
- package/dist/risk/extract.js +336 -0
- package/dist/risk/git.d.ts +30 -0
- package/dist/risk/git.js +118 -0
- package/dist/risk/import-graph.d.ts +41 -0
- package/dist/risk/import-graph.js +487 -0
- package/dist/risk/index.d.ts +20 -0
- package/dist/risk/index.js +20 -0
- package/dist/risk/paths.d.ts +16 -0
- package/dist/risk/paths.js +73 -0
- package/dist/risk/pipeline.d.ts +47 -0
- package/dist/risk/pipeline.js +121 -0
- package/dist/risk/priors.d.ts +18 -0
- package/dist/risk/priors.js +86 -0
- package/dist/risk/resources.d.ts +56 -0
- package/dist/risk/resources.js +374 -0
- package/dist/risk/score.d.ts +95 -0
- package/dist/risk/score.js +552 -0
- package/dist/risk/symbols.d.ts +35 -0
- package/dist/risk/symbols.js +348 -0
- package/dist/risk/text.d.ts +43 -0
- package/dist/risk/text.js +277 -0
- package/dist/risk/validate.d.ts +19 -0
- package/dist/risk/validate.js +154 -0
- package/dist/scratch-worktree.d.ts +55 -0
- package/dist/scratch-worktree.js +160 -0
- package/dist/user-scope.d.ts +74 -3
- package/dist/user-scope.js +270 -9
- package/dist/wire.d.ts +52 -3
- package/dist/wire.js +2 -2
- package/package.json +1 -1
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which could-not-tell verdicts a coding session has already been told.
|
|
3
|
+
*
|
|
4
|
+
* Robert, 30 September 2026: say a given could-not-tell once per session. The
|
|
5
|
+
* first time a session hears that a promise could not be judged, it hears it
|
|
6
|
+
* in full; later in the same session, for the same promise and the same
|
|
7
|
+
* reason, it hears one quiet line. A different reason, a new session, or a
|
|
8
|
+
* host that names no session is told in full. Kept and broken are never
|
|
9
|
+
* shortened.
|
|
10
|
+
*
|
|
11
|
+
* The record lives in the judge log directory, which carries its own
|
|
12
|
+
* `.gitignore`. It holds session ids, promise ids and a short gist of each
|
|
13
|
+
* reason, never the reason's text, and it forgets a session a day after it
|
|
14
|
+
* was last heard from.
|
|
15
|
+
*/
|
|
16
|
+
export declare const SAID_FILE = "said.json";
|
|
17
|
+
export declare const SAID_SCHEMA_VERSION = "balladeer-judge-said/v1";
|
|
18
|
+
/** A session not heard from for this long is forgotten. */
|
|
19
|
+
export declare const SAID_KEEP_MS: number;
|
|
20
|
+
/** What of a verdict the record reads. */
|
|
21
|
+
export type SaidVerdict = Readonly<{
|
|
22
|
+
promiseId: string;
|
|
23
|
+
verdict: "kept" | "broken" | "could_not_tell";
|
|
24
|
+
notes: string;
|
|
25
|
+
reproductionRejected: string | null;
|
|
26
|
+
nextStep?: string;
|
|
27
|
+
}>;
|
|
28
|
+
/**
|
|
29
|
+
* The gist of why a promise could not be judged, stable across the different
|
|
30
|
+
* words two runs use for the same reason: a rejected reproduction by the
|
|
31
|
+
* runner's own sentence, the runner's other reasons by their fixed words,
|
|
32
|
+
* then what the tests needed and did not have, and otherwise a fingerprint of
|
|
33
|
+
* the judge's notes with numbers and hashes set aside.
|
|
34
|
+
*/
|
|
35
|
+
export declare function reasonGist(verdict: SaidVerdict): string;
|
|
36
|
+
/** The one quiet line said instead of a could-not-tell this session already heard. */
|
|
37
|
+
export declare function quietLine(title: string, promiseId: string): string;
|
|
38
|
+
export type SessionMemory = Readonly<{
|
|
39
|
+
/**
|
|
40
|
+
* The quiet line for a could-not-tell this session was already told for the
|
|
41
|
+
* same promise and reason. Otherwise nothing, and the verdict is noted as
|
|
42
|
+
* told; it is then said in full by the caller.
|
|
43
|
+
*/
|
|
44
|
+
repeat: (verdict: SaidVerdict, title: string) => string | undefined;
|
|
45
|
+
/** Keep what was told. A record that cannot be written is left as it was. */
|
|
46
|
+
save: () => void;
|
|
47
|
+
}>;
|
|
48
|
+
/**
|
|
49
|
+
* What this session has been told, from the record in `directory`, or nothing
|
|
50
|
+
* without a session id, in which case every verdict is said in full.
|
|
51
|
+
*/
|
|
52
|
+
export declare function sessionMemory(directory: string, sessionId: string | undefined, now: Date): SessionMemory | undefined;
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import { createHash, randomBytes } from "node:crypto";
|
|
2
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
/**
|
|
5
|
+
* Which could-not-tell verdicts a coding session has already been told.
|
|
6
|
+
*
|
|
7
|
+
* Robert, 30 September 2026: say a given could-not-tell once per session. The
|
|
8
|
+
* first time a session hears that a promise could not be judged, it hears it
|
|
9
|
+
* in full; later in the same session, for the same promise and the same
|
|
10
|
+
* reason, it hears one quiet line. A different reason, a new session, or a
|
|
11
|
+
* host that names no session is told in full. Kept and broken are never
|
|
12
|
+
* shortened.
|
|
13
|
+
*
|
|
14
|
+
* The record lives in the judge log directory, which carries its own
|
|
15
|
+
* `.gitignore`. It holds session ids, promise ids and a short gist of each
|
|
16
|
+
* reason, never the reason's text, and it forgets a session a day after it
|
|
17
|
+
* was last heard from.
|
|
18
|
+
*/
|
|
19
|
+
export const SAID_FILE = "said.json";
|
|
20
|
+
export const SAID_SCHEMA_VERSION = "balladeer-judge-said/v1";
|
|
21
|
+
/** A session not heard from for this long is forgotten. */
|
|
22
|
+
export const SAID_KEEP_MS = 24 * 60 * 60 * 1000;
|
|
23
|
+
const MOST_SESSIONS = 50;
|
|
24
|
+
const MOST_PER_SESSION = 200;
|
|
25
|
+
function fingerprint(text) {
|
|
26
|
+
const flat = text
|
|
27
|
+
.toLowerCase()
|
|
28
|
+
.replace(/\b[0-9a-f]{7,64}\b/g, "#")
|
|
29
|
+
.replace(/\d+/g, "#")
|
|
30
|
+
.replace(/\s+/g, " ")
|
|
31
|
+
.trim();
|
|
32
|
+
return createHash("sha256").update(flat).digest("hex").slice(0, 16);
|
|
33
|
+
}
|
|
34
|
+
/** Reasons the runner writes itself, in fixed words. */
|
|
35
|
+
const RUNNER_REASONS = [
|
|
36
|
+
["unexercised", /^The judge answered kept without exercising ([^.]+)\./],
|
|
37
|
+
["no-reproduction", /^The judge answered broken without a command that shows it\./],
|
|
38
|
+
["no-answer", /^the judge's answer was not a verdict$/],
|
|
39
|
+
];
|
|
40
|
+
/**
|
|
41
|
+
* What the tests needed and did not have, as a judge tends to say it in its
|
|
42
|
+
* own words, which differ from one run to the next. Checked in this order.
|
|
43
|
+
*/
|
|
44
|
+
const NEEDS = [
|
|
45
|
+
["database", /\b(databases?|postgres(ql)?|psql|mysql|mariadb|mongo(db)?|redis|sqlite)\b/],
|
|
46
|
+
["browser", /\b(browsers?|playwright|puppeteer|chromium|selenium|webdriver|cypress)\b/],
|
|
47
|
+
[
|
|
48
|
+
"environment",
|
|
49
|
+
/\b(environment variables?|env vars?|api keys?|secrets?|credentials?|tokens?)\b|\.env\b/,
|
|
50
|
+
],
|
|
51
|
+
[
|
|
52
|
+
"service",
|
|
53
|
+
/\b(services?|servers?|econnrefused|connection refused|unreachable|could not (connect|reach)|network|docker)\b/,
|
|
54
|
+
],
|
|
55
|
+
[
|
|
56
|
+
"dependency",
|
|
57
|
+
/\b(not installed|missing dependenc(y|ies)|cannot find module|command not found|no such file)\b/,
|
|
58
|
+
],
|
|
59
|
+
["time", /\b(ran out|run out|running out|out of time|timed out|time limit|still working)\b/],
|
|
60
|
+
];
|
|
61
|
+
/**
|
|
62
|
+
* The gist of why a promise could not be judged, stable across the different
|
|
63
|
+
* words two runs use for the same reason: a rejected reproduction by the
|
|
64
|
+
* runner's own sentence, the runner's other reasons by their fixed words,
|
|
65
|
+
* then what the tests needed and did not have, and otherwise a fingerprint of
|
|
66
|
+
* the judge's notes with numbers and hashes set aside.
|
|
67
|
+
*/
|
|
68
|
+
export function reasonGist(verdict) {
|
|
69
|
+
if (verdict.reproductionRejected)
|
|
70
|
+
return `rejected:${fingerprint(verdict.reproductionRejected)}`;
|
|
71
|
+
for (const [gist, pattern] of RUNNER_REASONS) {
|
|
72
|
+
const found = pattern.exec(verdict.notes);
|
|
73
|
+
if (found !== null)
|
|
74
|
+
return found[1] === undefined ? gist : `${gist}:${found[1]}`;
|
|
75
|
+
}
|
|
76
|
+
const text = `${verdict.notes} ${verdict.nextStep ?? ""}`.toLowerCase();
|
|
77
|
+
for (const [gist, pattern] of NEEDS)
|
|
78
|
+
if (pattern.test(text))
|
|
79
|
+
return `needs:${gist}`;
|
|
80
|
+
return `notes:${fingerprint(verdict.notes)}`;
|
|
81
|
+
}
|
|
82
|
+
/** The one quiet line said instead of a could-not-tell this session already heard. */
|
|
83
|
+
export function quietLine(title, promiseId) {
|
|
84
|
+
return `could not tell again: ${title} (${promiseId}), for the reason given earlier.`;
|
|
85
|
+
}
|
|
86
|
+
function readRecord(path, now) {
|
|
87
|
+
const empty = { schemaVersion: SAID_SCHEMA_VERSION, sessions: {} };
|
|
88
|
+
let raw;
|
|
89
|
+
try {
|
|
90
|
+
if (!existsSync(path))
|
|
91
|
+
return empty;
|
|
92
|
+
raw = JSON.parse(readFileSync(path, "utf8"));
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
return empty;
|
|
96
|
+
}
|
|
97
|
+
if (raw === null || typeof raw !== "object")
|
|
98
|
+
return empty;
|
|
99
|
+
const sessions = raw.sessions;
|
|
100
|
+
if (raw.schemaVersion !== SAID_SCHEMA_VERSION ||
|
|
101
|
+
sessions === null ||
|
|
102
|
+
typeof sessions !== "object" ||
|
|
103
|
+
Array.isArray(sessions))
|
|
104
|
+
return empty;
|
|
105
|
+
const kept = {};
|
|
106
|
+
for (const [id, entry] of Object.entries(sessions)) {
|
|
107
|
+
const at = entry?.at;
|
|
108
|
+
const said = entry?.said;
|
|
109
|
+
if (typeof at !== "string" || !Array.isArray(said))
|
|
110
|
+
continue;
|
|
111
|
+
const time = Date.parse(at);
|
|
112
|
+
if (!Number.isFinite(time) || now.getTime() - time > SAID_KEEP_MS)
|
|
113
|
+
continue;
|
|
114
|
+
kept[id] = { at, said: said.filter((key) => typeof key === "string") };
|
|
115
|
+
}
|
|
116
|
+
return { schemaVersion: SAID_SCHEMA_VERSION, sessions: kept };
|
|
117
|
+
}
|
|
118
|
+
function writeRecord(directory, record) {
|
|
119
|
+
mkdirSync(directory, { recursive: true });
|
|
120
|
+
const ignore = join(directory, ".gitignore");
|
|
121
|
+
if (!existsSync(ignore))
|
|
122
|
+
writeFileSync(ignore, "*\n", "utf8");
|
|
123
|
+
const path = join(directory, SAID_FILE);
|
|
124
|
+
const temporary = join(directory, `.said-${randomBytes(6).toString("hex")}.tmp`);
|
|
125
|
+
writeFileSync(temporary, `${JSON.stringify(record)}\n`, { encoding: "utf8", flag: "wx" });
|
|
126
|
+
try {
|
|
127
|
+
renameSync(temporary, path);
|
|
128
|
+
}
|
|
129
|
+
catch (error) {
|
|
130
|
+
try {
|
|
131
|
+
unlinkSync(temporary);
|
|
132
|
+
}
|
|
133
|
+
catch {
|
|
134
|
+
/* Already gone. */
|
|
135
|
+
}
|
|
136
|
+
throw error;
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* What this session has been told, from the record in `directory`, or nothing
|
|
141
|
+
* without a session id, in which case every verdict is said in full.
|
|
142
|
+
*/
|
|
143
|
+
export function sessionMemory(directory, sessionId, now) {
|
|
144
|
+
if (sessionId === undefined)
|
|
145
|
+
return undefined;
|
|
146
|
+
const record = readRecord(join(directory, SAID_FILE), now);
|
|
147
|
+
const said = new Set(record.sessions[sessionId]?.said ?? []);
|
|
148
|
+
let heard = false;
|
|
149
|
+
return {
|
|
150
|
+
repeat: (verdict, title) => {
|
|
151
|
+
if (verdict.verdict !== "could_not_tell")
|
|
152
|
+
return undefined;
|
|
153
|
+
heard = true;
|
|
154
|
+
const key = `${verdict.promiseId} ${reasonGist(verdict)}`;
|
|
155
|
+
if (said.has(key))
|
|
156
|
+
return quietLine(title, verdict.promiseId);
|
|
157
|
+
said.add(key);
|
|
158
|
+
return undefined;
|
|
159
|
+
},
|
|
160
|
+
save: () => {
|
|
161
|
+
if (!heard)
|
|
162
|
+
return;
|
|
163
|
+
record.sessions[sessionId] = {
|
|
164
|
+
at: now.toISOString(),
|
|
165
|
+
said: [...said].slice(-MOST_PER_SESSION),
|
|
166
|
+
};
|
|
167
|
+
const newest = Object.entries(record.sessions)
|
|
168
|
+
.sort(([, a], [, b]) => Date.parse(b.at) - Date.parse(a.at))
|
|
169
|
+
.slice(0, MOST_SESSIONS);
|
|
170
|
+
try {
|
|
171
|
+
writeRecord(directory, {
|
|
172
|
+
schemaVersion: SAID_SCHEMA_VERSION,
|
|
173
|
+
sessions: Object.fromEntries(newest),
|
|
174
|
+
});
|
|
175
|
+
}
|
|
176
|
+
catch {
|
|
177
|
+
/* Unwritable: the next time is said in full, which is the safe side. */
|
|
178
|
+
}
|
|
179
|
+
},
|
|
180
|
+
};
|
|
181
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { PromiseDocument } from "./promise-meaning.js";
|
|
2
|
+
/**
|
|
3
|
+
* The fixed instructions a map builder works from, `map-brief/v1`.
|
|
4
|
+
*
|
|
5
|
+
* The map says where one promise's behavior lives, so a later change can be
|
|
6
|
+
* matched against it cheaply and a judge can start in the right place. It is
|
|
7
|
+
* built once per promise, from the code, by the person's own agent, in a
|
|
8
|
+
* disposable read-only checkout, and it never leaves the machine. The runner
|
|
9
|
+
* fills in the fields it owns (the promise id, the digest, when and on what
|
|
10
|
+
* commit it was mapped, and the meaning excerpt) and checks the rest against
|
|
11
|
+
* the contract before anything is written.
|
|
12
|
+
*/
|
|
13
|
+
export declare const MAP_BRIEF_REVISION = "map-brief/v1";
|
|
14
|
+
export declare const MAP_BRIEF = "You are mapping where one promise's behavior lives in this repository. A named person agreed the promise's meaning; it is below. Your working directory is a disposable copy of the repository at its current commit. Read only: anything you write here is thrown away.\n\nFind, by reading and searching the code:\n\n1. entryPoints: where the behavior starts, such as a route handler, a command, a UI action, a scheduled job or an event handler. kind is one of route, command, ui, job, event, function. note is one short phrase or \"\".\n2. symbols: the specific functions, classes, methods, constants, types or modules on the path from those entry points to the outcome. role is core for the ones that decide the outcome and supporting for the ones it passes through. kind is one of function, class, method, const, type, module. Name each symbol exactly as it is spelled in its file, because a later check searches the file for that name. Prefer specific symbols over whole modules.\n3. resources: what the behavior depends on outside the code: tables, columns, routes, feature flags, environment keys, queues, events, outbound calls, files, configuration. kind is one of table, column, route, flag, env, queue, event, outbound, file, config; access is one of read, write, both, call.\n4. linkedTests: search the test suite for tests that exercise this behavior. For each, give the test file, the test's own name as written in the file, and which passing cases it covers (passing-1, passing-2, in the order the meaning lists them). Only tests that exist; an empty list is a fine answer.\n5. sinks: for each failing case (failing-1, failing-2, in order), the effect that must not happen, the resources where it would happen, and the symbols where it would happen, written as path#symbol.\n6. confidence: a number from 0 to 1 for how sure you are that this map points at the code that decides the behavior.\n7. notes: anything a later reader needs, in at most three sentences, or \"\".\n8. meaning: copy this excerpt of the promise verbatim: title, observableOutcome, nonGoals, and failingExamples as {\"id\": \"failing-1\", \"text\": \"...\"}.\n\nPaths are relative to the repository root, with forward slashes. Every path must exist. Keep the map small: at most 20 entry points, 60 symbols, 40 resources, 20 linked tests.\n\nDo not push, publish or change anything outside this copy. Do not read or print credentials.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"entryPoints\": [{\"file\": \"\", \"symbol\": \"\", \"kind\": \"function\", \"note\": \"\"}], \"symbols\": [{\"file\": \"\", \"name\": \"\", \"kind\": \"function\", \"role\": \"core\"}], \"resources\": [{\"kind\": \"table\", \"name\": \"\", \"access\": \"read\"}], \"linkedTests\": [{\"file\": \"\", \"name\": \"\", \"cases\": [\"passing-1\"]}], \"sinks\": [{\"caseId\": \"failing-1\", \"effect\": \"\", \"resources\": [], \"symbols\": [\"path#symbol\"]}], \"confidence\": 0.5, \"notes\": \"\", \"meaning\": {\"title\": \"\", \"observableOutcome\": \"\", \"failingExamples\": [{\"id\": \"failing-1\", \"text\": \"\"}], \"nonGoals\": []}}";
|
|
15
|
+
/** The brief plus the promise, as the prompt the agent receives. */
|
|
16
|
+
export declare function mapPrompt(promise: PromiseDocument): string;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fixed instructions a map builder works from, `map-brief/v1`.
|
|
3
|
+
*
|
|
4
|
+
* The map says where one promise's behavior lives, so a later change can be
|
|
5
|
+
* matched against it cheaply and a judge can start in the right place. It is
|
|
6
|
+
* built once per promise, from the code, by the person's own agent, in a
|
|
7
|
+
* disposable read-only checkout, and it never leaves the machine. The runner
|
|
8
|
+
* fills in the fields it owns (the promise id, the digest, when and on what
|
|
9
|
+
* commit it was mapped, and the meaning excerpt) and checks the rest against
|
|
10
|
+
* the contract before anything is written.
|
|
11
|
+
*/
|
|
12
|
+
export const MAP_BRIEF_REVISION = "map-brief/v1";
|
|
13
|
+
export const MAP_BRIEF = `You are mapping where one promise's behavior lives in this repository. A named person agreed the promise's meaning; it is below. Your working directory is a disposable copy of the repository at its current commit. Read only: anything you write here is thrown away.
|
|
14
|
+
|
|
15
|
+
Find, by reading and searching the code:
|
|
16
|
+
|
|
17
|
+
1. entryPoints: where the behavior starts, such as a route handler, a command, a UI action, a scheduled job or an event handler. kind is one of route, command, ui, job, event, function. note is one short phrase or "".
|
|
18
|
+
2. symbols: the specific functions, classes, methods, constants, types or modules on the path from those entry points to the outcome. role is core for the ones that decide the outcome and supporting for the ones it passes through. kind is one of function, class, method, const, type, module. Name each symbol exactly as it is spelled in its file, because a later check searches the file for that name. Prefer specific symbols over whole modules.
|
|
19
|
+
3. resources: what the behavior depends on outside the code: tables, columns, routes, feature flags, environment keys, queues, events, outbound calls, files, configuration. kind is one of table, column, route, flag, env, queue, event, outbound, file, config; access is one of read, write, both, call.
|
|
20
|
+
4. linkedTests: search the test suite for tests that exercise this behavior. For each, give the test file, the test's own name as written in the file, and which passing cases it covers (passing-1, passing-2, in the order the meaning lists them). Only tests that exist; an empty list is a fine answer.
|
|
21
|
+
5. sinks: for each failing case (failing-1, failing-2, in order), the effect that must not happen, the resources where it would happen, and the symbols where it would happen, written as path#symbol.
|
|
22
|
+
6. confidence: a number from 0 to 1 for how sure you are that this map points at the code that decides the behavior.
|
|
23
|
+
7. notes: anything a later reader needs, in at most three sentences, or "".
|
|
24
|
+
8. meaning: copy this excerpt of the promise verbatim: title, observableOutcome, nonGoals, and failingExamples as {"id": "failing-1", "text": "..."}.
|
|
25
|
+
|
|
26
|
+
Paths are relative to the repository root, with forward slashes. Every path must exist. Keep the map small: at most 20 entry points, 60 symbols, 40 resources, 20 linked tests.
|
|
27
|
+
|
|
28
|
+
Do not push, publish or change anything outside this copy. Do not read or print credentials.
|
|
29
|
+
|
|
30
|
+
Your final message must be exactly one JSON object and nothing after it:
|
|
31
|
+
|
|
32
|
+
{"entryPoints": [{"file": "", "symbol": "", "kind": "function", "note": ""}], "symbols": [{"file": "", "name": "", "kind": "function", "role": "core"}], "resources": [{"kind": "table", "name": "", "access": "read"}], "linkedTests": [{"file": "", "name": "", "cases": ["passing-1"]}], "sinks": [{"caseId": "failing-1", "effect": "", "resources": [], "symbols": ["path#symbol"]}], "confidence": 0.5, "notes": "", "meaning": {"title": "", "observableOutcome": "", "failingExamples": [{"id": "failing-1", "text": ""}], "nonGoals": []}}`;
|
|
33
|
+
/** The brief plus the promise, as the prompt the agent receives. */
|
|
34
|
+
export function mapPrompt(promise) {
|
|
35
|
+
return `${MAP_BRIEF}\n\nThe promise, as Balladeer returns it:\n${JSON.stringify({
|
|
36
|
+
promiseId: promise.promiseId,
|
|
37
|
+
title: promise.title,
|
|
38
|
+
semanticDigest: promise.semanticDigest,
|
|
39
|
+
meaning: promise.meaning,
|
|
40
|
+
}, null, 2)}\n`;
|
|
41
|
+
}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fixed instructions for reading one change and naming the rules it
|
|
3
|
+
* establishes that no promise records yet, `offer-brief/v1`.
|
|
4
|
+
*
|
|
5
|
+
* Robert, 29 September 2026: an offer should be made where the work is, at
|
|
6
|
+
* the moment it is pushed, and should not outlive that session. So this runs
|
|
7
|
+
* from the same hook that judges a push, on the person's own agent, and what
|
|
8
|
+
* it finds is handed to the session that is pushing: up to three rules, each
|
|
9
|
+
* with the evidence in the change that shows it. Nothing is stored and
|
|
10
|
+
* nothing is recorded; recording is the person's yes, given in that session.
|
|
11
|
+
*
|
|
12
|
+
* The text is a constant so a result can name the brief it was given. The
|
|
13
|
+
* change itself is in the prompt, bounded, so the reader never depends on a
|
|
14
|
+
* shell to see it; the read-only git commands stay allowed for what was cut.
|
|
15
|
+
*/
|
|
16
|
+
export declare const OFFER_BRIEF_REVISION = "offer-brief/v1";
|
|
17
|
+
/** The most rules handed to the pushing session. */
|
|
18
|
+
export declare const MAX_OFFERS = 3;
|
|
19
|
+
/** The most rules one reading may name: three offered, the rest kept in `held`. */
|
|
20
|
+
export declare const MAX_RULES_READ = 6;
|
|
21
|
+
/** The exact question the pushing session asks, once per offer. */
|
|
22
|
+
export declare const OFFER_QUESTION = "Do you want this recorded as a promise for your review?";
|
|
23
|
+
/** How much of the diff the prompt carries, in characters. */
|
|
24
|
+
export declare const DIFF_CHARACTERS = 60000;
|
|
25
|
+
/** How much of any one file's diff the prompt carries, so one generated file cannot fill it. */
|
|
26
|
+
export declare const DIFF_FILE_CHARACTERS = 20000;
|
|
27
|
+
export declare const OFFER_BRIEF = "You are reading one change to this repository for the rules about the software's behavior that it establishes and that no promise records yet. A promise is a durable commitment about observable behavior that a person would care about losing, stated so that anyone can tell whether it is kept or broken. What you find is offered to the person who made the change, who decides whether to keep it. You record nothing.\n\nYour working directory is the repository. Read only: do not edit, commit, push or run anything that changes state. The change and what its author said about it are below. You may also read files and run git diff, git log and git show. The working tree may not be at the head commit, so read a file as the change left it with git show <head>:<path>.\n\nWhat is worth offering:\n\n1. A rule is a guarantee, an invariant or a boundary this change makes true about how the software behaves for somebody: what always happens, what never happens, what is refused. It needs an intention somebody stated (a commit message, or a test's name or assertion) and code in this change that makes it so. Commit messages and test names say what someone intended; the code says what is true.\n2. Not worth offering: how something is implemented, a refactor, a rename or a move, styling or wording, a one-off fix with no rule behind it, anything speculative or that the change does not yet do, and a sentence that narrates the change (\"this change adds a retry\") rather than stating what the software must do (\"a retried payment is charged once\").\n3. None is a good answer, and often the right one. A refactor, a rename, a dependency bump, a formatting change or a documentation change establishes no rule: answer with an empty list. Never invent a rule to have something to say.\n4. Leave out anything an existing promise listed below already states, and name that promise under \"covered\". Covered means the same beneficiary, trigger and outcome, not shared words or nearby files.\n\nMost valuable first, in this order, so that the same change always leads with the same rule:\n- a rule that a test added or changed in this change exercises and a commit message states;\n- then a rule that a test added or changed in this change exercises;\n- then a rule a commit message states that no test in the change exercises;\n- then a rule only the code shows.\nWithin each, the rule whose breaking would cost the person who depends on it most comes first. List at most 6.\n\nHow to write each one:\n\n5. rule: one plain sentence under 200 characters, written for the person who depends on the behavior, saying what the software must do. No file names, function names, identifiers or the author's name.\n6. beneficiary: who relies on it. trigger: when it applies. passingExample: one concrete situation where it is kept. failingExample: what must not happen, said that way (\"a second charge must not appear\").\n7. evidence: the files in this change that show it, each with what it shows. A rule with no file in this change behind it is an opinion; leave it out.\n8. statedBy: \"commit\" when a commit message states the rule, else \"test\" when a test added or changed in this change exercises it, else \"code\". confidence: \"high\" or \"medium\"; leave out anything you are less sure of.\n9. Name no person, email or account. Put no source code, secret or credential in your answer.\n\nYour final message must be exactly one JSON object and nothing after it:\n\n{\"offers\": [{\"rule\": \"<one sentence>\", \"beneficiary\": \"<who relies on it>\", \"trigger\": \"<when it applies>\", \"passingExample\": \"<what keeping it looks like>\", \"failingExample\": \"<what must not happen>\", \"evidence\": [{\"file\": \"<path in this change>\", \"shows\": \"<what in the change shows it>\"}], \"statedBy\": \"commit\" | \"test\" | \"code\", \"confidence\": \"high\" | \"medium\"}], \"covered\": [{\"promiseId\": \"<id>\", \"rule\": \"<the rule it already states>\"}], \"notes\": \"<at most two sentences>\"}";
|
|
28
|
+
/** What the reader is told about one promise already recorded. */
|
|
29
|
+
export type ExistingPromise = Readonly<{
|
|
30
|
+
promiseId: string;
|
|
31
|
+
title: string;
|
|
32
|
+
outcome?: string;
|
|
33
|
+
beneficiary?: string;
|
|
34
|
+
trigger?: string;
|
|
35
|
+
/** The labels of its failing cases, which say what it forbids in a few words each. */
|
|
36
|
+
failingExamples?: readonly string[];
|
|
37
|
+
}>;
|
|
38
|
+
/** The diff as the prompt carries it, and what was left out of it. */
|
|
39
|
+
export type BoundedDiff = Readonly<{
|
|
40
|
+
text: string;
|
|
41
|
+
totalCharacters: number;
|
|
42
|
+
shownCharacters: number;
|
|
43
|
+
/** The raw diff itself was cut by the reading process, so the total is a floor. */
|
|
44
|
+
totalIsFloor: boolean;
|
|
45
|
+
/** Files whose part was cut short. */
|
|
46
|
+
shortened: readonly string[];
|
|
47
|
+
/** Files left out entirely. */
|
|
48
|
+
omitted: readonly string[];
|
|
49
|
+
/** The line saying how much was cut, when anything was. */
|
|
50
|
+
cutLine?: string;
|
|
51
|
+
}>;
|
|
52
|
+
/**
|
|
53
|
+
* Where a file's part of the diff goes: code and tests first, then prose and
|
|
54
|
+
* configuration, then data, fixtures, evidence and lockfiles. A rule is shown
|
|
55
|
+
* by code and tests, and a change that also commits a large fixture must not
|
|
56
|
+
* push its own code out of the prompt.
|
|
57
|
+
*/
|
|
58
|
+
export declare function diffTier(path: string): number;
|
|
59
|
+
/**
|
|
60
|
+
* A whole number with its thousands grouped by commas, the way the lines print
|
|
61
|
+
* character counts. Written out rather than asked of the locale machinery,
|
|
62
|
+
* which this command keeps for instants alone (`local-time.ts`).
|
|
63
|
+
*/
|
|
64
|
+
export declare function grouped(value: number): string;
|
|
65
|
+
/**
|
|
66
|
+
* Hold a diff to what the prompt can carry.
|
|
67
|
+
*
|
|
68
|
+
* The raw diff is split per file, ordered by `diffTier` (git's own order
|
|
69
|
+
* within a tier), each file held to `DIFF_FILE_CHARACTERS`, and the whole to
|
|
70
|
+
* `DIFF_CHARACTERS`. When anything is cut, one line says how much, names the
|
|
71
|
+
* files cut short or left out, and says how to read them.
|
|
72
|
+
*/
|
|
73
|
+
export declare function boundDiff(raw: string, input: Readonly<{
|
|
74
|
+
base: string;
|
|
75
|
+
head: string;
|
|
76
|
+
totalIsFloor?: boolean;
|
|
77
|
+
limit?: number;
|
|
78
|
+
fileLimit?: number;
|
|
79
|
+
}>): BoundedDiff;
|
|
80
|
+
export type OfferBriefInput = Readonly<{
|
|
81
|
+
base: string;
|
|
82
|
+
head: string;
|
|
83
|
+
changedFiles: readonly string[];
|
|
84
|
+
diff: BoundedDiff;
|
|
85
|
+
/** The commit messages of the change, oldest first, trailers removed. */
|
|
86
|
+
commitMessages: string;
|
|
87
|
+
existing: readonly ExistingPromise[];
|
|
88
|
+
/** False when the promises already recorded could not be read, so nothing can be called covered. */
|
|
89
|
+
existingKnown: boolean;
|
|
90
|
+
minutes?: number;
|
|
91
|
+
}>;
|
|
92
|
+
/** One promise already recorded, as one line of the prompt. */
|
|
93
|
+
export declare function existingLine(promise: ExistingPromise): string;
|
|
94
|
+
/** The whole prompt: the brief, then the change and what is already recorded. */
|
|
95
|
+
export declare function offerPrompt(input: OfferBriefInput): string;
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fixed instructions for reading one change and naming the rules it
|
|
3
|
+
* establishes that no promise records yet, `offer-brief/v1`.
|
|
4
|
+
*
|
|
5
|
+
* Robert, 29 September 2026: an offer should be made where the work is, at
|
|
6
|
+
* the moment it is pushed, and should not outlive that session. So this runs
|
|
7
|
+
* from the same hook that judges a push, on the person's own agent, and what
|
|
8
|
+
* it finds is handed to the session that is pushing: up to three rules, each
|
|
9
|
+
* with the evidence in the change that shows it. Nothing is stored and
|
|
10
|
+
* nothing is recorded; recording is the person's yes, given in that session.
|
|
11
|
+
*
|
|
12
|
+
* The text is a constant so a result can name the brief it was given. The
|
|
13
|
+
* change itself is in the prompt, bounded, so the reader never depends on a
|
|
14
|
+
* shell to see it; the read-only git commands stay allowed for what was cut.
|
|
15
|
+
*/
|
|
16
|
+
export const OFFER_BRIEF_REVISION = "offer-brief/v1";
|
|
17
|
+
/** The most rules handed to the pushing session. */
|
|
18
|
+
export const MAX_OFFERS = 3;
|
|
19
|
+
/** The most rules one reading may name: three offered, the rest kept in `held`. */
|
|
20
|
+
export const MAX_RULES_READ = 6;
|
|
21
|
+
/** The exact question the pushing session asks, once per offer. */
|
|
22
|
+
export const OFFER_QUESTION = "Do you want this recorded as a promise for your review?";
|
|
23
|
+
/** How much of the diff the prompt carries, in characters. */
|
|
24
|
+
export const DIFF_CHARACTERS = 60_000;
|
|
25
|
+
/** How much of any one file's diff the prompt carries, so one generated file cannot fill it. */
|
|
26
|
+
export const DIFF_FILE_CHARACTERS = 20_000;
|
|
27
|
+
const MESSAGE_CHARACTERS = 8_000;
|
|
28
|
+
const CHANGED_FILES_SHOWN = 300;
|
|
29
|
+
const EXISTING_LINE_CHARACTERS = 600;
|
|
30
|
+
export const OFFER_BRIEF = `You are reading one change to this repository for the rules about the software's behavior that it establishes and that no promise records yet. A promise is a durable commitment about observable behavior that a person would care about losing, stated so that anyone can tell whether it is kept or broken. What you find is offered to the person who made the change, who decides whether to keep it. You record nothing.
|
|
31
|
+
|
|
32
|
+
Your working directory is the repository. Read only: do not edit, commit, push or run anything that changes state. The change and what its author said about it are below. You may also read files and run git diff, git log and git show. The working tree may not be at the head commit, so read a file as the change left it with git show <head>:<path>.
|
|
33
|
+
|
|
34
|
+
What is worth offering:
|
|
35
|
+
|
|
36
|
+
1. A rule is a guarantee, an invariant or a boundary this change makes true about how the software behaves for somebody: what always happens, what never happens, what is refused. It needs an intention somebody stated (a commit message, or a test's name or assertion) and code in this change that makes it so. Commit messages and test names say what someone intended; the code says what is true.
|
|
37
|
+
2. Not worth offering: how something is implemented, a refactor, a rename or a move, styling or wording, a one-off fix with no rule behind it, anything speculative or that the change does not yet do, and a sentence that narrates the change ("this change adds a retry") rather than stating what the software must do ("a retried payment is charged once").
|
|
38
|
+
3. None is a good answer, and often the right one. A refactor, a rename, a dependency bump, a formatting change or a documentation change establishes no rule: answer with an empty list. Never invent a rule to have something to say.
|
|
39
|
+
4. Leave out anything an existing promise listed below already states, and name that promise under "covered". Covered means the same beneficiary, trigger and outcome, not shared words or nearby files.
|
|
40
|
+
|
|
41
|
+
Most valuable first, in this order, so that the same change always leads with the same rule:
|
|
42
|
+
- a rule that a test added or changed in this change exercises and a commit message states;
|
|
43
|
+
- then a rule that a test added or changed in this change exercises;
|
|
44
|
+
- then a rule a commit message states that no test in the change exercises;
|
|
45
|
+
- then a rule only the code shows.
|
|
46
|
+
Within each, the rule whose breaking would cost the person who depends on it most comes first. List at most ${MAX_RULES_READ}.
|
|
47
|
+
|
|
48
|
+
How to write each one:
|
|
49
|
+
|
|
50
|
+
5. rule: one plain sentence under 200 characters, written for the person who depends on the behavior, saying what the software must do. No file names, function names, identifiers or the author's name.
|
|
51
|
+
6. beneficiary: who relies on it. trigger: when it applies. passingExample: one concrete situation where it is kept. failingExample: what must not happen, said that way ("a second charge must not appear").
|
|
52
|
+
7. evidence: the files in this change that show it, each with what it shows. A rule with no file in this change behind it is an opinion; leave it out.
|
|
53
|
+
8. statedBy: "commit" when a commit message states the rule, else "test" when a test added or changed in this change exercises it, else "code". confidence: "high" or "medium"; leave out anything you are less sure of.
|
|
54
|
+
9. Name no person, email or account. Put no source code, secret or credential in your answer.
|
|
55
|
+
|
|
56
|
+
Your final message must be exactly one JSON object and nothing after it:
|
|
57
|
+
|
|
58
|
+
{"offers": [{"rule": "<one sentence>", "beneficiary": "<who relies on it>", "trigger": "<when it applies>", "passingExample": "<what keeping it looks like>", "failingExample": "<what must not happen>", "evidence": [{"file": "<path in this change>", "shows": "<what in the change shows it>"}], "statedBy": "commit" | "test" | "code", "confidence": "high" | "medium"}], "covered": [{"promiseId": "<id>", "rule": "<the rule it already states>"}], "notes": "<at most two sentences>"}`;
|
|
59
|
+
const LOCKFILES = /(^|\/)(pnpm-lock\.yaml|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|bun\.lockb?|Cargo\.lock|poetry\.lock|Pipfile\.lock|uv\.lock|go\.sum|Gemfile\.lock|composer\.lock|mix\.lock|[^/]+\.lock)$/;
|
|
60
|
+
const DATA_DIRECTORIES = /(^|\/)(evidence|fixtures?|__snapshots__|snapshots|vendor|dist|build|generated|node_modules)\//;
|
|
61
|
+
const DATA_FILES = /\.(jsonl|csv|tsv|snap|map|min\.js|min\.css|svg|png|jpe?g|gif|ico|pdf|lock)$/;
|
|
62
|
+
const DOCS_AND_CONFIG = /\.(md|mdx|markdown|txt|rst|adoc|ya?ml|toml|json|ini|cfg|conf|env)$/;
|
|
63
|
+
/**
|
|
64
|
+
* Where a file's part of the diff goes: code and tests first, then prose and
|
|
65
|
+
* configuration, then data, fixtures, evidence and lockfiles. A rule is shown
|
|
66
|
+
* by code and tests, and a change that also commits a large fixture must not
|
|
67
|
+
* push its own code out of the prompt.
|
|
68
|
+
*/
|
|
69
|
+
export function diffTier(path) {
|
|
70
|
+
if (LOCKFILES.test(path) || DATA_DIRECTORIES.test(path) || DATA_FILES.test(path))
|
|
71
|
+
return 2;
|
|
72
|
+
if (DOCS_AND_CONFIG.test(path) || /(^|\/)docs?\//.test(path) || /(^|\/)\.[^/]+$/.test(path))
|
|
73
|
+
return 1;
|
|
74
|
+
return 0;
|
|
75
|
+
}
|
|
76
|
+
function sectionPath(header) {
|
|
77
|
+
const quoted = /^diff --git "?a\/.*?"? "?b\/(.*?)"?$/.exec(header);
|
|
78
|
+
return quoted?.[1] ?? header.replace(/^diff --git /, "");
|
|
79
|
+
}
|
|
80
|
+
function names(paths, limit = 40) {
|
|
81
|
+
const shown = paths.slice(0, limit).join(", ");
|
|
82
|
+
return paths.length > limit ? `${shown} and ${paths.length - limit} more` : shown;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* A whole number with its thousands grouped by commas, the way the lines print
|
|
86
|
+
* character counts. Written out rather than asked of the locale machinery,
|
|
87
|
+
* which this command keeps for instants alone (`local-time.ts`).
|
|
88
|
+
*/
|
|
89
|
+
export function grouped(value) {
|
|
90
|
+
return String(Math.round(value)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
|
|
91
|
+
}
|
|
92
|
+
const count = grouped;
|
|
93
|
+
/**
|
|
94
|
+
* Hold a diff to what the prompt can carry.
|
|
95
|
+
*
|
|
96
|
+
* The raw diff is split per file, ordered by `diffTier` (git's own order
|
|
97
|
+
* within a tier), each file held to `DIFF_FILE_CHARACTERS`, and the whole to
|
|
98
|
+
* `DIFF_CHARACTERS`. When anything is cut, one line says how much, names the
|
|
99
|
+
* files cut short or left out, and says how to read them.
|
|
100
|
+
*/
|
|
101
|
+
export function boundDiff(raw, input) {
|
|
102
|
+
const limit = input.limit ?? DIFF_CHARACTERS;
|
|
103
|
+
const fileLimit = input.fileLimit ?? DIFF_FILE_CHARACTERS;
|
|
104
|
+
const sections = [];
|
|
105
|
+
const starts = [];
|
|
106
|
+
const pattern = /^diff --git .*$/gm;
|
|
107
|
+
for (let match = pattern.exec(raw); match !== null; match = pattern.exec(raw))
|
|
108
|
+
starts.push(match.index);
|
|
109
|
+
if (starts.length === 0 && raw.trim() !== "")
|
|
110
|
+
sections.push({ path: "", text: raw, tier: 0, order: 0 });
|
|
111
|
+
starts.forEach((start, index) => {
|
|
112
|
+
const text = raw.slice(start, starts[index + 1] ?? raw.length);
|
|
113
|
+
const path = sectionPath(text.slice(0, text.indexOf("\n") < 0 ? text.length : text.indexOf("\n")));
|
|
114
|
+
sections.push({ path, text, tier: diffTier(path), order: index });
|
|
115
|
+
});
|
|
116
|
+
sections.sort((a, b) => a.tier - b.tier || a.order - b.order);
|
|
117
|
+
const parts = [];
|
|
118
|
+
const shortened = [];
|
|
119
|
+
const omitted = [];
|
|
120
|
+
let used = 0;
|
|
121
|
+
const marker = (path, rest) => `[this file's diff continues for ${count(rest)} more characters; read it with git diff ${input.base} ${input.head} -- ${path}]\n`;
|
|
122
|
+
for (const section of sections) {
|
|
123
|
+
// The share this file may take, marker included, so no bound is exceeded.
|
|
124
|
+
const share = Math.min(fileLimit, limit - used);
|
|
125
|
+
if (section.text.length <= share) {
|
|
126
|
+
parts.push(section.text);
|
|
127
|
+
used += section.text.length;
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
const keep = share - marker(section.path, section.text.length).length - 1;
|
|
131
|
+
if (keep < 800) {
|
|
132
|
+
omitted.push(section.path);
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
const kept = section.text.slice(0, keep);
|
|
136
|
+
const text = `${kept.endsWith("\n") ? kept : `${kept}\n`}${marker(section.path, section.text.length - keep)}`;
|
|
137
|
+
shortened.push(section.path);
|
|
138
|
+
parts.push(text);
|
|
139
|
+
used += text.length;
|
|
140
|
+
}
|
|
141
|
+
const text = parts.join("");
|
|
142
|
+
const total = raw.length;
|
|
143
|
+
const cutAnything = shortened.length > 0 || omitted.length > 0 || input.totalIsFloor === true;
|
|
144
|
+
const cutLine = cutAnything
|
|
145
|
+
? [
|
|
146
|
+
`The diff above is cut: it shows ${count(text.length)} of ${input.totalIsFloor === true ? "more than " : ""}${count(total)} characters.`,
|
|
147
|
+
shortened.length > 0 ? ` Cut short: ${names(shortened)}.` : "",
|
|
148
|
+
omitted.length > 0 ? ` Not shown: ${names(omitted)}.` : "",
|
|
149
|
+
` Read any file's whole change with git diff ${input.base} ${input.head} -- <path>.`,
|
|
150
|
+
].join("")
|
|
151
|
+
: undefined;
|
|
152
|
+
return {
|
|
153
|
+
text,
|
|
154
|
+
totalCharacters: total,
|
|
155
|
+
shownCharacters: text.length,
|
|
156
|
+
totalIsFloor: input.totalIsFloor === true,
|
|
157
|
+
shortened,
|
|
158
|
+
omitted,
|
|
159
|
+
...(cutLine === undefined ? {} : { cutLine }),
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
function bounded(text, limit) {
|
|
163
|
+
const flat = text.replace(/\s+/g, " ").trim();
|
|
164
|
+
return flat.length <= limit ? flat : `${flat.slice(0, limit - 3).trimEnd()}...`;
|
|
165
|
+
}
|
|
166
|
+
/** One promise already recorded, as one line of the prompt. */
|
|
167
|
+
export function existingLine(promise) {
|
|
168
|
+
const parts = [`${promise.promiseId}: ${promise.title}.`];
|
|
169
|
+
if (promise.outcome)
|
|
170
|
+
parts.push(`Outcome: ${promise.outcome}`);
|
|
171
|
+
if (promise.beneficiary)
|
|
172
|
+
parts.push(`For: ${promise.beneficiary}.`);
|
|
173
|
+
if (promise.trigger)
|
|
174
|
+
parts.push(`When: ${promise.trigger}.`);
|
|
175
|
+
if (promise.failingExamples && promise.failingExamples.length > 0)
|
|
176
|
+
parts.push(`Must not: ${promise.failingExamples.join("; ")}.`);
|
|
177
|
+
return `- ${bounded(parts.join(" "), EXISTING_LINE_CHARACTERS)}`;
|
|
178
|
+
}
|
|
179
|
+
/** The whole prompt: the brief, then the change and what is already recorded. */
|
|
180
|
+
export function offerPrompt(input) {
|
|
181
|
+
const sections = [OFFER_BRIEF, ""];
|
|
182
|
+
sections.push(`Base commit (without the change): ${input.base}`);
|
|
183
|
+
sections.push(`Head commit (with the change): ${input.head}`);
|
|
184
|
+
if (input.minutes !== undefined)
|
|
185
|
+
sections.push(`You have about ${input.minutes} minute${input.minutes === 1 ? "" : "s"}. If time is short, answer with what you are sure of.`);
|
|
186
|
+
sections.push("");
|
|
187
|
+
if (!input.existingKnown)
|
|
188
|
+
sections.push('The existing promises could not be read, so leave "covered" empty and say so in notes.');
|
|
189
|
+
else if (input.existing.length === 0)
|
|
190
|
+
sections.push("No promise is recorded for this repository yet.");
|
|
191
|
+
else {
|
|
192
|
+
sections.push(`Existing promises (${input.existing.length}). Leave out what these already state:`);
|
|
193
|
+
for (const promise of input.existing)
|
|
194
|
+
sections.push(existingLine(promise));
|
|
195
|
+
}
|
|
196
|
+
sections.push("");
|
|
197
|
+
const messages = input.commitMessages.trim();
|
|
198
|
+
sections.push("What its author said, commit by commit, oldest first:");
|
|
199
|
+
sections.push(messages === ""
|
|
200
|
+
? "(no commit message)"
|
|
201
|
+
: messages.length <= MESSAGE_CHARACTERS
|
|
202
|
+
? messages
|
|
203
|
+
: `${messages.slice(0, MESSAGE_CHARACTERS)}\n(the rest of the commit messages was cut; read them with git log ${input.base}..${input.head})`);
|
|
204
|
+
sections.push("");
|
|
205
|
+
const shown = input.changedFiles.slice(0, CHANGED_FILES_SHOWN);
|
|
206
|
+
sections.push(`Files this change touches (${input.changedFiles.length}):`);
|
|
207
|
+
for (const file of shown)
|
|
208
|
+
sections.push(`- ${file}`);
|
|
209
|
+
if (input.changedFiles.length > shown.length)
|
|
210
|
+
sections.push(`- and ${input.changedFiles.length - shown.length} more`);
|
|
211
|
+
sections.push("");
|
|
212
|
+
sections.push(`The change, as git diff --no-color ${input.base} ${input.head} prints it, code and tests first:`);
|
|
213
|
+
sections.push(input.diff.text === "" ? "(the diff is empty)" : input.diff.text.trimEnd());
|
|
214
|
+
if (input.diff.cutLine !== undefined)
|
|
215
|
+
sections.push("", input.diff.cutLine);
|
|
216
|
+
return `${sections.join("\n")}\n`;
|
|
217
|
+
}
|