@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.
Files changed (40) hide show
  1. package/README.md +7 -4
  2. package/bundles/friday-claude-0.13.0.zip +0 -0
  3. package/bundles/friday-opencode-0.13.0.zip +0 -0
  4. package/dist/adapters/claude/index.js +2 -1
  5. package/dist/adapters/claude/runtime.js +298 -49
  6. package/dist/adapters/claude/workflows.js +94 -36
  7. package/dist/adapters/drivers.js +44 -14
  8. package/dist/adapters/opencode/index.js +2 -1
  9. package/dist/adapters/skill.js +10 -2
  10. package/dist/cli.js +42 -7
  11. package/dist/contracts.js +200 -0
  12. package/dist/flow.js +230 -0
  13. package/dist/graph.js +11 -5
  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 +88 -5
  18. package/dist/reads.js +1 -1
  19. package/dist/slice.js +126 -0
  20. package/dist/specialize.js +10 -0
  21. package/dist/step-schemas.js +28 -3
  22. package/dist/validate.js +38 -20
  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 +11 -3
  28. package/pack/orchestrations/prompt-delivery.yaml +13 -5
  29. package/pack/orchestrations/prompt-discovery.yaml +3 -0
  30. package/pack/pack.yaml +14 -3
  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 +2 -2
  35. package/schemas/decisions.schema.yaml +28 -0
  36. package/schemas/handoff.schema.yaml +66 -4
  37. package/schemas/orchestration.schema.yaml +10 -4
  38. package/schemas/pack.schema.yaml +25 -0
  39. package/bundles/friday-claude-0.1.0.zip +0 -0
  40. 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-0.1.0.zip --dir .
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]... schemas + cross-references + sources + model policy + test pyramid
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
@@ -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" ? upstreamDriver(w, { run, ask }, ir.pack.id)
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
- // An answer that settles a contradiction lists the answers it replaces in supersedes.
59
- const SUPERSEDED = new Set([].concat.apply([], (A.answers || []).map(function (a) { return a.supersedes || []; })));
60
-
61
- function answersText() {
62
- const qa = (A.answers || []).concat(state.autoAnswers || []).filter(function (a) { return !SUPERSEDED.has(a.id); });
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 gapsText() {
73
- const g = A.gapResolutions || [];
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
- function roundText() {
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 "Round " + ROUND + ": 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.";
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
- const of = ROUND_LIMIT ? " of " + ROUND_LIMIT : "";
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 (args.sliceScoped): a task agent gets its task and the tasks it depends
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
- function sliceOf(item) {
109
- const tasks = (HANDOFF.tasks || []).filter(function (t) { return t.id === item.id || (item.dependsOn || []).indexOf(t.id) >= 0; });
110
- const decisions = (HANDOFF.decisions || []).filter(function (d) { return !d.where || String(d.where).indexOf(item.codebase) >= 0 || String(item.codebase).indexOf(d.where) >= 0; });
111
- return { workId: HANDOFF.workId, scope: { summary: (HANDOFF.scope || {}).summary }, tasks: tasks, decisions: decisions, dataClassification: HANDOFF.dataClassification || [], commands: COMMANDS, deliveryPolicy: HANDOFF.deliveryPolicy || null };
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
- parts.push("Questions already answered and gaps already resolved by the user are in " + A.answersFile + " (answers, gapResolutions). Read it before you start; do not ask or report them again; where an answer lists supersedes, only it counts.");
121
- if ((state.autoAnswers || []).length) parts.push("Answered in this run by the close-out rule:\n" + answersText());
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
- parts.push(roundText());
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 && A.sliceScoped && item && item.codebase) {
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) { return "- Q: " + a.question + "\n A: " + a.answer + (a.interpretation ? "\n Interpretation: " + a.interpretation : ""); }).join("\n");
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 agent(context(stepId, item) + "\n\n## Your task\n\n" + task, opts);
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 agent(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);
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
- if (HANDOFF) needsUpstream(stepId, item, (out.blocked && out.blocked.reason) || out.summary, (out.blocked && out.blocked.questions) || []);
254
- else stop({ status: "blocked", step: stepId, item: item && item.id, reason: (out.blocked && out.blocked.reason) || out.summary, questions: (out.blocked && out.blocked.questions) || [] });
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
- function foreignOk(v, item) {
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 || []).every(function (x) { return x.owner && x.owner !== (item && item.id) && ids.indexOf(x.owner) >= 0; });
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 agent(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,
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
- return d && never.indexOf(d.kind) < 0 ? d : null;
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
- const out = await agent(context("retro", null) + "\n\n## Your task\n\n" + task + guideFor(SCHEMAS.RETRO) + retroFacts(), opts);
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
- if (!ANSWERED.has(c.id)) state.contradictions.push(Object.assign({}, c, { step: stepId }));
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): only blockers or contradictions go to the user;
434
- // the rest take the recommended option, recorded as answers marked by close-out.
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.blocking !== false || (x.contradicts || []).length > 0; }
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
- if (keep(x)) return true;
443
- auto(x, ((x.options || [])[x.recommended] || {}).label || "recommended option"); return false;
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
- if (keep(x)) return true;
448
- auto(x, ((x.solutions || [])[x.recommended] || {}).option || "recommended solution"); return false;
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;