@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
package/README.md
CHANGED
|
@@ -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,35 @@ 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
|
+
// handoffSlice is src/slice.ts, embedded in the script by the compiler: the estimate in
|
|
135
|
+
// friday handoff check counts the same slice (decision 61).
|
|
136
|
+
function sliceOf(item) { return handoffSlice(HANDOFF, item, COMMANDS); }
|
|
113
137
|
|
|
114
138
|
function context(stepId, item) {
|
|
115
139
|
const parts = ["Workflow " + WORKFLOW.id + " (" + WORKFLOW.stream + "), step " + stepId + "."].concat(factsText());
|
|
116
140
|
if (WORKFLOW.stream === "upstream") {
|
|
117
141
|
parts.push("Work id: " + (A.workId || "(missing)"));
|
|
118
142
|
parts.push("Request:\n" + (A.request || "(missing)"));
|
|
143
|
+
if (DECISIONS_TEXT) parts.push(DECISIONS_TEXT);
|
|
119
144
|
if (A.answersFile) {
|
|
120
|
-
|
|
121
|
-
|
|
145
|
+
// The ids this step may read change its prompt exactly when its answers do (decision 59).
|
|
146
|
+
const ids = answersFor(stepId).map(function (x) { return x.id; }).concat(gapsFor(stepId).map(function (x) { return x.id; }));
|
|
147
|
+
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.");
|
|
148
|
+
const auto = (state.autoAnswers || []).filter(seenBy(stepId));
|
|
149
|
+
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
150
|
} 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());
|
|
151
|
+
parts.push("Questions already answered by the user (do not ask them again; build on the answers):\n" + answersText(stepId));
|
|
152
|
+
parts.push("Gaps already resolved by the user (do not report them again):\n" + gapsText(stepId));
|
|
125
153
|
}
|
|
126
|
-
|
|
154
|
+
const rt = roundText(stepId);
|
|
155
|
+
if (rt) parts.push(rt);
|
|
127
156
|
if (state.deferred.length) {
|
|
128
157
|
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
158
|
}
|
|
@@ -132,7 +161,7 @@ function context(stepId, item) {
|
|
|
132
161
|
// handoff; it comes first, and the handoff or its slice still follows as the source of truth.
|
|
133
162
|
const tb = HANDOFF && item && item.id && (HANDOFF.briefs || []).find(function (b) { return b.task === item.id; });
|
|
134
163
|
if (tb) parts.push("Task brief (approved with the handoff; the handoff below stays the source of truth):\n" + tb.text);
|
|
135
|
-
if (HANDOFF &&
|
|
164
|
+
if (HANDOFF && SLICED && item && item.codebase) {
|
|
136
165
|
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)));
|
|
137
166
|
} else if (HANDOFF) {
|
|
138
167
|
parts.push("Approved handoff (the only source of truth; anything it does not settle is a blocker, not a guess):\n" + JSON.stringify(HANDOFF));
|
|
@@ -151,6 +180,7 @@ function context(stepId, item) {
|
|
|
151
180
|
}).join("\n"));
|
|
152
181
|
}
|
|
153
182
|
}
|
|
183
|
+
if (HANDOFF && WORKFLOW.stream === "downstream") parts.push(PRECEDENCE);
|
|
154
184
|
if (HANDOFF && HANDOFF.deliveryPolicy) {
|
|
155
185
|
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
186
|
}
|
|
@@ -225,10 +255,45 @@ function midRunAnswersText(stepId, item) {
|
|
|
225
255
|
});
|
|
226
256
|
if (!own.length) return "";
|
|
227
257
|
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) {
|
|
258
|
+
own.map(function (a) {
|
|
259
|
+
const am = (a.amends || []).length ? "\n Amends (approved in the handoff; this answer wins over them): " + a.amends.join(", ") : "";
|
|
260
|
+
return "- Q: " + a.question + "\n A: " + a.answer + (a.interpretation ? "\n Interpretation: " + a.interpretation : "") + am;
|
|
261
|
+
}).join("\n");
|
|
262
|
+
}
|
|
263
|
+
// A mid-run answer that changes an approved decision, criterion or answer names them in amends
|
|
264
|
+
// (decision 57): it is a reversed answer, listed in the result and the retro, not only in a summary.
|
|
265
|
+
const AMENDMENTS = (Array.isArray(A.midRunAnswers) ? A.midRunAnswers : []).filter(function (a) { return a && (a.amends || []).length; });
|
|
266
|
+
// In the retro's reversed answers, an amendment has the shape of a recorded answer that supersedes
|
|
267
|
+
// others (id, question, answer, supersedes), so both are counted the same way.
|
|
268
|
+
function amendmentsAsAnswers() {
|
|
269
|
+
return AMENDMENTS.map(function (a) {
|
|
270
|
+
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 };
|
|
271
|
+
});
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
// Usage and caps (decision 61): every agent call counts, with its prompt's tokens estimated at 4
|
|
275
|
+
// characters a token (estimateTokens in src/slice.ts). args.maxAgentCalls and args.maxPromptTokens
|
|
276
|
+
// stop the run before the call that would pass them; a resumed run counts its replayed calls too.
|
|
277
|
+
state.usage = { calls: 0, promptTokens: 0 };
|
|
278
|
+
// Whole tokens, rounded up, without Math (the host and its test harness keep the script to plain arithmetic).
|
|
279
|
+
function tokensOf(text) { const n = String(text).length + 3; return (n - (n % 4)) / 4; }
|
|
280
|
+
const MAX_CALLS = count(A.maxAgentCalls, 0);
|
|
281
|
+
const MAX_PROMPT_TOKENS = count(A.maxPromptTokens, 0);
|
|
282
|
+
async function metered(stepId, item, prompt, opts) {
|
|
283
|
+
if (halted()) return null;
|
|
284
|
+
const t = tokensOf(prompt);
|
|
285
|
+
const over = MAX_CALLS && state.usage.calls + 1 > MAX_CALLS ? "args.maxAgentCalls (" + MAX_CALLS + ")"
|
|
286
|
+
: MAX_PROMPT_TOKENS && state.usage.promptTokens + t > MAX_PROMPT_TOKENS ? "args.maxPromptTokens (" + MAX_PROMPT_TOKENS + ")" : null;
|
|
287
|
+
if (over) {
|
|
288
|
+
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 });
|
|
289
|
+
return null;
|
|
290
|
+
}
|
|
291
|
+
state.usage.calls++;
|
|
292
|
+
state.usage.promptTokens += t;
|
|
293
|
+
return agent(prompt, opts);
|
|
229
294
|
}
|
|
230
295
|
|
|
231
|
-
async function call(stepId, ref, task, schema, item, phase) {
|
|
296
|
+
async function call(stepId, ref, task, schema, item, phase, noPark) {
|
|
232
297
|
if (halted()) return null;
|
|
233
298
|
task = withCommands(task);
|
|
234
299
|
const r = resolveRef(ref, item);
|
|
@@ -236,22 +301,34 @@ async function call(stepId, ref, task, schema, item, phase) {
|
|
|
236
301
|
const opts = { label: stepId + (item && item.id ? ":" + item.id : "") + " " + r.agentType, phase: phase, agentType: r.agentType, model: r.model, schema: schema };
|
|
237
302
|
if (r.effort) opts.effort = r.effort;
|
|
238
303
|
task = task + guideFor(schema) + midRunAnswersText(stepId, item);
|
|
239
|
-
let out = await
|
|
304
|
+
let out = await metered(stepId, item, context(stepId, item) + "\n\n## Your task\n\n" + task, opts);
|
|
240
305
|
if (out === null || out === undefined) { stop({ status: "failed", step: stepId, reason: r.agentType + " returned no result" }); return null; }
|
|
241
306
|
if (out.status === "blocked" && HANDOFF) {
|
|
242
307
|
// Decider in delivery: the lead developer settles what the standing policy allows; the step
|
|
243
308
|
// runs once more with the decision. Product, copy and security-widening still stop the run.
|
|
244
309
|
const d = await decide(stepId, item, out, phase);
|
|
245
310
|
if (d && d.settled) {
|
|
246
|
-
const again = await
|
|
311
|
+
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
312
|
if (again && again.status !== "blocked") return again;
|
|
248
313
|
if (again) out = again;
|
|
249
314
|
}
|
|
250
315
|
}
|
|
251
316
|
if (out.status === "blocked") {
|
|
252
|
-
// With a handoff, a blocker goes back upstream; without one (release) it is reported as is.
|
|
253
|
-
|
|
254
|
-
|
|
317
|
+
// With a handoff, a blocker goes back upstream; without one (release) it is reported as is. A
|
|
318
|
+
// blocker that names the tasks it affects parks only them (decision 56): an item's agents stop
|
|
319
|
+
// here, a step before the task loop keeps its result for the tasks that go on.
|
|
320
|
+
const why = (out.blocked && out.blocked.reason) || out.summary;
|
|
321
|
+
const qs = (out.blocked && out.blocked.questions) || [];
|
|
322
|
+
if (HANDOFF) {
|
|
323
|
+
// The preflight never parks: a workspace it could not prepare is not ready for any task.
|
|
324
|
+
const held = noPark ? null : park(stepId, item, why, qs, (out.blocked && out.blocked.tasks) || []);
|
|
325
|
+
if (held) {
|
|
326
|
+
if (item) return null;
|
|
327
|
+
// The partial result says which tasks it does not settle, so the steps that read it know.
|
|
328
|
+
return Object.assign({}, out, { parked: { tasks: held, note: "Not settled for these tasks: they wait for the answers to this step's blocker." } });
|
|
329
|
+
}
|
|
330
|
+
needsUpstream(stepId, item, why, qs);
|
|
331
|
+
} 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
332
|
}
|
|
256
333
|
return out;
|
|
257
334
|
}
|
|
@@ -259,7 +336,63 @@ async function call(stepId, ref, task, schema, item, phase) {
|
|
|
259
336
|
// A downstream stop the people upstream answer: the same run resumes with the answers.
|
|
260
337
|
function needsUpstream(stepId, item, reason, questions, extra) {
|
|
261
338
|
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 || {}));
|
|
339
|
+
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 || {}));
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
// Parking (decision 56): until the task loop over handoff.tasks has run, a blocker that affects
|
|
343
|
+
// only some tasks parks them and the tasks that depend on them; the others go on. When the loop is
|
|
344
|
+
// over (or every task is parked) the run stops once, needs-upstream, with every parked blocker.
|
|
345
|
+
// args.parkBlocked: false stops at the first blocker instead. A workflow without that loop never
|
|
346
|
+
// parks: nothing would release the parked blockers.
|
|
347
|
+
state.parked = [];
|
|
348
|
+
state.parkedTasks = [];
|
|
349
|
+
state.parkOpen = !!HANDOFF && WORKFLOW.stream === "downstream" && WORKFLOW.taskLoop === true && A.parkBlocked !== false;
|
|
350
|
+
function taskIds() { return ((HANDOFF && HANDOFF.tasks) || []).map(function (t) { return t.id; }); }
|
|
351
|
+
function withDependents(ids) {
|
|
352
|
+
const out = ids.slice();
|
|
353
|
+
let grew = true;
|
|
354
|
+
while (grew) {
|
|
355
|
+
grew = false;
|
|
356
|
+
((HANDOFF && HANDOFF.tasks) || []).forEach(function (t) {
|
|
357
|
+
if (out.indexOf(t.id) < 0 && (t.dependsOn || []).some(function (d) { return out.indexOf(d) >= 0; })) { out.push(t.id); grew = true; }
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
return out;
|
|
361
|
+
}
|
|
362
|
+
function isParked(item) { return !!(item && item.id && state.parkedTasks.indexOf(item.id) >= 0); }
|
|
363
|
+
// Returns the ids of the tasks that now wait, or null when the blocker is not parked. A task whose
|
|
364
|
+
// own step blocked always waits, whatever else the blocker names; a task already done does not.
|
|
365
|
+
function park(stepId, item, reason, questions, tasks) {
|
|
366
|
+
if (!state.parkOpen) return null;
|
|
367
|
+
const all = taskIds();
|
|
368
|
+
let ids = (tasks || []).filter(function (t) { return all.indexOf(t) >= 0; });
|
|
369
|
+
if (item && item.id && all.indexOf(item.id) >= 0 && ids.indexOf(item.id) < 0) ids.push(item.id);
|
|
370
|
+
ids = ids.filter(function (t) { return state.done.indexOf(t) < 0; });
|
|
371
|
+
if (!ids.length) return null;
|
|
372
|
+
const waiting = withDependents(ids).filter(function (t) { return state.done.indexOf(t) < 0; });
|
|
373
|
+
const union = state.parkedTasks.concat(waiting.filter(function (t) { return state.parkedTasks.indexOf(t) < 0; }));
|
|
374
|
+
// Nothing would go on: stop now, as without parking.
|
|
375
|
+
if (!state.parked.length && union.length >= all.length) return null;
|
|
376
|
+
state.parked.push({ step: stepId, item: (item && item.id) || null, tasks: ids, waiting: waiting, reason: reason, questions: questions || [] });
|
|
377
|
+
state.parkedTasks = union;
|
|
378
|
+
trace(stepId, item, null, "parked", waiting.join(", ") + ": " + reason);
|
|
379
|
+
if (union.length >= all.length) releaseParked();
|
|
380
|
+
return waiting;
|
|
381
|
+
}
|
|
382
|
+
function releaseParked() {
|
|
383
|
+
state.parkOpen = false;
|
|
384
|
+
if (!state.parked.length || halted()) return;
|
|
385
|
+
const p = state.parked;
|
|
386
|
+
const first = p[0];
|
|
387
|
+
const qs = [].concat.apply([], p.map(function (x) { return x.questions; }));
|
|
388
|
+
const reason = p.length === 1 ? first.reason : p.length + " blockers parked tasks " + state.parkedTasks.join(", ") + ": " + p.map(function (x) { return x.reason; }).join(" | ");
|
|
389
|
+
const extra = { parked: p, parkedTasks: state.parkedTasks };
|
|
390
|
+
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.";
|
|
391
|
+
needsUpstream(first.step, first.item ? { id: first.item } : null, reason, qs, extra);
|
|
392
|
+
}
|
|
393
|
+
// A blocker found by the runtime itself (e.g. test design's questions) parks the same way.
|
|
394
|
+
function upstreamOrPark(stepId, item, reason, questions) {
|
|
395
|
+
if (!park(stepId, item, reason, questions, [])) needsUpstream(stepId, item, reason, questions);
|
|
263
396
|
}
|
|
264
397
|
|
|
265
398
|
// Test file -> the task whose red step wrote it. Verify reads it to tell its own failures from
|
|
@@ -271,22 +404,34 @@ function ownersText(item) {
|
|
|
271
404
|
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
405
|
}
|
|
273
406
|
// A foreign failure counts only when its owner is another known task; anything else is this task's.
|
|
274
|
-
|
|
407
|
+
// Each one that does not count says why, so a round it makes red never comes back with no failure.
|
|
408
|
+
function foreignProblems(v, item) {
|
|
275
409
|
const ids = Object.keys(state.testOwners).map(function (f) { return state.testOwners[f]; });
|
|
276
|
-
return (v.foreignFailures || []).
|
|
410
|
+
return (v.foreignFailures || []).map(function (x) {
|
|
411
|
+
const t = (x && x.test) || "a test";
|
|
412
|
+
if (!x || !x.owner) return t + " fails and verify named no owner for it, so it counts as this task's";
|
|
413
|
+
if (x.owner === (item && item.id)) return t + " fails and is this task's own test";
|
|
414
|
+
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";
|
|
415
|
+
return null;
|
|
416
|
+
}).filter(Boolean);
|
|
277
417
|
}
|
|
418
|
+
function foreignOk(v, item) { return !foreignProblems(v, item).length; }
|
|
278
419
|
|
|
279
420
|
state.decisions = [];
|
|
421
|
+
// The decider's answer applies only when its kind is on deliveryPolicy.maySettle (decision 56); with
|
|
422
|
+
// args.decider and no policy, any kind but the three that are never delivery's.
|
|
280
423
|
async function decide(stepId, item, out, phase) {
|
|
281
424
|
if (!DECIDER || !(HANDOFF.deliveryPolicy || A.decider)) return null;
|
|
282
425
|
const r = resolveRef(DECIDER, null);
|
|
283
426
|
if (r.error) return null;
|
|
284
427
|
const q = ((out.blocked && out.blocked.reason) || out.summary) + "\n" + JSON.stringify((out.blocked && out.blocked.questions) || []);
|
|
285
|
-
const d = await
|
|
428
|
+
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
429
|
{ 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
430
|
const never = ["product", "copy", "security-widening"];
|
|
289
|
-
|
|
431
|
+
const allowed = HANDOFF.deliveryPolicy ? (HANDOFF.deliveryPolicy.maySettle || []) : null;
|
|
432
|
+
const applied = !!(d && d.settled && never.indexOf(d.kind) < 0 && (!allowed || allowed.indexOf(d.kind) >= 0));
|
|
433
|
+
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 });
|
|
434
|
+
return applied ? d : null;
|
|
290
435
|
}
|
|
291
436
|
|
|
292
437
|
function key(stepId, item) { return item && item.id ? stepId + ":" + item.id : stepId; }
|
|
@@ -318,6 +463,45 @@ function guardGaps(stepId, out) {
|
|
|
318
463
|
});
|
|
319
464
|
}
|
|
320
465
|
|
|
466
|
+
// Working trees (decision 56): args.worktrees [{ path, branch }] or args.branch name the branch each
|
|
467
|
+
// working tree must be on; the preflight reports every tree's branch and uncommitted changes.
|
|
468
|
+
function expectedBranches() {
|
|
469
|
+
return (Array.isArray(A.worktrees) ? A.worktrees : A.branch ? [{ path: ".", branch: A.branch }] : []).filter(function (x) { return x && x.branch; });
|
|
470
|
+
}
|
|
471
|
+
function worktreesText() {
|
|
472
|
+
const w = expectedBranches();
|
|
473
|
+
if (!w.length) return "";
|
|
474
|
+
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");
|
|
475
|
+
}
|
|
476
|
+
// "./apps/web/", "apps\\web" and "apps/web" name the same tree; "", "./" and "." the root.
|
|
477
|
+
function normPath(p) {
|
|
478
|
+
const s = String(p === undefined || p === null ? "." : p).trim().replace(/\\/g, "/").replace(/^(\.\/)+/, "").replace(/\/+$/, "");
|
|
479
|
+
return s === "" || s === "." ? "." : s;
|
|
480
|
+
}
|
|
481
|
+
// A reported tree is the expected one when the paths match, or when the reported path is absolute
|
|
482
|
+
// and ends in the expected one ("/home/u/repo/apps/web" for "apps/web").
|
|
483
|
+
function samePath(reported, expected) {
|
|
484
|
+
const r = normPath(reported);
|
|
485
|
+
return r === expected || (expected !== "." && ("/" + r).slice(-(expected.length + 1)) === "/" + expected);
|
|
486
|
+
}
|
|
487
|
+
// A named working tree that is on another branch, or that the preflight did not report, stops the run.
|
|
488
|
+
function wrongBranches(out) {
|
|
489
|
+
const exp = expectedBranches();
|
|
490
|
+
const seen = ((out && out.worktrees) || []).filter(Boolean);
|
|
491
|
+
const paths = exp.map(function (e) { return normPath(e.path); });
|
|
492
|
+
return exp.map(function (e, i) {
|
|
493
|
+
const path = paths[i];
|
|
494
|
+
let r = seen.find(function (x) { return samePath(x.path, path); });
|
|
495
|
+
// The root reported under its absolute path: the one report no other expected tree claims.
|
|
496
|
+
if (!r && path === ".") {
|
|
497
|
+
const free = seen.filter(function (x) { return !paths.some(function (q) { return q !== "." && samePath(x.path, q); }); });
|
|
498
|
+
if (free.length === 1) r = free[0];
|
|
499
|
+
}
|
|
500
|
+
if (!r) return path + ": not reported (expected " + e.branch + ")";
|
|
501
|
+
return r.branch === e.branch ? null : path + ": on " + r.branch + ", expected " + e.branch;
|
|
502
|
+
}).filter(Boolean);
|
|
503
|
+
}
|
|
504
|
+
|
|
321
505
|
// Git step options: handoff.git, then args.git. Defaults keep the pack's behaviour (open a
|
|
322
506
|
// ready PR that links the handoff); an uncommitted handoff is never linked.
|
|
323
507
|
function gitText() {
|
|
@@ -334,7 +518,8 @@ function gitText() {
|
|
|
334
518
|
function retroFacts() {
|
|
335
519
|
return "\n\nRun facts:\n" + JSON.stringify({
|
|
336
520
|
halt: state.halt, round: ROUND, scopeFrozen: FROZEN,
|
|
337
|
-
reversedAnswers: (A.answers || []).filter(function (a) { return (a.supersedes || []).length; }),
|
|
521
|
+
reversedAnswers: (A.answers || []).filter(function (a) { return (a.supersedes || []).length; }).concat(amendmentsAsAnswers()),
|
|
522
|
+
parked: state.parked, usage: state.usage,
|
|
338
523
|
autoAnswers: state.autoAnswers || [], dropped: state.dropped, deferred: state.deferred,
|
|
339
524
|
redRounds: state.red || [], pyramidViolations: state.violations, foreignFailures: state.foreign,
|
|
340
525
|
trace: state.trace, testChanges: state.testChanges,
|
|
@@ -346,7 +531,11 @@ async function retro(ref, task) {
|
|
|
346
531
|
if (r.error) return null;
|
|
347
532
|
const opts = { label: "retro " + r.agentType, phase: "retro", agentType: r.agentType, model: r.model, schema: SCHEMAS.RETRO };
|
|
348
533
|
if (r.effort) opts.effort = r.effort;
|
|
349
|
-
|
|
534
|
+
// The retro is counted but never capped: it records why the run stopped, a cap included.
|
|
535
|
+
const prompt = context("retro", null) + "\n\n## Your task\n\n" + task + guideFor(SCHEMAS.RETRO) + retroFacts();
|
|
536
|
+
state.usage.calls++;
|
|
537
|
+
state.usage.promptTokens += tokensOf(prompt);
|
|
538
|
+
const out = await agent(prompt, opts);
|
|
350
539
|
return out ? { path: out.retroPath, improvements: out.improvements || [] } : null;
|
|
351
540
|
}
|
|
352
541
|
|
|
@@ -401,8 +590,12 @@ function consolidate(stepId, out) {
|
|
|
401
590
|
raw[k].forEach(function (x) { if (!seen.has(x.id)) next[k].push(x); });
|
|
402
591
|
});
|
|
403
592
|
state.questions = next.questions; state.assumptions = next.assumptions; state.gaps = next.gaps;
|
|
593
|
+
// Ids are "<step>.<id>" like every other item, so its answer belongs to this step (decision 59).
|
|
594
|
+
// A later consolidating step that reports the same contradiction again finds it settled.
|
|
404
595
|
(out.contradictions || []).forEach(function (c) {
|
|
405
|
-
|
|
596
|
+
const bare = String(c.id).indexOf(stepId + ".") === 0 ? String(c.id).slice(stepId.length + 1) : String(c.id);
|
|
597
|
+
const id = stepId + "." + bare;
|
|
598
|
+
if (!ANSWERED.has(id) && !ANSWERED.has(bare) && !ANSWERED_CONTRADICTIONS.has(bare)) state.contradictions.push(Object.assign({}, c, { id: id, step: stepId }));
|
|
406
599
|
});
|
|
407
600
|
}
|
|
408
601
|
|
|
@@ -411,6 +604,10 @@ function consolidate(stepId, out) {
|
|
|
411
604
|
// reason, unless it says it contradicts that answer.
|
|
412
605
|
const ANSWERED_TOPICS = {};
|
|
413
606
|
(A.answers || []).forEach(function (a) { if (a.topic) ANSWERED_TOPICS[a.topic] = a.id; });
|
|
607
|
+
// The join on documented decisions (decision 64): an item whose topic a decision lists is settled
|
|
608
|
+
// by it, unless it names that decision in contradicts; then it stays for the user to settle.
|
|
609
|
+
const DECISION_TOPICS = {};
|
|
610
|
+
DECISIONS.forEach(function (d) { d.topics.forEach(function (t) { DECISION_TOPICS[t] = d; }); });
|
|
414
611
|
function dedupe() {
|
|
415
612
|
const byTopic = {};
|
|
416
613
|
function pass(list) {
|
|
@@ -418,6 +615,11 @@ function dedupe() {
|
|
|
418
615
|
list.forEach(function (x) {
|
|
419
616
|
if (!x.topic) { out.push(x); return; }
|
|
420
617
|
const t = x.topic;
|
|
618
|
+
const dd = DECISION_TOPICS[t];
|
|
619
|
+
if (dd && (x.contradicts || []).indexOf(dd.id) < 0) {
|
|
620
|
+
state.dropped.push({ id: x.id, reason: "topic " + t + " is settled by documented decision " + dd.id + " (" + dd.source + ")", step: x.step, decision: dd.id });
|
|
621
|
+
return;
|
|
622
|
+
}
|
|
421
623
|
if (ANSWERED_TOPICS[t] && !(x.contradicts || []).length) {
|
|
422
624
|
state.dropped.push({ id: x.id, reason: "topic " + t + " is settled by answer " + ANSWERED_TOPICS[t], step: x.step });
|
|
423
625
|
return;
|
|
@@ -430,22 +632,27 @@ function dedupe() {
|
|
|
430
632
|
state.questions = pass(state.questions); state.assumptions = pass(state.assumptions); state.gaps = pass(state.gaps);
|
|
431
633
|
}
|
|
432
634
|
|
|
433
|
-
// Close-out (args.closeOut, the user's choice):
|
|
434
|
-
//
|
|
635
|
+
// Close-out (args.closeOut, the user's choice; decision 59): an item that changes what is built or
|
|
636
|
+
// how it behaves, a contradiction, and an item without a recommended option still go to the user;
|
|
637
|
+
// an item marked changesBehaviour: false takes its recommended option, recorded as an answer marked
|
|
638
|
+
// by close-out. Blocking does not keep an item: a technical detail can block planning and still
|
|
639
|
+
// have one safe answer.
|
|
435
640
|
const CLOSE_OUT = A.closeOut === true;
|
|
436
641
|
state.autoAnswers = [];
|
|
437
642
|
function closeOut() {
|
|
438
643
|
if (!CLOSE_OUT) return;
|
|
439
|
-
function keep(x) { return x.
|
|
644
|
+
function keep(x) { return x.changesBehaviour !== false || (x.contradicts || []).length > 0; }
|
|
440
645
|
function auto(x, answer) { state.autoAnswers.push({ id: x.id, question: x.question || x.assumption || x.gap, answer: answer, by: "close-out" }); }
|
|
441
646
|
state.questions = state.questions.filter(function (x) {
|
|
442
|
-
|
|
443
|
-
|
|
647
|
+
const pick = (x.options || [])[x.recommended];
|
|
648
|
+
if (keep(x) || !pick) return true;
|
|
649
|
+
auto(x, pick.label); return false;
|
|
444
650
|
});
|
|
445
651
|
state.assumptions = state.assumptions.filter(function (x) { if (keep(x)) return true; auto(x, "Confirmed"); return false; });
|
|
446
652
|
state.gaps = state.gaps.filter(function (x) {
|
|
447
|
-
|
|
448
|
-
|
|
653
|
+
const pick = (x.solutions || [])[x.recommended];
|
|
654
|
+
if (keep(x) || !pick) return true;
|
|
655
|
+
auto(x, pick.option); return false;
|
|
449
656
|
});
|
|
450
657
|
}
|
|
451
658
|
|
|
@@ -532,6 +739,43 @@ function waves(items, order) {
|
|
|
532
739
|
// its start until its closedBy tasks are done (decision 50).
|
|
533
740
|
function markSeen(item) { if (item && item.id && state.seen.indexOf(item.id) < 0) state.seen.push(item.id); }
|
|
534
741
|
function markDone(item) { if (item && item.id && state.done.indexOf(item.id) < 0) state.done.push(item.id); }
|
|
742
|
+
|
|
743
|
+
// Resume (decision 63): a resumed run replays from the cache only up to its first changed call, so
|
|
744
|
+
// an answered blocker before the task loop re-ran every finished task. A downstream result reports
|
|
745
|
+
// doneTasks (each task that went green, with its step, summary and files, those of earlier resumes
|
|
746
|
+
// included); the driver passes them back as args.doneTasks, and the task is not built again. An
|
|
747
|
+
// answer that amends what a done task relies on (the task, a criterion it covers, a decision for
|
|
748
|
+
// its codebase or for no place) re-runs it and the tasks that depend on it.
|
|
749
|
+
const DONE_BEFORE = {};
|
|
750
|
+
(Array.isArray(A.doneTasks) ? A.doneTasks : []).forEach(function (d) { if (d && d.id) DONE_BEFORE[d.id] = d; });
|
|
751
|
+
const AMENDED = (function () {
|
|
752
|
+
const ids = [].concat.apply([], AMENDMENTS.map(function (a) { return a.amends || []; }));
|
|
753
|
+
if (!ids.length || !HANDOFF) return [];
|
|
754
|
+
const hit = (HANDOFF.tasks || []).filter(function (t) {
|
|
755
|
+
if (ids.indexOf(t.id) >= 0) return true;
|
|
756
|
+
if ((t.covers || []).some(function (c) { return ids.some(function (x) { return coversCriterion(x, c) || coversCriterion(c, x); }); })) return true;
|
|
757
|
+
return (HANDOFF.decisions || []).some(function (d) {
|
|
758
|
+
return ids.indexOf(d.id) >= 0 && (!d.where || String(d.where).indexOf(t.codebase) >= 0 || String(t.codebase).indexOf(d.where) >= 0);
|
|
759
|
+
});
|
|
760
|
+
}).map(function (t) { return t.id; });
|
|
761
|
+
return withDependents(hit);
|
|
762
|
+
})();
|
|
763
|
+
function doneBefore(item) {
|
|
764
|
+
const d = item && item.id && DONE_BEFORE[item.id];
|
|
765
|
+
return d && AMENDED.indexOf(item.id) < 0 ? d : null;
|
|
766
|
+
}
|
|
767
|
+
function doneTasksOut() {
|
|
768
|
+
const out = {};
|
|
769
|
+
Object.keys(DONE_BEFORE).forEach(function (id) { if (AMENDED.indexOf(id) < 0) out[id] = DONE_BEFORE[id]; });
|
|
770
|
+
Object.keys(state.outputs).forEach(function (k) {
|
|
771
|
+
const i = k.indexOf(":");
|
|
772
|
+
const v = state.outputs[k];
|
|
773
|
+
if (i < 0 || !v || v.green !== true || state.done.indexOf(k.slice(i + 1)) < 0) return;
|
|
774
|
+
const red = state.outputs[k.slice(0, i) + ".test:" + k.slice(i + 1)] || {};
|
|
775
|
+
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 || [] };
|
|
776
|
+
});
|
|
777
|
+
return Object.keys(out).map(function (id) { return out[id]; });
|
|
778
|
+
}
|
|
535
779
|
function openBreaks() {
|
|
536
780
|
return ((HANDOFF && HANDOFF.tasks) || []).filter(function (t) {
|
|
537
781
|
return (t.breaks || []).length && state.seen.indexOf(t.id) >= 0;
|