@digital-agora/friday 0.10.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.
Files changed (38) hide show
  1. package/README.md +8 -4
  2. package/bundles/friday-claude-0.1.0.zip +0 -0
  3. package/bundles/friday-opencode-0.1.0.zip +0 -0
  4. package/dist/adapters/claude/index.js +2 -1
  5. package/dist/adapters/claude/runtime.js +331 -51
  6. package/dist/adapters/claude/workflows.js +95 -35
  7. package/dist/adapters/drivers.js +49 -14
  8. package/dist/adapters/opencode/index.js +2 -1
  9. package/dist/adapters/skill.js +16 -5
  10. package/dist/cli.js +42 -7
  11. package/dist/contracts.js +200 -0
  12. package/dist/flow.js +227 -0
  13. package/dist/graph.js +18 -7
  14. package/dist/handoff.js +76 -3
  15. package/dist/ir.js +1 -0
  16. package/dist/load.js +3 -0
  17. package/dist/prompts.js +81 -5
  18. package/dist/reads.js +75 -0
  19. package/dist/slice.js +90 -0
  20. package/dist/specialize.js +10 -0
  21. package/dist/step-schemas.js +28 -3
  22. package/dist/validate.js +38 -3
  23. package/pack/model-policy.yaml +5 -0
  24. package/pack/orchestrations/architecture-decision.yaml +5 -0
  25. package/pack/orchestrations/bugfix-tdd.yaml +1 -1
  26. package/pack/orchestrations/discovery.yaml +16 -3
  27. package/pack/orchestrations/feature-delivery.yaml +21 -3
  28. package/pack/orchestrations/prompt-delivery.yaml +25 -5
  29. package/pack/orchestrations/prompt-discovery.yaml +3 -0
  30. package/pack/pack.yaml +12 -2
  31. package/pack/personas/backend-engineer.yaml +1 -1
  32. package/pack/personas/devops-engineer.yaml +1 -1
  33. package/pack/personas/frontend-engineer.yaml +1 -1
  34. package/package.json +1 -1
  35. package/schemas/decisions.schema.yaml +28 -0
  36. package/schemas/handoff.schema.yaml +66 -4
  37. package/schemas/orchestration.schema.yaml +20 -4
  38. 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,7 +1,13 @@
1
1
  import { outputsOf } from "./types.js";
2
+ import { stepPlaces } from "./reads.js";
3
+ import { DECIDER_FACTOR, gateCalls, tddCalls } from "./flow.js";
2
4
  const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
3
- /** `handoff`: the run has a handoff to go back to (downstream, not release from changesets). */
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
+ */
4
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)` : ""}`;
5
11
  const escalation = handoff
6
12
  ? "an agent returns blocked -> the delivery decider settles it or the run stops with needs-upstream"
7
13
  : "an agent returns blocked -> the run stops with blocked";
@@ -10,21 +16,21 @@ export function loopExits(step, handoff = true) {
10
16
  return {
11
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`,
12
18
  failure: `still not green after round ${step.maxRounds}`,
13
- 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`,
14
- 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)" : ""}`,
15
21
  };
16
22
  case "gate":
17
23
  return {
18
24
  success: "the review passes",
19
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)",
20
- 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))}`,
21
27
  escalation,
22
28
  };
23
29
  case "integration-loop":
24
30
  return {
25
31
  success: `every stack green, every level in scope (${step.testScope.join(", ")}) reported with no failed suite, and no follow-ups`,
26
32
  failure: `red with no follow-ups, or follow-ups left after round ${step.maxRounds}`,
27
- 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`,
28
34
  escalation,
29
35
  };
30
36
  }
@@ -166,10 +172,15 @@ export function orchestrationGraph(w) {
166
172
  route("round-limit", id, `checkpoint after round ${w.maxRounds} (+ extraRounds): the user freezes the scope, extends or stops`);
167
173
  };
168
174
  const last = chain(w.steps, at("start"));
175
+ // Data edges (decision 55): what each step with `reads` is given from earlier steps.
176
+ for (const [id, p] of stepPlaces(w))
177
+ for (const r of p.step.reads ?? [])
178
+ g.edges.push({ from: r, to: id, label: "reads", data: true });
169
179
  const end = down ? "done" : "awaiting-approval";
170
180
  for (const e of last)
171
181
  route(end, e.from, down ? "every step finished" : "the handoff is written; a person approves it");
172
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" });
173
184
  g.agentExits.push({
174
185
  status: handoff ? "needs-upstream" : "blocked",
175
186
  from: "any agent step",
@@ -182,7 +193,7 @@ const emitsWorkflow = (w) => outputsOf(w).includes("workflow");
182
193
  const mid = (id) => `n_${id.replace(/[^A-Za-z0-9_]/g, "_")}`;
183
194
  const tid = (status) => `t_${status.replace(/[^A-Za-z0-9_]/g, "_")}`;
184
195
  const esc = (s) => s.replace(/"/g, "'");
185
- /** A Mermaid flowchart: steps, routes, loop back-edges and the terminals each step reaches. */
196
+ /** A Mermaid flowchart: steps, routes, loop back-edges, data edges (--o) and the terminals each step reaches. */
186
197
  export function renderMermaid(g) {
187
198
  const lines = ["flowchart TD"];
188
199
  for (const n of g.nodes) {
@@ -194,7 +205,7 @@ export function renderMermaid(g) {
194
205
  for (const s of statuses)
195
206
  lines.push(` ${tid(s)}((("${s}")))`);
196
207
  for (const e of g.edges) {
197
- const arrow = e.back ? "-.->" : "-->";
208
+ const arrow = e.data ? "--o" : e.back ? "-.->" : "-->";
198
209
  lines.push(` ${mid(e.from)} ${arrow}${e.label ? `|"${esc(e.label)}"|` : ""} ${mid(e.to)}`);
199
210
  }
200
211
  const seen = new Set();
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
- return { ok: problems.length === 0, status: h.status, problems, warnings };
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
@@ -143,6 +143,7 @@ export function buildIR(lp) {
143
143
  orchestrations: lp.orchestrations,
144
144
  agentIndex,
145
145
  instructions: renderInstructions(lp),
146
+ decisions: lp.decisions ?? [],
146
147
  };
147
148
  }
148
149
  function renderInstructions(lp) {
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))