@digital-agora/friday 0.11.0 → 0.12.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.
- package/README.md +6 -3
- package/bundles/friday-claude-0.1.0.zip +0 -0
- package/bundles/friday-opencode-0.1.0.zip +0 -0
- package/dist/adapters/claude/index.js +2 -1
- package/dist/adapters/claude/runtime.js +293 -49
- package/dist/adapters/claude/workflows.js +91 -36
- package/dist/adapters/drivers.js +41 -14
- package/dist/adapters/opencode/index.js +2 -1
- package/dist/adapters/skill.js +10 -2
- package/dist/cli.js +42 -7
- package/dist/contracts.js +200 -0
- package/dist/flow.js +227 -0
- package/dist/graph.js +11 -5
- package/dist/handoff.js +76 -3
- package/dist/ir.js +1 -0
- package/dist/load.js +3 -0
- package/dist/prompts.js +81 -5
- package/dist/reads.js +1 -1
- package/dist/slice.js +90 -0
- package/dist/specialize.js +10 -0
- package/dist/step-schemas.js +28 -3
- package/dist/validate.js +38 -20
- package/pack/model-policy.yaml +5 -0
- package/pack/orchestrations/architecture-decision.yaml +5 -0
- package/pack/orchestrations/bugfix-tdd.yaml +1 -1
- package/pack/orchestrations/discovery.yaml +16 -3
- package/pack/orchestrations/feature-delivery.yaml +11 -3
- package/pack/orchestrations/prompt-delivery.yaml +13 -5
- package/pack/orchestrations/prompt-discovery.yaml +3 -0
- package/pack/pack.yaml +12 -2
- package/pack/personas/backend-engineer.yaml +1 -1
- package/pack/personas/devops-engineer.yaml +1 -1
- package/pack/personas/frontend-engineer.yaml +1 -1
- package/package.json +1 -1
- package/schemas/decisions.schema.yaml +28 -0
- package/schemas/handoff.schema.yaml +66 -4
- package/schemas/orchestration.schema.yaml +10 -4
- package/schemas/pack.schema.yaml +25 -0
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
// DSL first, code after (decision 65): the interface contracts of the work, written in a small
|
|
2
|
+
// language-neutral DSL (handoff interfaceContracts and shapes, schemas/handoff.schema.yaml), are
|
|
3
|
+
// checked here before any code is written, rendered for the person who approves the handoff, and
|
|
4
|
+
// written as JSON Schema for the contract tests. contractIssues is embedded in every upstream
|
|
5
|
+
// workflow script (contractIssues.toString()), so a step's contracts are checked the same way there
|
|
6
|
+
// and in `friday handoff check`: it stays self-contained, plain JavaScript once the types are
|
|
7
|
+
// stripped, with no imports.
|
|
8
|
+
/**
|
|
9
|
+
* Why the contracts are not yet a DSL delivery can code from, one line each; [] when they are.
|
|
10
|
+
* A contract the work adds or changes (change new or changed) needs its kind and its body: port
|
|
11
|
+
* and callable their operations, each with every error it returns; event its payload; type its
|
|
12
|
+
* shape; http and async the OpenAPI or AsyncAPI document that is the contract. An existing one
|
|
13
|
+
* needs its owner. Every shape a contract or a shape names is declared, or is a primitive.
|
|
14
|
+
*/
|
|
15
|
+
export function contractIssues(contracts, shapes) {
|
|
16
|
+
const out = [];
|
|
17
|
+
const all = shapes || {};
|
|
18
|
+
const primitive = ["string", "integer", "number", "boolean", "date", "datetime"];
|
|
19
|
+
function known(name) {
|
|
20
|
+
return typeof name === "string" && (primitive.indexOf(name) >= 0 || Object.prototype.hasOwnProperty.call(all, name));
|
|
21
|
+
}
|
|
22
|
+
const seen = {};
|
|
23
|
+
(contracts || []).forEach(function (c) {
|
|
24
|
+
const id = String((c && c.id) || "?");
|
|
25
|
+
if (seen[id])
|
|
26
|
+
out.push(id + ": duplicate contract id");
|
|
27
|
+
seen[id] = true;
|
|
28
|
+
const change = c.change;
|
|
29
|
+
if (!change) {
|
|
30
|
+
out.push(id + ": say whether the work adds it (change: new), changes it (changed) or only uses it (existing)");
|
|
31
|
+
return;
|
|
32
|
+
}
|
|
33
|
+
if (change === "existing") {
|
|
34
|
+
if (!c.owner)
|
|
35
|
+
out.push(id + ": an existing contract needs owner, the codebase where it lives");
|
|
36
|
+
return;
|
|
37
|
+
}
|
|
38
|
+
if (!c.kind) {
|
|
39
|
+
out.push(id + ": a " + change + " contract needs kind (port, callable, event, type, http or async) and its body");
|
|
40
|
+
return;
|
|
41
|
+
}
|
|
42
|
+
if (!c.owner)
|
|
43
|
+
out.push(id + ": needs owner, the codebase that owns it");
|
|
44
|
+
if (c.kind === "port" || c.kind === "callable") {
|
|
45
|
+
if (!(c.operations || []).length)
|
|
46
|
+
out.push(id + ": a " + c.kind + " needs operations");
|
|
47
|
+
(c.operations || []).forEach(function (op) {
|
|
48
|
+
const at = id + "." + (op.name || "?");
|
|
49
|
+
if (!Array.isArray(op.errors))
|
|
50
|
+
out.push(at + ": list every error it returns in errors ([] for none)");
|
|
51
|
+
if (op.input !== undefined && !known(op.input))
|
|
52
|
+
out.push(at + ": input " + op.input + " is not a declared shape");
|
|
53
|
+
if (op.output !== undefined && !known(op.output))
|
|
54
|
+
out.push(at + ": output " + op.output + " is not a declared shape");
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
if (c.kind === "event" && !known(c.payload))
|
|
58
|
+
out.push(id + ": an event needs payload, a declared shape" + (c.payload ? " (" + c.payload + " is not one)" : ""));
|
|
59
|
+
if (c.kind === "type" && !known(c.shape))
|
|
60
|
+
out.push(id + ": a type needs shape, a declared shape" + (c.shape ? " (" + c.shape + " is not one)" : ""));
|
|
61
|
+
if ((c.kind === "http" || c.kind === "async") && !(c.spec && c.spec.file)) {
|
|
62
|
+
out.push(id + ": " + (c.kind === "http" ? "an http contract points at its OpenAPI" : "an async contract points at its AsyncAPI") + " document in spec.file");
|
|
63
|
+
}
|
|
64
|
+
});
|
|
65
|
+
// Layers (decision 65): an outer contract realizes inner ones, each owned by another codebase,
|
|
66
|
+
// with no cycle, so every boundary is named once and implemented or exposed across it.
|
|
67
|
+
const byId = {};
|
|
68
|
+
(contracts || []).forEach(function (c) { if (c && c.id)
|
|
69
|
+
byId[c.id] = c; });
|
|
70
|
+
(contracts || []).forEach(function (c) {
|
|
71
|
+
(c.realizes || []).forEach(function (r) {
|
|
72
|
+
const inner = byId[r];
|
|
73
|
+
if (r === c.id)
|
|
74
|
+
out.push(c.id + ": realizes itself");
|
|
75
|
+
else if (!inner)
|
|
76
|
+
out.push(c.id + ": realizes " + r + ", which is not one of the contracts");
|
|
77
|
+
else if (c.owner && inner.owner && c.owner === inner.owner)
|
|
78
|
+
out.push(c.id + ": realizes " + r + ", owned by the same codebase (" + c.owner + "); realizes crosses a layer");
|
|
79
|
+
});
|
|
80
|
+
});
|
|
81
|
+
// The first realizes cycle, as its path.
|
|
82
|
+
const done = {};
|
|
83
|
+
const path = [];
|
|
84
|
+
function walk(id) {
|
|
85
|
+
if (path.indexOf(id) >= 0) {
|
|
86
|
+
out.push("realizes cycle: " + path.slice(path.indexOf(id)).concat([id]).join(" -> "));
|
|
87
|
+
return true;
|
|
88
|
+
}
|
|
89
|
+
if (done[id])
|
|
90
|
+
return false;
|
|
91
|
+
path.push(id);
|
|
92
|
+
const hit = ((byId[id] || {}).realizes || []).some(function (r) { return r !== id && !!byId[r] && walk(r); });
|
|
93
|
+
path.pop();
|
|
94
|
+
done[id] = true;
|
|
95
|
+
return hit;
|
|
96
|
+
}
|
|
97
|
+
Object.keys(byId).some(function (k) { return walk(k); });
|
|
98
|
+
function check(at, s) {
|
|
99
|
+
if (!s || typeof s !== "object")
|
|
100
|
+
return;
|
|
101
|
+
if (s.type === "object") {
|
|
102
|
+
const fields = s.fields || {};
|
|
103
|
+
(s.required || []).forEach(function (r) { if (!Object.prototype.hasOwnProperty.call(fields, r))
|
|
104
|
+
out.push(at + ": required field " + r + " is not one of its fields"); });
|
|
105
|
+
Object.keys(fields).forEach(function (f) { check(at + "." + f, fields[f]); });
|
|
106
|
+
}
|
|
107
|
+
if (s.type === "array") {
|
|
108
|
+
if (!s.items)
|
|
109
|
+
out.push(at + ": an array needs items");
|
|
110
|
+
else
|
|
111
|
+
check(at + "[]", s.items);
|
|
112
|
+
}
|
|
113
|
+
if (s.type === "enum" && !(s.values || []).length)
|
|
114
|
+
out.push(at + ": an enum needs values");
|
|
115
|
+
if (s.type === "ref" && !known(s.ref))
|
|
116
|
+
out.push(at + ": ref " + s.ref + " is not a declared shape");
|
|
117
|
+
}
|
|
118
|
+
Object.keys(all).forEach(function (name) { check("shape " + name, all[name]); });
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
/** The shapes as one JSON Schema document, each under $defs, for the contract tests in any language. */
|
|
122
|
+
export function contractSchema(shapes) {
|
|
123
|
+
const prim = {
|
|
124
|
+
string: { type: "string" },
|
|
125
|
+
integer: { type: "integer" },
|
|
126
|
+
number: { type: "number" },
|
|
127
|
+
boolean: { type: "boolean" },
|
|
128
|
+
date: { type: "string", format: "date" },
|
|
129
|
+
datetime: { type: "string", format: "date-time" },
|
|
130
|
+
};
|
|
131
|
+
const named = (n) => prim[n] ?? { $ref: `#/$defs/${n}` };
|
|
132
|
+
const conv = (s) => {
|
|
133
|
+
let o;
|
|
134
|
+
if (s.type === "object") {
|
|
135
|
+
o = { type: "object", properties: Object.fromEntries(Object.entries(s.fields ?? {}).map(([k, v]) => [k, conv(v)])), additionalProperties: false };
|
|
136
|
+
if (s.required?.length)
|
|
137
|
+
o.required = s.required;
|
|
138
|
+
}
|
|
139
|
+
else if (s.type === "array")
|
|
140
|
+
o = { type: "array", items: conv(s.items ?? {}) };
|
|
141
|
+
else if (s.type === "enum")
|
|
142
|
+
o = { enum: s.values };
|
|
143
|
+
else if (s.type === "ref")
|
|
144
|
+
o = named(s.ref);
|
|
145
|
+
else
|
|
146
|
+
o = { ...prim[s.type] };
|
|
147
|
+
if (s.description)
|
|
148
|
+
o.description = s.description;
|
|
149
|
+
return s.nullable ? { anyOf: [o, { type: "null" }] } : o;
|
|
150
|
+
};
|
|
151
|
+
return { $schema: "https://json-schema.org/draft/2020-12/schema", $defs: Object.fromEntries(Object.entries(shapes ?? {}).map(([k, v]) => [k, conv(v)])) };
|
|
152
|
+
}
|
|
153
|
+
/** A contract as signature lines, for handoff.md. */
|
|
154
|
+
export function contractLines(c) {
|
|
155
|
+
const head = `**${c.id}**${c.kind ? ` (${c.kind}${c.change ? `, ${c.change}` : ""})` : c.change ? ` (${c.change})` : ""}, boundary ${c.boundary}${c.owner ? `, owned by \`${c.owner}\`` : ""}: ${c.contract}`;
|
|
156
|
+
const body = [];
|
|
157
|
+
if (c.rationale)
|
|
158
|
+
body.push(` - why: ${c.rationale}`);
|
|
159
|
+
for (const op of c.operations ?? []) {
|
|
160
|
+
body.push(` - \`${op.name}(${op.input ?? ""})${op.output ? ` -> ${op.output}` : ""}\`, errors: ${op.errors?.length ? op.errors.join(", ") : "none"}`);
|
|
161
|
+
}
|
|
162
|
+
if (c.payload)
|
|
163
|
+
body.push(` - payload: \`${c.payload}\``);
|
|
164
|
+
if (c.shape)
|
|
165
|
+
body.push(` - shape: \`${c.shape}\``);
|
|
166
|
+
if (c.realizes?.length)
|
|
167
|
+
body.push(` - realizes: ${c.realizes.join(", ")}`);
|
|
168
|
+
if (c.spec)
|
|
169
|
+
body.push(` - ${c.spec.format === "asyncapi" ? "AsyncAPI" : "OpenAPI"}: \`${c.spec.file}\`${c.spec.ref ? ` (${c.spec.ref})` : ""}`);
|
|
170
|
+
if (c.consumers?.length)
|
|
171
|
+
body.push(` - consumers: ${c.consumers.join(", ")}`);
|
|
172
|
+
return [`- ${head}`, ...body];
|
|
173
|
+
}
|
|
174
|
+
/** Who owns and who consumes each contract, as a Mermaid flowchart generated from the DSL. */
|
|
175
|
+
export function contractsMermaid(contracts) {
|
|
176
|
+
const id = (s) => `n_${s.replace(/[^A-Za-z0-9_]/g, "_")}`;
|
|
177
|
+
const esc = (s) => s.replace(/"/g, "'");
|
|
178
|
+
const lines = ["flowchart LR"];
|
|
179
|
+
const nodes = new Set();
|
|
180
|
+
const node = (key, label, shape) => {
|
|
181
|
+
if (nodes.has(key))
|
|
182
|
+
return;
|
|
183
|
+
nodes.add(key);
|
|
184
|
+
lines.push(` ${id(key)}${shape === "box" ? `["${esc(label)}"]` : `("${esc(label)}")`}`);
|
|
185
|
+
};
|
|
186
|
+
for (const c of contracts ?? []) {
|
|
187
|
+
node(`c:${c.id}`, `${c.id}${c.kind ? ` (${c.kind})` : ""}`, "box");
|
|
188
|
+
if (c.owner) {
|
|
189
|
+
node(`o:${c.owner}`, c.owner, "round");
|
|
190
|
+
lines.push(` ${id(`o:${c.owner}`)} -->|owns| ${id(`c:${c.id}`)}`);
|
|
191
|
+
}
|
|
192
|
+
for (const r of c.realizes ?? [])
|
|
193
|
+
lines.push(` ${id(`c:${c.id}`)} -.->|realizes| ${id(`c:${r}`)}`);
|
|
194
|
+
for (const u of c.consumers ?? []) {
|
|
195
|
+
node(`u:${u}`, u, "round");
|
|
196
|
+
lines.push(` ${id(`c:${c.id}`)} -->|used by| ${id(`u:${u}`)}`);
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
return lines.join("\n");
|
|
200
|
+
}
|
package/dist/flow.js
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
import { CONTAINER_TYPES, readIssue, stepPlaces } from "./reads.js";
|
|
2
|
+
import { estimateTokens, handoffSlice } from "./slice.js";
|
|
3
|
+
/** An orchestration's `id: step: message`, the form the validator reports. */
|
|
4
|
+
export const flowMessage = (i) => `${i.orchestration}: ${i.step ? `step ${i.step}: ` : ""}${i.message}`;
|
|
5
|
+
// ---------------------------------------------------------------------------------------------
|
|
6
|
+
// Data flow
|
|
7
|
+
/** Every `reads` entry that names no earlier step: unknown, itself, a step that holds it, or a later step. */
|
|
8
|
+
export function dataFlowIssues(w) {
|
|
9
|
+
const out = [];
|
|
10
|
+
const places = stepPlaces(w);
|
|
11
|
+
for (const [id, p] of places) {
|
|
12
|
+
const r = p.step.reads;
|
|
13
|
+
if (!r)
|
|
14
|
+
continue;
|
|
15
|
+
if (CONTAINER_TYPES.has(p.step.type) || p.step.type === "approval") {
|
|
16
|
+
const why = p.step.type === "approval" ? "no agent runs an approval" : `set it on the steps ${p.step.type} holds`;
|
|
17
|
+
out.push({ level: "error", orchestration: w.id, step: id, message: `reads applies to agent steps; ${why}` });
|
|
18
|
+
continue;
|
|
19
|
+
}
|
|
20
|
+
for (const e of r) {
|
|
21
|
+
const why = readIssue(w, places, p.step, e);
|
|
22
|
+
if (why)
|
|
23
|
+
out.push({ level: "error", orchestration: w.id, step: id, entry: e, message: why });
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
return out;
|
|
27
|
+
}
|
|
28
|
+
/** The units a budget counts in, and the pack's assumed size for each (agentCallBudget.assume). */
|
|
29
|
+
export const BUDGET_UNITS = {
|
|
30
|
+
task: "a task of the handoff",
|
|
31
|
+
stack: "a stack the handoff's tasks use (one integration run each)",
|
|
32
|
+
followup: "a follow-up task one integration round proposes",
|
|
33
|
+
item: "an item of an earlier step's list (<stepId>.tasks)",
|
|
34
|
+
};
|
|
35
|
+
const add = (a, b) => {
|
|
36
|
+
const o = { ...a };
|
|
37
|
+
for (const [k, v] of Object.entries(b))
|
|
38
|
+
o[k] = (o[k] ?? 0) + v;
|
|
39
|
+
return o;
|
|
40
|
+
};
|
|
41
|
+
const scale = (a, k) => Object.fromEntries(Object.entries(a).map(([m, v]) => [m, v * k]));
|
|
42
|
+
const times = (a, unit) => Object.fromEntries(Object.entries(a).map(([m, v]) => [[...(m ? m.split("*") : []), unit].sort().join("*"), v]));
|
|
43
|
+
const constant = (k) => (k ? { "": k } : {});
|
|
44
|
+
/** The unit of a foreach's items. */
|
|
45
|
+
function unitOf(over) {
|
|
46
|
+
if (over === "handoff.tasks")
|
|
47
|
+
return "task";
|
|
48
|
+
if (over === "handoff.stacks")
|
|
49
|
+
return "stack";
|
|
50
|
+
return "item";
|
|
51
|
+
}
|
|
52
|
+
/** Missing limits stop the count: the budget of a loop without one is not finite. */
|
|
53
|
+
export class UnboundedLoop extends Error {
|
|
54
|
+
step;
|
|
55
|
+
limit;
|
|
56
|
+
constructor(step, limit) {
|
|
57
|
+
super(`${limit} is missing or not a whole number >= ${limit === "maxLoops" ? 0 : 1}; the loop has no finite bound`);
|
|
58
|
+
this.step = step;
|
|
59
|
+
this.limit = limit;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
const limit = (s, name) => {
|
|
63
|
+
const v = s[name];
|
|
64
|
+
const min = name === "maxLoops" ? 0 : 1;
|
|
65
|
+
if (typeof v !== "number" || !Number.isInteger(v) || v < min)
|
|
66
|
+
throw new UnboundedLoop(s.id, name);
|
|
67
|
+
return v;
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* Agent calls of one tdd-pair loop for one task, before the delivery decider: test design (red),
|
|
71
|
+
* one verify when the acceptance is already met, then per round the implementer and either
|
|
72
|
+
* verify or test design on a test conflict.
|
|
73
|
+
*/
|
|
74
|
+
export const tddCalls = (s) => 2 + 2 * limit(s, "maxRounds");
|
|
75
|
+
/** Agent calls of one gate: a review per loop (maxLoops + 1) and a fix between reviews with a fixer. */
|
|
76
|
+
export const gateCalls = (s) => {
|
|
77
|
+
const loops = limit(s, "maxLoops");
|
|
78
|
+
return loops + 1 + (s.onFail ? loops : 0);
|
|
79
|
+
};
|
|
80
|
+
/** Calls of the steps, before the decider multiplier. */
|
|
81
|
+
function stepsBudget(steps) {
|
|
82
|
+
return steps.reduce((b, s) => add(b, stepBudget(s)), {});
|
|
83
|
+
}
|
|
84
|
+
function stepBudget(s) {
|
|
85
|
+
switch (s.type) {
|
|
86
|
+
case "approval":
|
|
87
|
+
return {};
|
|
88
|
+
case "parallel":
|
|
89
|
+
case "sequential":
|
|
90
|
+
return stepsBudget(s.steps);
|
|
91
|
+
case "foreach":
|
|
92
|
+
return times(stepsBudget(s.steps), unitOf(s.over));
|
|
93
|
+
case "tdd-pair":
|
|
94
|
+
return constant(tddCalls(s));
|
|
95
|
+
case "gate":
|
|
96
|
+
return constant(gateCalls(s));
|
|
97
|
+
case "integration-loop": {
|
|
98
|
+
// Each round runs once per stack; the follow-ups of a round go through the task loop before
|
|
99
|
+
// the next round, so they run in every round but the last, which stops with them open.
|
|
100
|
+
const rounds = limit(s, "maxRounds");
|
|
101
|
+
return add(times(constant(rounds), "stack"), times(scale(stepsBudget(s.followup), rounds - 1), "followup"));
|
|
102
|
+
}
|
|
103
|
+
case "agent":
|
|
104
|
+
// An interfaces step runs once more when its contracts fail their checks (decision 65).
|
|
105
|
+
return constant(s.output === "interfaces" ? 2 : 1);
|
|
106
|
+
default:
|
|
107
|
+
return constant(1);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Every agent call a delivery step makes with a handoff can be followed by the delivery decider
|
|
112
|
+
* and one re-run of the step (decisions 49, 56): three calls at most.
|
|
113
|
+
*/
|
|
114
|
+
export const DECIDER_FACTOR = 3;
|
|
115
|
+
/** The worst-case agent calls of one orchestration; throws UnboundedLoop when a limit is missing. */
|
|
116
|
+
export function orchestrationBudget(w, assumed) {
|
|
117
|
+
const handoff = w.stream === "downstream" && !!w.requires?.includes("handoff");
|
|
118
|
+
let calls = scale(stepsBudget(w.steps), handoff ? DECIDER_FACTOR : 1);
|
|
119
|
+
if (w.stream === "upstream") {
|
|
120
|
+
// One workflow run is one question round; a round that stops for the user writes no retro.
|
|
121
|
+
if (typeof w.maxRounds !== "number" || !Number.isInteger(w.maxRounds) || w.maxRounds < 1)
|
|
122
|
+
throw new UnboundedLoop("(workflow)", "maxRounds");
|
|
123
|
+
calls = scale(calls, w.maxRounds);
|
|
124
|
+
}
|
|
125
|
+
if (w.retro)
|
|
126
|
+
calls = add(calls, constant(1));
|
|
127
|
+
const atAssumed = assumed ? evaluate(calls, assumed.assume) : undefined;
|
|
128
|
+
// The assumed size is quoted only with the units the count depends on.
|
|
129
|
+
const used = new Set(Object.keys(calls).flatMap((m) => (m ? m.split("*") : [])));
|
|
130
|
+
const sized = assumed ? Object.fromEntries(Object.entries(assumed.assume).filter(([u]) => used.has(u))) : {};
|
|
131
|
+
const why = [w.stream === "upstream" ? `${w.maxRounds} rounds (+ extraRounds the user allows)` : "", handoff ? `each call may add the delivery decider and one re-run` : ""].filter(Boolean).join("; ");
|
|
132
|
+
const text = `worst case ${formatBudget(calls)} agent calls${why ? ` (${why})` : ""}${atAssumed !== undefined && Object.keys(sized).length ? `; ${atAssumed} for ${assumedText(sized)}` : ""}`;
|
|
133
|
+
return { orchestration: w.id, calls, ...(atAssumed !== undefined ? { atAssumed } : {}), text };
|
|
134
|
+
}
|
|
135
|
+
/** The value of a budget at the given size per unit; a unit without a size counts 1. */
|
|
136
|
+
export function evaluate(b, size) {
|
|
137
|
+
return Object.entries(b).reduce((sum, [m, v]) => sum + v * (m ? m.split("*") : []).reduce((p, u) => p * (size[u] ?? 1), 1), 0);
|
|
138
|
+
}
|
|
139
|
+
/** "19 + 24 per task + 6 per stack". */
|
|
140
|
+
export function formatBudget(b) {
|
|
141
|
+
const terms = Object.entries(b)
|
|
142
|
+
.filter(([, v]) => v)
|
|
143
|
+
.sort(([a], [c]) => a.split("*").length - c.split("*").length || a.localeCompare(c))
|
|
144
|
+
.map(([m, v]) => (m ? `${v} per ${m.split("*").join(" per ")}` : `${v}`));
|
|
145
|
+
return terms.join(" + ") || "0";
|
|
146
|
+
}
|
|
147
|
+
const assumedText = (a) => Object.keys(BUDGET_UNITS).filter((u) => a[u] !== undefined).map((u) => `${a[u]} ${u}${a[u] === 1 ? "" : "s"}`).join(", ");
|
|
148
|
+
/** The budget issues: an error for a missing limit, a warning above the pack's threshold. */
|
|
149
|
+
export function budgetIssues(w, pack) {
|
|
150
|
+
try {
|
|
151
|
+
const budget = orchestrationBudget(w, pack.agentCallBudget);
|
|
152
|
+
const cap = pack.agentCallBudget?.warnAbove;
|
|
153
|
+
const issues = cap !== undefined && budget.atAssumed !== undefined && budget.atAssumed > cap
|
|
154
|
+
? [{ level: "warning", orchestration: w.id, message: `${budget.text}, above agentCallBudget.warnAbove (${cap})` }]
|
|
155
|
+
: [];
|
|
156
|
+
return { issues, budget };
|
|
157
|
+
}
|
|
158
|
+
catch (e) {
|
|
159
|
+
if (!(e instanceof UnboundedLoop))
|
|
160
|
+
throw e;
|
|
161
|
+
return { issues: [{ level: "error", orchestration: w.id, ...(e.step === "(workflow)" ? {} : { step: e.step }), message: e.message }] };
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
// ---------------------------------------------------------------------------------------------
|
|
165
|
+
// Parking (decision 56)
|
|
166
|
+
const isTaskLoop = (s) => s.type === "foreach" && s.over === "handoff.tasks";
|
|
167
|
+
const nestedTaskLoops = (steps) => steps.flatMap((s) => {
|
|
168
|
+
const kids = s.type === "parallel" || s.type === "sequential" || s.type === "foreach" ? s.steps : s.type === "integration-loop" ? s.followup : [];
|
|
169
|
+
return [...kids.filter(isTaskLoop), ...nestedTaskLoops(kids)];
|
|
170
|
+
});
|
|
171
|
+
/**
|
|
172
|
+
* Whether a run of this orchestration parks blockers: a downstream workflow from a handoff with a
|
|
173
|
+
* foreach over handoff.tasks at any depth. Adapters emit parking from this alone (the Claude
|
|
174
|
+
* runtime's WORKFLOW.taskLoop, the skill's parking rule), so they cannot drift from the check.
|
|
175
|
+
*/
|
|
176
|
+
export function canPark(w) {
|
|
177
|
+
return w.stream === "downstream" && !!w.requires?.includes("handoff") && (w.steps.some(isTaskLoop) || nestedTaskLoops(w.steps).length > 0);
|
|
178
|
+
}
|
|
179
|
+
/** A workflow that parks has its task loop at the top level: parked blockers are released once, after it. */
|
|
180
|
+
export function parkingIssues(w) {
|
|
181
|
+
if (!canPark(w) || w.steps.some(isTaskLoop))
|
|
182
|
+
return [];
|
|
183
|
+
return nestedTaskLoops(w.steps).map((s) => ({
|
|
184
|
+
level: "error",
|
|
185
|
+
orchestration: w.id,
|
|
186
|
+
step: s.id,
|
|
187
|
+
message: "parks blockers (decision 56) but has no top-level foreach over handoff.tasks; nested in another step, its parked blockers would be released per outer iteration or while sibling steps still run. Make it a top-level step",
|
|
188
|
+
}));
|
|
189
|
+
}
|
|
190
|
+
/** Every issue of the orchestration check, and the budget when every loop is bounded. */
|
|
191
|
+
export function orchestrationCheck(w, pack) {
|
|
192
|
+
const b = budgetIssues(w, pack);
|
|
193
|
+
return { issues: [...dataFlowIssues(w), ...b.issues, ...parkingIssues(w)], ...(b.budget ? { budget: b.budget } : {}) };
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* The worst case of a delivery run's prompt tokens spent on the handoff: a call on a task (a term
|
|
197
|
+
* of the budget per task or per follow-up) carries that task's slice, every other call the whole
|
|
198
|
+
* handoff. Follow-ups are not known before the run: they count at the pack's assumed number, each
|
|
199
|
+
* with the average slice. Counts only the handoff part of a prompt, which dominates it; the other
|
|
200
|
+
* parts (the brief, earlier results, the field guides) come on top.
|
|
201
|
+
*/
|
|
202
|
+
export function promptTokenEstimate(w, handoff, pack, opts = {}) {
|
|
203
|
+
const calls = orchestrationBudget(w).calls;
|
|
204
|
+
const tasks = handoff.tasks ?? [];
|
|
205
|
+
const whole = estimateTokens(JSON.stringify(handoff));
|
|
206
|
+
const sliced = opts.sliced !== false;
|
|
207
|
+
const slices = tasks.map((t) => (sliced ? estimateTokens(JSON.stringify(handoffSlice(handoff, t, handoff.commands ?? {}))) : whole));
|
|
208
|
+
const sum = slices.reduce((a, b) => a + b, 0);
|
|
209
|
+
const avg = slices.length ? sum / slices.length : whole;
|
|
210
|
+
const size = {
|
|
211
|
+
task: tasks.length,
|
|
212
|
+
stack: new Set(tasks.map((t) => t.stack)).size || 1,
|
|
213
|
+
followup: pack.agentCallBudget?.assume.followup ?? 0,
|
|
214
|
+
};
|
|
215
|
+
let promptTokens = 0;
|
|
216
|
+
for (const [m, k] of Object.entries(calls)) {
|
|
217
|
+
const units = m ? m.split("*") : [];
|
|
218
|
+
const others = units.filter((u) => u !== "task").reduce((p, u) => p * (size[u] ?? 1), 1);
|
|
219
|
+
// Per task: each task's own slice; per follow-up: the average slice; otherwise the whole handoff.
|
|
220
|
+
promptTokens += units.includes("task") ? k * others * sum : units.includes("followup") ? k * others * avg : k * others * whole;
|
|
221
|
+
}
|
|
222
|
+
promptTokens = Math.round(promptTokens);
|
|
223
|
+
const n = evaluate(calls, size);
|
|
224
|
+
const largest = slices.length ? Math.max(...slices) : whole;
|
|
225
|
+
const text = `worst case about ${promptTokens.toLocaleString("en-US")} prompt tokens of handoff over ${n} agent calls (${tasks.length} tasks, ${size.stack} stacks, ${size.followup} follow-ups per round assumed): the whole handoff is about ${whole.toLocaleString("en-US")} tokens, the largest task slice about ${largest.toLocaleString("en-US")}`;
|
|
226
|
+
return { calls: n, handoffTokens: whole, largestSliceTokens: largest, promptTokens, text };
|
|
227
|
+
}
|
package/dist/graph.js
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
import { outputsOf } from "./types.js";
|
|
2
2
|
import { stepPlaces } from "./reads.js";
|
|
3
|
+
import { DECIDER_FACTOR, gateCalls, tddCalls } from "./flow.js";
|
|
3
4
|
const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
|
|
4
|
-
/**
|
|
5
|
+
/**
|
|
6
|
+
* `handoff`: the run has a handoff to go back to (downstream, not release from changesets). The
|
|
7
|
+
* budget ends in the loop's worst-case agent calls (decision 58, src/flow.ts).
|
|
8
|
+
*/
|
|
5
9
|
export function loopExits(step, handoff = true) {
|
|
10
|
+
const calls = (k, per = "") => `at most ${n(k, "agent call", "agent calls")}${per}${handoff ? ` (${k * DECIDER_FACTOR} with the delivery decider and its re-runs)` : ""}`;
|
|
6
11
|
const escalation = handoff
|
|
7
12
|
? "an agent returns blocked -> the delivery decider settles it or the run stops with needs-upstream"
|
|
8
13
|
: "an agent returns blocked -> the run stops with blocked";
|
|
@@ -11,21 +16,21 @@ export function loopExits(step, handoff = true) {
|
|
|
11
16
|
return {
|
|
12
17
|
success: `verify is green with evidence: the static checks and each level the task's tests are at (one test per criterion, at the lowest level that proves it, within ${step.testScope.join(", ")}) ran with exit code 0, no forbidden command, no failure of this task's own tests`,
|
|
13
18
|
failure: `still not green after round ${step.maxRounds}`,
|
|
14
|
-
budget: `${n(step.maxRounds, "round", "rounds")} of green + verify; a test conflict goes to test design, which keeps the test or changes it with a justification`,
|
|
15
|
-
escalation: `${escalation}; test design returns questions, or a test changed without naming its criterion and why it was wrong -> ${handoff ? "needs-upstream" : "blocked"}`,
|
|
19
|
+
budget: `${n(step.maxRounds, "round", "rounds")} of green + verify; a test conflict goes to test design, which keeps the test or changes it with a justification; ${calls(tddCalls(step), " per task")}`,
|
|
20
|
+
escalation: `${escalation}; test design returns questions, or a test changed without naming its criterion and why it was wrong -> ${handoff ? "needs-upstream" : "blocked"}${handoff ? "; in the task loop over the handoff's tasks a blocker or test question parks only its task and the tasks that depend on it, and the run stops once after the loop (decision 56)" : ""}`,
|
|
16
21
|
};
|
|
17
22
|
case "gate":
|
|
18
23
|
return {
|
|
19
24
|
success: "the review passes",
|
|
20
25
|
failure: step.onFail ? `still failing after ${n(step.maxLoops, "fix loop", "fix loops")} (the findings are returned)` : "the review fails (the findings are returned)",
|
|
21
|
-
budget: step.onFail ? `${n(step.maxLoops, "fix loop", "fix loops")} by ${step.onFail.persona}--${step.onFail.taskKind}` : "no fixer: one review, pass or fail"
|
|
26
|
+
budget: `${step.onFail ? `${n(step.maxLoops, "fix loop", "fix loops")} by ${step.onFail.persona}--${step.onFail.taskKind}` : "no fixer: one review, pass or fail"}; ${calls(gateCalls(step))}`,
|
|
22
27
|
escalation,
|
|
23
28
|
};
|
|
24
29
|
case "integration-loop":
|
|
25
30
|
return {
|
|
26
31
|
success: `every stack green, every level in scope (${step.testScope.join(", ")}) reported with no failed suite, and no follow-ups`,
|
|
27
32
|
failure: `red with no follow-ups, or follow-ups left after round ${step.maxRounds}`,
|
|
28
|
-
budget: `${n(step.maxRounds, "integration round", "integration rounds")}; each round's follow-ups go through the task loop`,
|
|
33
|
+
budget: `${n(step.maxRounds, "integration round", "integration rounds")}; each round's follow-ups go through the task loop; ${calls(step.maxRounds, " per stack")}, plus the follow-ups of ${n(step.maxRounds - 1, "round", "rounds")} through the task loop`,
|
|
29
34
|
escalation,
|
|
30
35
|
};
|
|
31
36
|
}
|
|
@@ -175,6 +180,7 @@ export function orchestrationGraph(w) {
|
|
|
175
180
|
for (const e of last)
|
|
176
181
|
route(end, e.from, down ? "every step finished" : "the handoff is written; a person approves it");
|
|
177
182
|
g.agentExits.push({ status: "failed", from: "any agent step", when: "the agent returned no result, or no agent exists for the persona and task kind" });
|
|
183
|
+
g.agentExits.push({ status: "failed", from: "any agent step", when: "the next call would pass args.maxAgentCalls or args.maxPromptTokens (decision 61); resume with a higher cap to go on" });
|
|
178
184
|
g.agentExits.push({
|
|
179
185
|
status: handoff ? "needs-upstream" : "blocked",
|
|
180
186
|
from: "any agent step",
|
package/dist/handoff.js
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import { existsSync, readFileSync, writeFileSync } from "node:fs";
|
|
2
2
|
import { parse, stringify } from "yaml";
|
|
3
|
+
import { resolve } from "node:path";
|
|
4
|
+
import { promptTokenEstimate } from "./flow.js";
|
|
5
|
+
import { contractIssues, contractLines, contractsMermaid } from "./contracts.js";
|
|
3
6
|
import { schemaValidator } from "./validate.js";
|
|
4
7
|
/** The orchestrations whose handoff must carry one task brief per task (decision 40). */
|
|
5
8
|
export function requiredBriefs(lp) {
|
|
@@ -50,6 +53,37 @@ export function coversCriterion(entry, criterion) {
|
|
|
50
53
|
* awaiting-approval (used before asking the user to approve). With `stacks` (stack -> the task kinds
|
|
51
54
|
* of its engineer), every task must name a stack whose engineer can do its taskKind.
|
|
52
55
|
*/
|
|
56
|
+
/**
|
|
57
|
+
* A dependsOn cycle among the tasks, as its path ("T1 -> T2 -> T1"), or null (decision 58). The rule
|
|
58
|
+
* of the runtime's waves() (src/adapters/claude/runtime.ts): a task is ready once every task it
|
|
59
|
+
* depends on is done, a dependency that is not one of the tasks never holds it back, and the
|
|
60
|
+
* tasks left when none is ready hold a cycle.
|
|
61
|
+
*/
|
|
62
|
+
export function dependsOnCycle(tasks) {
|
|
63
|
+
const ids = new Set(tasks.map((t) => t.id));
|
|
64
|
+
const deps = (t) => (t.dependsOn ?? []).filter((d) => ids.has(d));
|
|
65
|
+
const done = new Set();
|
|
66
|
+
let left = tasks.slice();
|
|
67
|
+
while (left.length) {
|
|
68
|
+
const ready = left.filter((t) => deps(t).every((d) => done.has(d)));
|
|
69
|
+
if (!ready.length)
|
|
70
|
+
break;
|
|
71
|
+
for (const t of ready)
|
|
72
|
+
done.add(t.id);
|
|
73
|
+
left = left.filter((t) => !done.has(t.id));
|
|
74
|
+
}
|
|
75
|
+
if (!left.length)
|
|
76
|
+
return null;
|
|
77
|
+
// Every task left waits on another task left: follow the first such dependency until one repeats.
|
|
78
|
+
const byId = new Map(left.map((t) => [t.id, t]));
|
|
79
|
+
const path = [];
|
|
80
|
+
let at = left[0];
|
|
81
|
+
while (!path.includes(at.id)) {
|
|
82
|
+
path.push(at.id);
|
|
83
|
+
at = byId.get(deps(at).find((d) => byId.has(d)));
|
|
84
|
+
}
|
|
85
|
+
return [...path.slice(path.indexOf(at.id)), at.id];
|
|
86
|
+
}
|
|
53
87
|
export function checkHandoff(file, opts = {}) {
|
|
54
88
|
let data;
|
|
55
89
|
try {
|
|
@@ -94,6 +128,10 @@ export function checkHandoff(file, opts = {}) {
|
|
|
94
128
|
if (!ids.has(c))
|
|
95
129
|
problems.push(`task ${t.id}: closedBy names unknown task ${c}`);
|
|
96
130
|
}
|
|
131
|
+
// Before any run: the runtime would fail its first wave on it (decision 58).
|
|
132
|
+
const cycle = dependsOnCycle(h.tasks);
|
|
133
|
+
if (cycle)
|
|
134
|
+
problems.push(`dependsOn cycle: ${cycle.join(" -> ")}; no task in it can start`);
|
|
97
135
|
// Every scope acceptance criterion maps to at least one task (decision 50). Handoffs written
|
|
98
136
|
// before tasks had `covers` are still ready, with a warning.
|
|
99
137
|
const acceptance = h.scope.acceptance;
|
|
@@ -213,7 +251,36 @@ export function checkHandoff(file, opts = {}) {
|
|
|
213
251
|
problems.push("handoff.md does not match handoff.yaml: run friday handoff render (never edit handoff.md)");
|
|
214
252
|
}
|
|
215
253
|
}
|
|
216
|
-
|
|
254
|
+
// DSL first, code after (decision 65): every new or changed interface contract is a DSL delivery
|
|
255
|
+
// can code from, before any run. A contract written before it (no change) is reported, not refused.
|
|
256
|
+
const ics = h.interfaceContracts ?? [];
|
|
257
|
+
for (const x of contractIssues(ics, h.shapes ?? {})) {
|
|
258
|
+
const c = ics.find((i) => x.startsWith(`${i.id}: `) || x.startsWith(`${i.id}.`));
|
|
259
|
+
if (c && !c.change)
|
|
260
|
+
warnings.push(`interface contract ${x} (decision 65; written before the DSL)`);
|
|
261
|
+
else
|
|
262
|
+
problems.push(`interface contract ${x}`);
|
|
263
|
+
}
|
|
264
|
+
const taskIdSet = new Set(h.tasks.map((t) => t.id));
|
|
265
|
+
for (const c of ics.filter((i) => i.change === "new" || i.change === "changed")) {
|
|
266
|
+
for (const u of (c.consumers ?? []).filter((x) => taskIdSet.has(x))) {
|
|
267
|
+
const b = (h.briefs ?? []).find((x) => x.task === u);
|
|
268
|
+
if (h.briefs && b && !(b.interfaces ?? []).includes(c.id))
|
|
269
|
+
problems.push(`interface contract ${c.id}: task ${u} consumes it, but its brief does not name it in interfaces`);
|
|
270
|
+
}
|
|
271
|
+
if (c.spec?.file && !existsSync(resolve(opts.root ?? process.cwd(), c.spec.file)))
|
|
272
|
+
problems.push(`interface contract ${c.id}: spec file ${c.spec.file} is not in the repository`);
|
|
273
|
+
}
|
|
274
|
+
// The run's worst-case prompt tokens spent on the handoff, before it starts (decision 61).
|
|
275
|
+
let estimate;
|
|
276
|
+
const w = opts.budget?.orchestrations.find((o) => o.id === h.workflow);
|
|
277
|
+
if (w && w.stream === "downstream") {
|
|
278
|
+
estimate = promptTokenEstimate(w, data, opts.budget.pack);
|
|
279
|
+
const cap = opts.budget.pack.agentCallBudget?.warnPromptTokensAbove;
|
|
280
|
+
if (cap !== undefined && estimate.promptTokens > cap)
|
|
281
|
+
warnings.push(`${estimate.text}; above agentCallBudget.warnPromptTokensAbove (${cap.toLocaleString("en-US")})`);
|
|
282
|
+
}
|
|
283
|
+
return { ok: problems.length === 0, status: h.status, problems, warnings, ...(estimate ? { estimate } : {}) };
|
|
217
284
|
}
|
|
218
285
|
/** Where the readable handoff lives: next to the yaml, same name, .md. */
|
|
219
286
|
export function readablePath(file) {
|
|
@@ -226,7 +293,7 @@ function dependencyOrder(tasks) {
|
|
|
226
293
|
const left = [...tasks];
|
|
227
294
|
while (left.length) {
|
|
228
295
|
const i = left.findIndex((t) => t.dependsOn.every((d) => done.has(d) || !tasks.some((x) => x.id === d)));
|
|
229
|
-
const [next] = left.splice(i < 0 ? 0 : i, 1); // a cycle (refused by the check) keeps the order
|
|
296
|
+
const [next] = left.splice(i < 0 ? 0 : i, 1); // a cycle (refused by the check, dependsOnCycle) keeps the order
|
|
230
297
|
out.push(next);
|
|
231
298
|
done.add(next.id);
|
|
232
299
|
}
|
|
@@ -237,7 +304,7 @@ const sentence = (v) => v.trim().replace(/[.\s]+$/, "") + ".";
|
|
|
237
304
|
const cell = (v) => String(v ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
|
|
238
305
|
const list = (items) => (items ?? []).map((i) => `- ${i}`);
|
|
239
306
|
/** Fields with their own section; every other field is shown as YAML, so nothing is hidden. */
|
|
240
|
-
const LAID_OUT = new Set(["workId", "status", "workflow", "approvedBy", "checkpoints", "briefs", "scope", "decisions", "dataClassification", "promptPyramid", "prerequisites", "tasks", "questions", "gaps", "openQuestions"]);
|
|
307
|
+
const LAID_OUT = new Set(["workId", "status", "workflow", "approvedBy", "checkpoints", "briefs", "scope", "decisions", "interfaceContracts", "dataClassification", "promptPyramid", "prerequisites", "tasks", "questions", "gaps", "openQuestions"]);
|
|
241
308
|
/** handoff.md: the text a person reads and approves, rendered deterministically from the yaml. */
|
|
242
309
|
export function renderHandoff(h) {
|
|
243
310
|
const out = [
|
|
@@ -270,6 +337,12 @@ export function renderHandoff(h) {
|
|
|
270
337
|
out.push("", "## Decisions", "");
|
|
271
338
|
for (const d of h.decisions)
|
|
272
339
|
out.push(`- **${d.id}** ${sentence(d.decision)} Why: ${sentence(d.why)}${d.where ? ` Where: ${sentence(d.where)}` : ""}`);
|
|
340
|
+
// DSL first, code after (decision 65): the contracts as signatures, and who owns, realizes and
|
|
341
|
+
// uses each, drawn from the DSL; the shapes they name follow as YAML with the other fields.
|
|
342
|
+
const ics = (h.interfaceContracts ?? []);
|
|
343
|
+
if (ics.length) {
|
|
344
|
+
out.push("", "## Interface contracts", "", ...ics.flatMap((c) => contractLines(c)), "", "```mermaid", contractsMermaid(ics), "```");
|
|
345
|
+
}
|
|
273
346
|
out.push("", "## Data classification", "", "| Entity | Class | Owner | Retention | Fields |", "| --- | --- | --- | --- | --- |");
|
|
274
347
|
for (const c of h.dataClassification)
|
|
275
348
|
out.push(`| ${cell(c.entity)} | ${cell(c.class)} | ${cell(c.owner)} | ${cell(c.retention)} | ${cell((c.fields ?? []).join(", "))} |`);
|
package/dist/ir.js
CHANGED
package/dist/load.js
CHANGED
|
@@ -26,6 +26,9 @@ export function loadRawPack(pack) {
|
|
|
26
26
|
readYaml(dir, "model-policy.yaml", raw, "model-policy");
|
|
27
27
|
else
|
|
28
28
|
raw.parseErrors.push({ file: "model-policy.yaml", message: "missing" });
|
|
29
|
+
// The project's documented decisions, by topic (decision 64); optional.
|
|
30
|
+
if (existsSync(join(dir, "decisions.yaml")))
|
|
31
|
+
readYaml(dir, "decisions.yaml", raw, "decisions");
|
|
29
32
|
for (const [kind, folder] of FOLDERS) {
|
|
30
33
|
const sub = join(dir, folder);
|
|
31
34
|
if (!existsSync(sub))
|