@digital-agora/friday 0.11.0 → 0.13.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 +7 -4
- package/bundles/friday-claude-0.13.0.zip +0 -0
- package/bundles/friday-opencode-0.13.0.zip +0 -0
- package/dist/adapters/claude/index.js +2 -1
- package/dist/adapters/claude/runtime.js +298 -49
- package/dist/adapters/claude/workflows.js +94 -36
- package/dist/adapters/drivers.js +44 -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 +230 -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 +88 -5
- package/dist/reads.js +1 -1
- package/dist/slice.js +126 -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 +14 -3
- 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 +2 -2
- 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
- package/bundles/friday-claude-0.1.0.zip +0 -0
- package/bundles/friday-opencode-0.1.0.zip +0 -0
package/README.md
CHANGED
|
@@ -52,7 +52,7 @@ npx -y @digital-agora/friday install --target opencode --dir ../my-project
|
|
|
52
52
|
```
|
|
53
53
|
|
|
54
54
|
```bash
|
|
55
|
-
npx -y @digital-agora/friday install --from ./friday-claude
|
|
55
|
+
npx -y @digital-agora/friday install --from ./friday-claude-<version>.zip --dir .
|
|
56
56
|
```
|
|
57
57
|
|
|
58
58
|
`--dry-run` shows what would change. Installing again only updates files Friday wrote; a file you
|
|
@@ -96,7 +96,10 @@ npx -y @digital-agora/friday install --with ./path/to/specialization --with @acm
|
|
|
96
96
|
```
|
|
97
97
|
|
|
98
98
|
A project rule cites its repository (`<repo>/<path>`, a repository in the specialization's
|
|
99
|
-
`sources`); `friday validate --with <it>` checks the merged pack.
|
|
99
|
+
`sources`); `friday validate --with <it>` checks the merged pack. A specialization (or a project's
|
|
100
|
+
`.friday/`) may also hold `decisions.yaml`, the project's documented decisions by topic
|
|
101
|
+
(`schemas/decisions.schema.yaml`): discovery settles an open item whose topic a decision lists
|
|
102
|
+
instead of asking it, and keeps one that contradicts the decision for the user (decision 64).
|
|
100
103
|
|
|
101
104
|
A specialization can build on another with `extends` in `specialization.yaml` (a folder, or a
|
|
102
105
|
package it depends on); what it extends is applied first, so it wins (decision 53):
|
|
@@ -244,10 +247,10 @@ decide comes back as questions, never as a note (decisions 48-52).
|
|
|
244
247
|
```text
|
|
245
248
|
friday install [-t target] [-g | -d dir] [--from zip|url] [--with spec]... [--no-project-conventions] [--force] [--dry-run]
|
|
246
249
|
friday list [--with spec]... agents (with models) and workflows
|
|
247
|
-
friday validate [--with spec]...
|
|
250
|
+
friday validate [--with spec]... [--pack dir] schemas + cross-references + sources + model policy + test pyramid + orchestration check (data flow, loop limits, agent-call budgets)
|
|
248
251
|
friday build [-t target] [-o dir] [--with spec]... unpacked bundles
|
|
249
252
|
friday bundle [-t target] [-o dir] [--with spec]... friday-<target>-<version>.zip
|
|
250
|
-
friday graph [orchestration] [--with spec]... steps, routes, loops, what each step reads and every way a run can end (Mermaid + table)
|
|
253
|
+
friday graph [orchestration] [--with spec]... [-o file] steps, routes, loops, budgets, what each step reads and every way a run can end (Mermaid + table); CI posts it on each pull request
|
|
251
254
|
friday handoff render <file> write the readable handoff.md next to handoff.yaml
|
|
252
255
|
friday handoff check <file> [--pending]
|
|
253
256
|
```
|
|
Binary file
|
|
Binary file
|
|
@@ -109,7 +109,8 @@ function orchestrations(ir) {
|
|
|
109
109
|
function driverSkill(w, ir) {
|
|
110
110
|
const ask = ASK;
|
|
111
111
|
const run = `Call the Workflow tool with \`name: "${w.id}"\` and \`args\``;
|
|
112
|
-
const driver = w.stream === "upstream"
|
|
112
|
+
const driver = w.stream === "upstream"
|
|
113
|
+
? upstreamDriver(w, { run, ask, rerun: "Start the next round as a resume of this round's run (`resumeFromRunId` with its run id) with the new args: those steps replay from the cache and the rest run again. If the run cannot be resumed, run it afresh." }, ir.pack.id)
|
|
113
114
|
: w.requires?.includes("changesets") ? releaseDriver(w, { run, ask })
|
|
114
115
|
: downstreamDriver(w, { run, ask }, ir.pack.id);
|
|
115
116
|
const skill = withFrontmatter({
|
|
@@ -55,11 +55,33 @@ function resolveRef(ref, item) {
|
|
|
55
55
|
return { persona: persona, kind: kind, agentType: agentType, model: ref.model || policy.model, effort: ref.effort || policy.effort };
|
|
56
56
|
}
|
|
57
57
|
|
|
58
|
-
//
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
58
|
+
// Upstream rounds re-run from the earliest step an answer concerns (decision 59). An answer
|
|
59
|
+
// belongs to the step whose id prefixes its id ("<step>.<id>"), a gap resolution to its gap's step;
|
|
60
|
+
// one with no known step (a directive) belongs to every step. A step sees the answers of its own
|
|
61
|
+
// step and of the steps before it, so a step before the earliest step this round's answers belong
|
|
62
|
+
// to gets the same prompt as the round before, and a resumed run replays it from the cache.
|
|
63
|
+
const STEP_INDEX = {};
|
|
64
|
+
// The bare id of every answered item ("gaps.C-format" -> "C-format"), for contradictions.
|
|
65
|
+
const ANSWERED_CONTRADICTIONS = new Set([].concat.apply([], (A.answers || []).map(function (a) { const i = String(a.id).indexOf("."); return i > 0 ? [String(a.id).slice(i + 1)] : []; })));
|
|
66
|
+
STEP_ORDER.forEach(function (id, i) { STEP_INDEX[id] = i; });
|
|
67
|
+
function ownerIndex(x) {
|
|
68
|
+
const s = (x && x.step) || String((x && x.id) || "").split(".")[0];
|
|
69
|
+
return STEP_INDEX[s] === undefined ? -1 : STEP_INDEX[s];
|
|
70
|
+
}
|
|
71
|
+
function seenBy(stepId) {
|
|
72
|
+
const here = STEP_INDEX[stepId];
|
|
73
|
+
return function (x) { const o = ownerIndex(x); return here === undefined || o < 0 || o <= here; };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// An answer that settles a contradiction lists the answers it replaces in supersedes. A step that
|
|
77
|
+
// does not see the replacing answer keeps the one it replaces (its result predates the settlement).
|
|
78
|
+
function answersFor(stepId) {
|
|
79
|
+
const qa = (A.answers || []).concat(state.autoAnswers || []).filter(seenBy(stepId));
|
|
80
|
+
const replaced = new Set([].concat.apply([], qa.map(function (a) { return a.supersedes || []; })));
|
|
81
|
+
return qa.filter(function (a) { return !replaced.has(a.id); });
|
|
82
|
+
}
|
|
83
|
+
function answersText(stepId) {
|
|
84
|
+
const qa = answersFor(stepId);
|
|
63
85
|
if (!qa.length) return "(none yet)";
|
|
64
86
|
return qa.map(function (a) {
|
|
65
87
|
const sup = (a.supersedes || []).length ? "\n Replaces: " + a.supersedes.join(", ") : "";
|
|
@@ -69,20 +91,20 @@ function answersText() {
|
|
|
69
91
|
}).join("\n");
|
|
70
92
|
}
|
|
71
93
|
|
|
72
|
-
function
|
|
73
|
-
|
|
94
|
+
function gapsFor(stepId) { return (A.gapResolutions || []).filter(seenBy(stepId)); }
|
|
95
|
+
function gapsText(stepId) {
|
|
96
|
+
const g = gapsFor(stepId);
|
|
74
97
|
if (!g.length) return "(none yet)";
|
|
75
98
|
return g.map(function (x) { return "- " + x.id + " [" + x.area + "] " + x.gap + "\n Resolution: " + x.resolution; }).join("\n");
|
|
76
99
|
}
|
|
77
100
|
|
|
78
|
-
|
|
101
|
+
// No round number in a prompt: it would change every step's prompt every round, and nothing would
|
|
102
|
+
// replay. A step told about earlier answers is told to ask only what they newly raise.
|
|
103
|
+
function roundText(stepId) {
|
|
79
104
|
if (FROZEN) {
|
|
80
|
-
return "
|
|
105
|
+
return "Scope frozen: the user froze the scope. Anything the answers above do not settle is out of scope for this work; report it only if a planned task cannot be written or tested without it.";
|
|
81
106
|
}
|
|
82
|
-
|
|
83
|
-
const last = ROUND_LIMIT && ROUND >= ROUND_LIMIT ? " This is the last round: anything still open is shown to the user, who freezes the scope or allows more rounds." : "";
|
|
84
|
-
const later = ROUND > 1 ? " Ask only what the newest answers raise or still leave open; do not reopen what earlier rounds settled." : "";
|
|
85
|
-
return "Question round " + ROUND + of + "." + later + last;
|
|
107
|
+
return answersFor(stepId).length || gapsFor(stepId).length ? "Ask only what the newest answers raise or still leave open; do not reopen what earlier rounds settled." : "";
|
|
86
108
|
}
|
|
87
109
|
|
|
88
110
|
// Optional run inputs every step sees: the domain glossary and facts about the environment
|
|
@@ -102,28 +124,38 @@ function factsText() {
|
|
|
102
124
|
return parts;
|
|
103
125
|
}
|
|
104
126
|
|
|
105
|
-
// Slice-scoped prompts
|
|
106
|
-
// on, the decisions that touch its codebase (or name no place), the data classification, the
|
|
127
|
+
// Slice-scoped prompts, the default for a task (decision 60; args.sliceScoped: false gives every
|
|
128
|
+
// agent the whole handoff again): a task agent gets its task and the tasks it depends on, the decisions that touch its codebase (or name no place), the data classification, the
|
|
107
129
|
// command map and the standing policy; not the whole handoff. Smaller prompts, stable cache keys.
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
130
|
+
// The slice also keeps what the upstream run fixed for this task: the criteria it covers, the
|
|
131
|
+
// contracts that list it (or list no task), the interface contracts its brief names (all when the
|
|
132
|
+
// brief names none), the standards, its build plan entry and the red tests it owns.
|
|
133
|
+
const SLICED = A.sliceScoped !== false;
|
|
134
|
+
// A step outside the task loop gets an index of the handoff and its path, not the whole of it, when
|
|
135
|
+
// the run passes args.handoffPath (decision 66); args.handoffIndex: false gives it the whole again.
|
|
136
|
+
const INDEXED = typeof A.handoffPath === "string" && A.handoffPath.length > 0 && A.handoffIndex !== false;
|
|
137
|
+
// handoffSlice is src/slice.ts, embedded in the script by the compiler: the estimate in
|
|
138
|
+
// friday handoff check counts the same slice (decision 61).
|
|
139
|
+
function sliceOf(item) { return handoffSlice(HANDOFF, item, COMMANDS); }
|
|
113
140
|
|
|
114
141
|
function context(stepId, item) {
|
|
115
142
|
const parts = ["Workflow " + WORKFLOW.id + " (" + WORKFLOW.stream + "), step " + stepId + "."].concat(factsText());
|
|
116
143
|
if (WORKFLOW.stream === "upstream") {
|
|
117
144
|
parts.push("Work id: " + (A.workId || "(missing)"));
|
|
118
145
|
parts.push("Request:\n" + (A.request || "(missing)"));
|
|
146
|
+
if (DECISIONS_TEXT) parts.push(DECISIONS_TEXT);
|
|
119
147
|
if (A.answersFile) {
|
|
120
|
-
|
|
121
|
-
|
|
148
|
+
// The ids this step may read change its prompt exactly when its answers do (decision 59).
|
|
149
|
+
const ids = answersFor(stepId).map(function (x) { return x.id; }).concat(gapsFor(stepId).map(function (x) { return x.id; }));
|
|
150
|
+
parts.push("Questions already answered and gaps already resolved by the user are in " + A.answersFile + " (answers, gapResolutions). Read it before you start, only the entries with these ids: " + (ids.join(", ") || "(none yet)") + ". Do not ask or report them again; where an answer lists supersedes, only it counts.");
|
|
151
|
+
const auto = (state.autoAnswers || []).filter(seenBy(stepId));
|
|
152
|
+
if (auto.length) parts.push("Answered in this run by the close-out rule:\n" + auto.map(function (a) { return "- " + a.id + ": " + a.question + "\n Answer: " + a.answer + " (close-out: recommended option)"; }).join("\n"));
|
|
122
153
|
} else {
|
|
123
|
-
parts.push("Questions already answered by the user (do not ask them again; build on the answers):\n" + answersText());
|
|
124
|
-
parts.push("Gaps already resolved by the user (do not report them again):\n" + gapsText());
|
|
154
|
+
parts.push("Questions already answered by the user (do not ask them again; build on the answers):\n" + answersText(stepId));
|
|
155
|
+
parts.push("Gaps already resolved by the user (do not report them again):\n" + gapsText(stepId));
|
|
125
156
|
}
|
|
126
|
-
|
|
157
|
+
const rt = roundText(stepId);
|
|
158
|
+
if (rt) parts.push(rt);
|
|
127
159
|
if (state.deferred.length) {
|
|
128
160
|
parts.push("Deferred items (not blockers for this work): record each in scope.outOfScope as a follow-up work item, plan no task for it and do not ask about it:\n" + JSON.stringify(state.deferred));
|
|
129
161
|
}
|
|
@@ -132,8 +164,10 @@ function context(stepId, item) {
|
|
|
132
164
|
// handoff; it comes first, and the handoff or its slice still follows as the source of truth.
|
|
133
165
|
const tb = HANDOFF && item && item.id && (HANDOFF.briefs || []).find(function (b) { return b.task === item.id; });
|
|
134
166
|
if (tb) parts.push("Task brief (approved with the handoff; the handoff below stays the source of truth):\n" + tb.text);
|
|
135
|
-
if (HANDOFF &&
|
|
167
|
+
if (HANDOFF && SLICED && item && item.codebase) {
|
|
136
168
|
parts.push("Approved handoff, scoped to this task (the only source of truth; anything it does not settle is a blocker, not a guess):\n" + JSON.stringify(sliceOf(item)));
|
|
169
|
+
} else if (HANDOFF && INDEXED) {
|
|
170
|
+
parts.push(HANDOFF_INDEX + "\n" + JSON.stringify(handoffIndex(HANDOFF, A.handoffPath)));
|
|
137
171
|
} else if (HANDOFF) {
|
|
138
172
|
parts.push("Approved handoff (the only source of truth; anything it does not settle is a blocker, not a guess):\n" + JSON.stringify(HANDOFF));
|
|
139
173
|
} else {
|
|
@@ -151,6 +185,7 @@ function context(stepId, item) {
|
|
|
151
185
|
}).join("\n"));
|
|
152
186
|
}
|
|
153
187
|
}
|
|
188
|
+
if (HANDOFF && WORKFLOW.stream === "downstream") parts.push(PRECEDENCE);
|
|
154
189
|
if (HANDOFF && HANDOFF.deliveryPolicy) {
|
|
155
190
|
parts.push("Standing delivery policy (what delivery may settle itself; record each such decision in your summary, never product, copy or security-widening):\n" + JSON.stringify(HANDOFF.deliveryPolicy));
|
|
156
191
|
}
|
|
@@ -225,10 +260,45 @@ function midRunAnswersText(stepId, item) {
|
|
|
225
260
|
});
|
|
226
261
|
if (!own.length) return "";
|
|
227
262
|
return "\n\n## Answers to the questions this step raised (from the user; settled, do not ask them again; ask only a question an answer newly creates)\n\n" +
|
|
228
|
-
own.map(function (a) {
|
|
263
|
+
own.map(function (a) {
|
|
264
|
+
const am = (a.amends || []).length ? "\n Amends (approved in the handoff; this answer wins over them): " + a.amends.join(", ") : "";
|
|
265
|
+
return "- Q: " + a.question + "\n A: " + a.answer + (a.interpretation ? "\n Interpretation: " + a.interpretation : "") + am;
|
|
266
|
+
}).join("\n");
|
|
267
|
+
}
|
|
268
|
+
// A mid-run answer that changes an approved decision, criterion or answer names them in amends
|
|
269
|
+
// (decision 57): it is a reversed answer, listed in the result and the retro, not only in a summary.
|
|
270
|
+
const AMENDMENTS = (Array.isArray(A.midRunAnswers) ? A.midRunAnswers : []).filter(function (a) { return a && (a.amends || []).length; });
|
|
271
|
+
// In the retro's reversed answers, an amendment has the shape of a recorded answer that supersedes
|
|
272
|
+
// others (id, question, answer, supersedes), so both are counted the same way.
|
|
273
|
+
function amendmentsAsAnswers() {
|
|
274
|
+
return AMENDMENTS.map(function (a) {
|
|
275
|
+
return { id: a.step + (a.item ? ":" + a.item : "") + ":" + a.question, question: a.question, answer: a.answer, supersedes: a.amends, midRun: true, step: a.step, item: a.item || null };
|
|
276
|
+
});
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
// Usage and caps (decision 61): every agent call counts, with its prompt's tokens estimated at 4
|
|
280
|
+
// characters a token (estimateTokens in src/slice.ts). args.maxAgentCalls and args.maxPromptTokens
|
|
281
|
+
// stop the run before the call that would pass them; a resumed run counts its replayed calls too.
|
|
282
|
+
state.usage = { calls: 0, promptTokens: 0 };
|
|
283
|
+
// Whole tokens, rounded up, without Math (the host and its test harness keep the script to plain arithmetic).
|
|
284
|
+
function tokensOf(text) { const n = String(text).length + 3; return (n - (n % 4)) / 4; }
|
|
285
|
+
const MAX_CALLS = count(A.maxAgentCalls, 0);
|
|
286
|
+
const MAX_PROMPT_TOKENS = count(A.maxPromptTokens, 0);
|
|
287
|
+
async function metered(stepId, item, prompt, opts) {
|
|
288
|
+
if (halted()) return null;
|
|
289
|
+
const t = tokensOf(prompt);
|
|
290
|
+
const over = MAX_CALLS && state.usage.calls + 1 > MAX_CALLS ? "args.maxAgentCalls (" + MAX_CALLS + ")"
|
|
291
|
+
: MAX_PROMPT_TOKENS && state.usage.promptTokens + t > MAX_PROMPT_TOKENS ? "args.maxPromptTokens (" + MAX_PROMPT_TOKENS + ")" : null;
|
|
292
|
+
if (over) {
|
|
293
|
+
stop({ status: "failed", step: stepId, item: item && item.id, reason: "the run reached " + over + " after " + state.usage.calls + " agent calls and about " + state.usage.promptTokens + " prompt tokens; resume it with a higher cap to go on", usage: state.usage });
|
|
294
|
+
return null;
|
|
295
|
+
}
|
|
296
|
+
state.usage.calls++;
|
|
297
|
+
state.usage.promptTokens += t;
|
|
298
|
+
return agent(prompt, opts);
|
|
229
299
|
}
|
|
230
300
|
|
|
231
|
-
async function call(stepId, ref, task, schema, item, phase) {
|
|
301
|
+
async function call(stepId, ref, task, schema, item, phase, noPark) {
|
|
232
302
|
if (halted()) return null;
|
|
233
303
|
task = withCommands(task);
|
|
234
304
|
const r = resolveRef(ref, item);
|
|
@@ -236,22 +306,34 @@ async function call(stepId, ref, task, schema, item, phase) {
|
|
|
236
306
|
const opts = { label: stepId + (item && item.id ? ":" + item.id : "") + " " + r.agentType, phase: phase, agentType: r.agentType, model: r.model, schema: schema };
|
|
237
307
|
if (r.effort) opts.effort = r.effort;
|
|
238
308
|
task = task + guideFor(schema) + midRunAnswersText(stepId, item);
|
|
239
|
-
let out = await
|
|
309
|
+
let out = await metered(stepId, item, context(stepId, item) + "\n\n## Your task\n\n" + task, opts);
|
|
240
310
|
if (out === null || out === undefined) { stop({ status: "failed", step: stepId, reason: r.agentType + " returned no result" }); return null; }
|
|
241
311
|
if (out.status === "blocked" && HANDOFF) {
|
|
242
312
|
// Decider in delivery: the lead developer settles what the standing policy allows; the step
|
|
243
313
|
// runs once more with the decision. Product, copy and security-widening still stop the run.
|
|
244
314
|
const d = await decide(stepId, item, out, phase);
|
|
245
315
|
if (d && d.settled) {
|
|
246
|
-
const again = await
|
|
316
|
+
const again = await metered(stepId, item, context(stepId, item) + "\n\n## Your task\n\n" + task + "\n\nDecision by the delivery decider (recorded, shown at the end): " + d.decision + " Why: " + (d.why || ""), opts);
|
|
247
317
|
if (again && again.status !== "blocked") return again;
|
|
248
318
|
if (again) out = again;
|
|
249
319
|
}
|
|
250
320
|
}
|
|
251
321
|
if (out.status === "blocked") {
|
|
252
|
-
// With a handoff, a blocker goes back upstream; without one (release) it is reported as is.
|
|
253
|
-
|
|
254
|
-
|
|
322
|
+
// With a handoff, a blocker goes back upstream; without one (release) it is reported as is. A
|
|
323
|
+
// blocker that names the tasks it affects parks only them (decision 56): an item's agents stop
|
|
324
|
+
// here, a step before the task loop keeps its result for the tasks that go on.
|
|
325
|
+
const why = (out.blocked && out.blocked.reason) || out.summary;
|
|
326
|
+
const qs = (out.blocked && out.blocked.questions) || [];
|
|
327
|
+
if (HANDOFF) {
|
|
328
|
+
// The preflight never parks: a workspace it could not prepare is not ready for any task.
|
|
329
|
+
const held = noPark ? null : park(stepId, item, why, qs, (out.blocked && out.blocked.tasks) || []);
|
|
330
|
+
if (held) {
|
|
331
|
+
if (item) return null;
|
|
332
|
+
// The partial result says which tasks it does not settle, so the steps that read it know.
|
|
333
|
+
return Object.assign({}, out, { parked: { tasks: held, note: "Not settled for these tasks: they wait for the answers to this step's blocker." } });
|
|
334
|
+
}
|
|
335
|
+
needsUpstream(stepId, item, why, qs);
|
|
336
|
+
} else stop({ status: "blocked", step: stepId, item: item && item.id, reason: (out.blocked && out.blocked.reason) || out.summary, questions: (out.blocked && out.blocked.questions) || [] });
|
|
255
337
|
}
|
|
256
338
|
return out;
|
|
257
339
|
}
|
|
@@ -259,7 +341,63 @@ async function call(stepId, ref, task, schema, item, phase) {
|
|
|
259
341
|
// A downstream stop the people upstream answer: the same run resumes with the answers.
|
|
260
342
|
function needsUpstream(stepId, item, reason, questions, extra) {
|
|
261
343
|
stop(Object.assign({ status: "needs-upstream", step: stepId, item: item && item.id, reason: reason, questions: questions || [],
|
|
262
|
-
resume: "Resume this same run (resumeFromRunId) with args.midRunAnswers [{ step: " + JSON.stringify(stepId) + (item && item.id ? ", item: " + JSON.stringify(item.id) : "") + ", question, answer }] and the same other args; do not edit the handoff argument, or every finished step runs again." }, extra || {}));
|
|
344
|
+
resume: "Resume this same run (resumeFromRunId) with args.midRunAnswers [{ step: " + JSON.stringify(stepId) + (item && item.id ? ", item: " + JSON.stringify(item.id) : "") + ", question, answer, interpretation, amends }] (amends: the ids of every approved decision, criterion or answer the answer changes; leave it out when it changes none), args.doneTasks as this result returns it, and the same other args; do not edit the handoff argument, or every finished step runs again." }, extra || {}));
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
// Parking (decision 56): until the task loop over handoff.tasks has run, a blocker that affects
|
|
348
|
+
// only some tasks parks them and the tasks that depend on them; the others go on. When the loop is
|
|
349
|
+
// over (or every task is parked) the run stops once, needs-upstream, with every parked blocker.
|
|
350
|
+
// args.parkBlocked: false stops at the first blocker instead. A workflow without that loop never
|
|
351
|
+
// parks: nothing would release the parked blockers.
|
|
352
|
+
state.parked = [];
|
|
353
|
+
state.parkedTasks = [];
|
|
354
|
+
state.parkOpen = !!HANDOFF && WORKFLOW.stream === "downstream" && WORKFLOW.taskLoop === true && A.parkBlocked !== false;
|
|
355
|
+
function taskIds() { return ((HANDOFF && HANDOFF.tasks) || []).map(function (t) { return t.id; }); }
|
|
356
|
+
function withDependents(ids) {
|
|
357
|
+
const out = ids.slice();
|
|
358
|
+
let grew = true;
|
|
359
|
+
while (grew) {
|
|
360
|
+
grew = false;
|
|
361
|
+
((HANDOFF && HANDOFF.tasks) || []).forEach(function (t) {
|
|
362
|
+
if (out.indexOf(t.id) < 0 && (t.dependsOn || []).some(function (d) { return out.indexOf(d) >= 0; })) { out.push(t.id); grew = true; }
|
|
363
|
+
});
|
|
364
|
+
}
|
|
365
|
+
return out;
|
|
366
|
+
}
|
|
367
|
+
function isParked(item) { return !!(item && item.id && state.parkedTasks.indexOf(item.id) >= 0); }
|
|
368
|
+
// Returns the ids of the tasks that now wait, or null when the blocker is not parked. A task whose
|
|
369
|
+
// own step blocked always waits, whatever else the blocker names; a task already done does not.
|
|
370
|
+
function park(stepId, item, reason, questions, tasks) {
|
|
371
|
+
if (!state.parkOpen) return null;
|
|
372
|
+
const all = taskIds();
|
|
373
|
+
let ids = (tasks || []).filter(function (t) { return all.indexOf(t) >= 0; });
|
|
374
|
+
if (item && item.id && all.indexOf(item.id) >= 0 && ids.indexOf(item.id) < 0) ids.push(item.id);
|
|
375
|
+
ids = ids.filter(function (t) { return state.done.indexOf(t) < 0; });
|
|
376
|
+
if (!ids.length) return null;
|
|
377
|
+
const waiting = withDependents(ids).filter(function (t) { return state.done.indexOf(t) < 0; });
|
|
378
|
+
const union = state.parkedTasks.concat(waiting.filter(function (t) { return state.parkedTasks.indexOf(t) < 0; }));
|
|
379
|
+
// Nothing would go on: stop now, as without parking.
|
|
380
|
+
if (!state.parked.length && union.length >= all.length) return null;
|
|
381
|
+
state.parked.push({ step: stepId, item: (item && item.id) || null, tasks: ids, waiting: waiting, reason: reason, questions: questions || [] });
|
|
382
|
+
state.parkedTasks = union;
|
|
383
|
+
trace(stepId, item, null, "parked", waiting.join(", ") + ": " + reason);
|
|
384
|
+
if (union.length >= all.length) releaseParked();
|
|
385
|
+
return waiting;
|
|
386
|
+
}
|
|
387
|
+
function releaseParked() {
|
|
388
|
+
state.parkOpen = false;
|
|
389
|
+
if (!state.parked.length || halted()) return;
|
|
390
|
+
const p = state.parked;
|
|
391
|
+
const first = p[0];
|
|
392
|
+
const qs = [].concat.apply([], p.map(function (x) { return x.questions; }));
|
|
393
|
+
const reason = p.length === 1 ? first.reason : p.length + " blockers parked tasks " + state.parkedTasks.join(", ") + ": " + p.map(function (x) { return x.reason; }).join(" | ");
|
|
394
|
+
const extra = { parked: p, parkedTasks: state.parkedTasks };
|
|
395
|
+
if (p.length > 1) extra.resume = "Resume this same run (resumeFromRunId) with args.midRunAnswers, one { step, item, question, answer, interpretation, amends } per question, with the step and item of the parked blocker it answers (see parked) and amends listing the ids of every approved decision, criterion or answer it changes (left out when it changes none), args.doneTasks as this result returns it, and the same other args; do not edit the handoff argument, or every finished step runs again.";
|
|
396
|
+
needsUpstream(first.step, first.item ? { id: first.item } : null, reason, qs, extra);
|
|
397
|
+
}
|
|
398
|
+
// A blocker found by the runtime itself (e.g. test design's questions) parks the same way.
|
|
399
|
+
function upstreamOrPark(stepId, item, reason, questions) {
|
|
400
|
+
if (!park(stepId, item, reason, questions, [])) needsUpstream(stepId, item, reason, questions);
|
|
263
401
|
}
|
|
264
402
|
|
|
265
403
|
// Test file -> the task whose red step wrote it. Verify reads it to tell its own failures from
|
|
@@ -271,22 +409,34 @@ function ownersText(item) {
|
|
|
271
409
|
return "\n\nTest ownership (owned by other tasks; their failures are not this task's):\n" + others.map(function (f) { return "- " + f + ": " + state.testOwners[f]; }).join("\n");
|
|
272
410
|
}
|
|
273
411
|
// A foreign failure counts only when its owner is another known task; anything else is this task's.
|
|
274
|
-
|
|
412
|
+
// Each one that does not count says why, so a round it makes red never comes back with no failure.
|
|
413
|
+
function foreignProblems(v, item) {
|
|
275
414
|
const ids = Object.keys(state.testOwners).map(function (f) { return state.testOwners[f]; });
|
|
276
|
-
return (v.foreignFailures || []).
|
|
415
|
+
return (v.foreignFailures || []).map(function (x) {
|
|
416
|
+
const t = (x && x.test) || "a test";
|
|
417
|
+
if (!x || !x.owner) return t + " fails and verify named no owner for it, so it counts as this task's";
|
|
418
|
+
if (x.owner === (item && item.id)) return t + " fails and is this task's own test";
|
|
419
|
+
if (ids.indexOf(x.owner) < 0) return t + " fails; verify says " + x.owner + " owns it, but no task of this run has written tests for " + x.owner + " yet, so it counts as this task's";
|
|
420
|
+
return null;
|
|
421
|
+
}).filter(Boolean);
|
|
277
422
|
}
|
|
423
|
+
function foreignOk(v, item) { return !foreignProblems(v, item).length; }
|
|
278
424
|
|
|
279
425
|
state.decisions = [];
|
|
426
|
+
// The decider's answer applies only when its kind is on deliveryPolicy.maySettle (decision 56); with
|
|
427
|
+
// args.decider and no policy, any kind but the three that are never delivery's.
|
|
280
428
|
async function decide(stepId, item, out, phase) {
|
|
281
429
|
if (!DECIDER || !(HANDOFF.deliveryPolicy || A.decider)) return null;
|
|
282
430
|
const r = resolveRef(DECIDER, null);
|
|
283
431
|
if (r.error) return null;
|
|
284
432
|
const q = ((out.blocked && out.blocked.reason) || out.summary) + "\n" + JSON.stringify((out.blocked && out.blocked.questions) || []);
|
|
285
|
-
const d = await
|
|
433
|
+
const d = await metered("decide:" + stepId, item, context(stepId, item) + "\n\n## Your task\n\n" + DECIDE_BLOCKER + guideFor(SCHEMAS.DECISION) + "\n\nBlocked step " + stepId + (item && item.id ? " (" + item.id + ")" : "") + ":\n" + q,
|
|
286
434
|
{ label: "decide:" + stepId + (item && item.id ? ":" + item.id : "") + " " + r.agentType, phase: phase, agentType: r.agentType, model: r.model, schema: SCHEMAS.DECISION });
|
|
287
|
-
if (d) state.decisions.push({ step: stepId, item: item && item.id, settled: !!d.settled, kind: d.kind, decision: d.decision || null, why: d.why || null });
|
|
288
435
|
const never = ["product", "copy", "security-widening"];
|
|
289
|
-
|
|
436
|
+
const allowed = HANDOFF.deliveryPolicy ? (HANDOFF.deliveryPolicy.maySettle || []) : null;
|
|
437
|
+
const applied = !!(d && d.settled && never.indexOf(d.kind) < 0 && (!allowed || allowed.indexOf(d.kind) >= 0));
|
|
438
|
+
if (d) state.decisions.push({ step: stepId, item: item && item.id, settled: !!d.settled, applied: applied, kind: d.kind, decision: d.decision || null, why: d.why || null });
|
|
439
|
+
return applied ? d : null;
|
|
290
440
|
}
|
|
291
441
|
|
|
292
442
|
function key(stepId, item) { return item && item.id ? stepId + ":" + item.id : stepId; }
|
|
@@ -318,6 +468,45 @@ function guardGaps(stepId, out) {
|
|
|
318
468
|
});
|
|
319
469
|
}
|
|
320
470
|
|
|
471
|
+
// Working trees (decision 56): args.worktrees [{ path, branch }] or args.branch name the branch each
|
|
472
|
+
// working tree must be on; the preflight reports every tree's branch and uncommitted changes.
|
|
473
|
+
function expectedBranches() {
|
|
474
|
+
return (Array.isArray(A.worktrees) ? A.worktrees : A.branch ? [{ path: ".", branch: A.branch }] : []).filter(function (x) { return x && x.branch; });
|
|
475
|
+
}
|
|
476
|
+
function worktreesText() {
|
|
477
|
+
const w = expectedBranches();
|
|
478
|
+
if (!w.length) return "";
|
|
479
|
+
return "\n\nExpected branches (a working tree on another branch stops the run). Report each of these trees with its path exactly as written here:\n" + w.map(function (x) { return "- " + (x.path || ".") + ": " + x.branch; }).join("\n");
|
|
480
|
+
}
|
|
481
|
+
// "./apps/web/", "apps\\web" and "apps/web" name the same tree; "", "./" and "." the root.
|
|
482
|
+
function normPath(p) {
|
|
483
|
+
const s = String(p === undefined || p === null ? "." : p).trim().replace(/\\/g, "/").replace(/^(\.\/)+/, "").replace(/\/+$/, "");
|
|
484
|
+
return s === "" || s === "." ? "." : s;
|
|
485
|
+
}
|
|
486
|
+
// A reported tree is the expected one when the paths match, or when the reported path is absolute
|
|
487
|
+
// and ends in the expected one ("/home/u/repo/apps/web" for "apps/web").
|
|
488
|
+
function samePath(reported, expected) {
|
|
489
|
+
const r = normPath(reported);
|
|
490
|
+
return r === expected || (expected !== "." && ("/" + r).slice(-(expected.length + 1)) === "/" + expected);
|
|
491
|
+
}
|
|
492
|
+
// A named working tree that is on another branch, or that the preflight did not report, stops the run.
|
|
493
|
+
function wrongBranches(out) {
|
|
494
|
+
const exp = expectedBranches();
|
|
495
|
+
const seen = ((out && out.worktrees) || []).filter(Boolean);
|
|
496
|
+
const paths = exp.map(function (e) { return normPath(e.path); });
|
|
497
|
+
return exp.map(function (e, i) {
|
|
498
|
+
const path = paths[i];
|
|
499
|
+
let r = seen.find(function (x) { return samePath(x.path, path); });
|
|
500
|
+
// The root reported under its absolute path: the one report no other expected tree claims.
|
|
501
|
+
if (!r && path === ".") {
|
|
502
|
+
const free = seen.filter(function (x) { return !paths.some(function (q) { return q !== "." && samePath(x.path, q); }); });
|
|
503
|
+
if (free.length === 1) r = free[0];
|
|
504
|
+
}
|
|
505
|
+
if (!r) return path + ": not reported (expected " + e.branch + ")";
|
|
506
|
+
return r.branch === e.branch ? null : path + ": on " + r.branch + ", expected " + e.branch;
|
|
507
|
+
}).filter(Boolean);
|
|
508
|
+
}
|
|
509
|
+
|
|
321
510
|
// Git step options: handoff.git, then args.git. Defaults keep the pack's behaviour (open a
|
|
322
511
|
// ready PR that links the handoff); an uncommitted handoff is never linked.
|
|
323
512
|
function gitText() {
|
|
@@ -334,7 +523,8 @@ function gitText() {
|
|
|
334
523
|
function retroFacts() {
|
|
335
524
|
return "\n\nRun facts:\n" + JSON.stringify({
|
|
336
525
|
halt: state.halt, round: ROUND, scopeFrozen: FROZEN,
|
|
337
|
-
reversedAnswers: (A.answers || []).filter(function (a) { return (a.supersedes || []).length; }),
|
|
526
|
+
reversedAnswers: (A.answers || []).filter(function (a) { return (a.supersedes || []).length; }).concat(amendmentsAsAnswers()),
|
|
527
|
+
parked: state.parked, usage: state.usage,
|
|
338
528
|
autoAnswers: state.autoAnswers || [], dropped: state.dropped, deferred: state.deferred,
|
|
339
529
|
redRounds: state.red || [], pyramidViolations: state.violations, foreignFailures: state.foreign,
|
|
340
530
|
trace: state.trace, testChanges: state.testChanges,
|
|
@@ -346,7 +536,11 @@ async function retro(ref, task) {
|
|
|
346
536
|
if (r.error) return null;
|
|
347
537
|
const opts = { label: "retro " + r.agentType, phase: "retro", agentType: r.agentType, model: r.model, schema: SCHEMAS.RETRO };
|
|
348
538
|
if (r.effort) opts.effort = r.effort;
|
|
349
|
-
|
|
539
|
+
// The retro is counted but never capped: it records why the run stopped, a cap included.
|
|
540
|
+
const prompt = context("retro", null) + "\n\n## Your task\n\n" + task + guideFor(SCHEMAS.RETRO) + retroFacts();
|
|
541
|
+
state.usage.calls++;
|
|
542
|
+
state.usage.promptTokens += tokensOf(prompt);
|
|
543
|
+
const out = await agent(prompt, opts);
|
|
350
544
|
return out ? { path: out.retroPath, improvements: out.improvements || [] } : null;
|
|
351
545
|
}
|
|
352
546
|
|
|
@@ -401,8 +595,12 @@ function consolidate(stepId, out) {
|
|
|
401
595
|
raw[k].forEach(function (x) { if (!seen.has(x.id)) next[k].push(x); });
|
|
402
596
|
});
|
|
403
597
|
state.questions = next.questions; state.assumptions = next.assumptions; state.gaps = next.gaps;
|
|
598
|
+
// Ids are "<step>.<id>" like every other item, so its answer belongs to this step (decision 59).
|
|
599
|
+
// A later consolidating step that reports the same contradiction again finds it settled.
|
|
404
600
|
(out.contradictions || []).forEach(function (c) {
|
|
405
|
-
|
|
601
|
+
const bare = String(c.id).indexOf(stepId + ".") === 0 ? String(c.id).slice(stepId.length + 1) : String(c.id);
|
|
602
|
+
const id = stepId + "." + bare;
|
|
603
|
+
if (!ANSWERED.has(id) && !ANSWERED.has(bare) && !ANSWERED_CONTRADICTIONS.has(bare)) state.contradictions.push(Object.assign({}, c, { id: id, step: stepId }));
|
|
406
604
|
});
|
|
407
605
|
}
|
|
408
606
|
|
|
@@ -411,6 +609,10 @@ function consolidate(stepId, out) {
|
|
|
411
609
|
// reason, unless it says it contradicts that answer.
|
|
412
610
|
const ANSWERED_TOPICS = {};
|
|
413
611
|
(A.answers || []).forEach(function (a) { if (a.topic) ANSWERED_TOPICS[a.topic] = a.id; });
|
|
612
|
+
// The join on documented decisions (decision 64): an item whose topic a decision lists is settled
|
|
613
|
+
// by it, unless it names that decision in contradicts; then it stays for the user to settle.
|
|
614
|
+
const DECISION_TOPICS = {};
|
|
615
|
+
DECISIONS.forEach(function (d) { d.topics.forEach(function (t) { DECISION_TOPICS[t] = d; }); });
|
|
414
616
|
function dedupe() {
|
|
415
617
|
const byTopic = {};
|
|
416
618
|
function pass(list) {
|
|
@@ -418,6 +620,11 @@ function dedupe() {
|
|
|
418
620
|
list.forEach(function (x) {
|
|
419
621
|
if (!x.topic) { out.push(x); return; }
|
|
420
622
|
const t = x.topic;
|
|
623
|
+
const dd = DECISION_TOPICS[t];
|
|
624
|
+
if (dd && (x.contradicts || []).indexOf(dd.id) < 0) {
|
|
625
|
+
state.dropped.push({ id: x.id, reason: "topic " + t + " is settled by documented decision " + dd.id + " (" + dd.source + ")", step: x.step, decision: dd.id });
|
|
626
|
+
return;
|
|
627
|
+
}
|
|
421
628
|
if (ANSWERED_TOPICS[t] && !(x.contradicts || []).length) {
|
|
422
629
|
state.dropped.push({ id: x.id, reason: "topic " + t + " is settled by answer " + ANSWERED_TOPICS[t], step: x.step });
|
|
423
630
|
return;
|
|
@@ -430,22 +637,27 @@ function dedupe() {
|
|
|
430
637
|
state.questions = pass(state.questions); state.assumptions = pass(state.assumptions); state.gaps = pass(state.gaps);
|
|
431
638
|
}
|
|
432
639
|
|
|
433
|
-
// Close-out (args.closeOut, the user's choice):
|
|
434
|
-
//
|
|
640
|
+
// Close-out (args.closeOut, the user's choice; decision 59): an item that changes what is built or
|
|
641
|
+
// how it behaves, a contradiction, and an item without a recommended option still go to the user;
|
|
642
|
+
// an item marked changesBehaviour: false takes its recommended option, recorded as an answer marked
|
|
643
|
+
// by close-out. Blocking does not keep an item: a technical detail can block planning and still
|
|
644
|
+
// have one safe answer.
|
|
435
645
|
const CLOSE_OUT = A.closeOut === true;
|
|
436
646
|
state.autoAnswers = [];
|
|
437
647
|
function closeOut() {
|
|
438
648
|
if (!CLOSE_OUT) return;
|
|
439
|
-
function keep(x) { return x.
|
|
649
|
+
function keep(x) { return x.changesBehaviour !== false || (x.contradicts || []).length > 0; }
|
|
440
650
|
function auto(x, answer) { state.autoAnswers.push({ id: x.id, question: x.question || x.assumption || x.gap, answer: answer, by: "close-out" }); }
|
|
441
651
|
state.questions = state.questions.filter(function (x) {
|
|
442
|
-
|
|
443
|
-
|
|
652
|
+
const pick = (x.options || [])[x.recommended];
|
|
653
|
+
if (keep(x) || !pick) return true;
|
|
654
|
+
auto(x, pick.label); return false;
|
|
444
655
|
});
|
|
445
656
|
state.assumptions = state.assumptions.filter(function (x) { if (keep(x)) return true; auto(x, "Confirmed"); return false; });
|
|
446
657
|
state.gaps = state.gaps.filter(function (x) {
|
|
447
|
-
|
|
448
|
-
|
|
658
|
+
const pick = (x.solutions || [])[x.recommended];
|
|
659
|
+
if (keep(x) || !pick) return true;
|
|
660
|
+
auto(x, pick.option); return false;
|
|
449
661
|
});
|
|
450
662
|
}
|
|
451
663
|
|
|
@@ -532,6 +744,43 @@ function waves(items, order) {
|
|
|
532
744
|
// its start until its closedBy tasks are done (decision 50).
|
|
533
745
|
function markSeen(item) { if (item && item.id && state.seen.indexOf(item.id) < 0) state.seen.push(item.id); }
|
|
534
746
|
function markDone(item) { if (item && item.id && state.done.indexOf(item.id) < 0) state.done.push(item.id); }
|
|
747
|
+
|
|
748
|
+
// Resume (decision 63): a resumed run replays from the cache only up to its first changed call, so
|
|
749
|
+
// an answered blocker before the task loop re-ran every finished task. A downstream result reports
|
|
750
|
+
// doneTasks (each task that went green, with its step, summary and files, those of earlier resumes
|
|
751
|
+
// included); the driver passes them back as args.doneTasks, and the task is not built again. An
|
|
752
|
+
// answer that amends what a done task relies on (the task, a criterion it covers, a decision for
|
|
753
|
+
// its codebase or for no place) re-runs it and the tasks that depend on it.
|
|
754
|
+
const DONE_BEFORE = {};
|
|
755
|
+
(Array.isArray(A.doneTasks) ? A.doneTasks : []).forEach(function (d) { if (d && d.id) DONE_BEFORE[d.id] = d; });
|
|
756
|
+
const AMENDED = (function () {
|
|
757
|
+
const ids = [].concat.apply([], AMENDMENTS.map(function (a) { return a.amends || []; }));
|
|
758
|
+
if (!ids.length || !HANDOFF) return [];
|
|
759
|
+
const hit = (HANDOFF.tasks || []).filter(function (t) {
|
|
760
|
+
if (ids.indexOf(t.id) >= 0) return true;
|
|
761
|
+
if ((t.covers || []).some(function (c) { return ids.some(function (x) { return coversCriterion(x, c) || coversCriterion(c, x); }); })) return true;
|
|
762
|
+
return (HANDOFF.decisions || []).some(function (d) {
|
|
763
|
+
return ids.indexOf(d.id) >= 0 && (!d.where || String(d.where).indexOf(t.codebase) >= 0 || String(t.codebase).indexOf(d.where) >= 0);
|
|
764
|
+
});
|
|
765
|
+
}).map(function (t) { return t.id; });
|
|
766
|
+
return withDependents(hit);
|
|
767
|
+
})();
|
|
768
|
+
function doneBefore(item) {
|
|
769
|
+
const d = item && item.id && DONE_BEFORE[item.id];
|
|
770
|
+
return d && AMENDED.indexOf(item.id) < 0 ? d : null;
|
|
771
|
+
}
|
|
772
|
+
function doneTasksOut() {
|
|
773
|
+
const out = {};
|
|
774
|
+
Object.keys(DONE_BEFORE).forEach(function (id) { if (AMENDED.indexOf(id) < 0) out[id] = DONE_BEFORE[id]; });
|
|
775
|
+
Object.keys(state.outputs).forEach(function (k) {
|
|
776
|
+
const i = k.indexOf(":");
|
|
777
|
+
const v = state.outputs[k];
|
|
778
|
+
if (i < 0 || !v || v.green !== true || state.done.indexOf(k.slice(i + 1)) < 0) return;
|
|
779
|
+
const red = state.outputs[k.slice(0, i) + ".test:" + k.slice(i + 1)] || {};
|
|
780
|
+
out[k.slice(i + 1)] = { id: k.slice(i + 1), step: k.slice(0, i), summary: v.summary || "", files: v.files || [], testFiles: red.testFiles || v.testFiles || [] };
|
|
781
|
+
});
|
|
782
|
+
return Object.keys(out).map(function (id) { return out[id]; });
|
|
783
|
+
}
|
|
535
784
|
function openBreaks() {
|
|
536
785
|
return ((HANDOFF && HANDOFF.tasks) || []).filter(function (t) {
|
|
537
786
|
return (t.breaks || []).length && state.seen.indexOf(t.id) >= 0;
|