@digital-agora/friday 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +8 -4
  2. package/bundles/friday-claude-0.1.0.zip +0 -0
  3. package/bundles/friday-opencode-0.1.0.zip +0 -0
  4. package/dist/adapters/claude/index.js +2 -1
  5. package/dist/adapters/claude/runtime.js +331 -51
  6. package/dist/adapters/claude/workflows.js +95 -35
  7. package/dist/adapters/drivers.js +49 -14
  8. package/dist/adapters/opencode/index.js +2 -1
  9. package/dist/adapters/skill.js +16 -5
  10. package/dist/cli.js +42 -7
  11. package/dist/contracts.js +200 -0
  12. package/dist/flow.js +227 -0
  13. package/dist/graph.js +18 -7
  14. package/dist/handoff.js +76 -3
  15. package/dist/ir.js +1 -0
  16. package/dist/load.js +3 -0
  17. package/dist/prompts.js +81 -5
  18. package/dist/reads.js +75 -0
  19. package/dist/slice.js +90 -0
  20. package/dist/specialize.js +10 -0
  21. package/dist/step-schemas.js +28 -3
  22. package/dist/validate.js +38 -3
  23. package/pack/model-policy.yaml +5 -0
  24. package/pack/orchestrations/architecture-decision.yaml +5 -0
  25. package/pack/orchestrations/bugfix-tdd.yaml +1 -1
  26. package/pack/orchestrations/discovery.yaml +16 -3
  27. package/pack/orchestrations/feature-delivery.yaml +21 -3
  28. package/pack/orchestrations/prompt-delivery.yaml +25 -5
  29. package/pack/orchestrations/prompt-discovery.yaml +3 -0
  30. package/pack/pack.yaml +12 -2
  31. package/pack/personas/backend-engineer.yaml +1 -1
  32. package/pack/personas/devops-engineer.yaml +1 -1
  33. package/pack/personas/frontend-engineer.yaml +1 -1
  34. package/package.json +1 -1
  35. package/schemas/decisions.schema.yaml +28 -0
  36. package/schemas/handoff.schema.yaml +66 -4
  37. package/schemas/orchestration.schema.yaml +20 -4
  38. package/schemas/pack.schema.yaml +25 -0
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]... 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 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
  ```
@@ -294,4 +297,5 @@ model policy and test pyramid, all generic), `specializations/` (platform and pr
294
297
  such as Google Cloud's and Hybrid-Day's, each its own package), `src/` (loader, validator, IR,
295
298
  `src/adapters/<target>/`, bundle, install, CLI), `test/` (vitest, including a harness that runs
296
299
  the generated workflow scripts with mocked agents). See `CLAUDE.md` for the rules and
297
- `docs/decisions.md` for why things are the way they are.
300
+ `docs/decisions.md` for why things are the way they are, and
301
+ `docs/how-friday-fits-together.md` for how the parts fit together as a pattern for other tools.
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" ? 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,35 @@ 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
+ // 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
- 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());
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
- parts.push(roundText());
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 && A.sliceScoped && item && item.codebase) {
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,15 +180,52 @@ 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
  }
157
- const earlier = Object.keys(state.outputs);
158
- if (earlier.length) parts.push("Results of earlier steps:\n" + JSON.stringify(state.outputs));
187
+ const earlier = visibleOutputs(stepId, item);
188
+ if (Object.keys(earlier).length) parts.push("Results of earlier steps:\n" + JSON.stringify(earlier));
159
189
  if (item) parts.push("Current item:\n" + JSON.stringify(item));
160
190
  return parts.join("\n\n");
161
191
  }
162
192
 
193
+ // The results of earlier steps one agent call sees (decision 55; the rules are in src/reads.ts).
194
+ // A result key is <stepId>[.<part>][:<itemId>]. A step's own results are always visible; with
195
+ // reads, only the steps it names besides its own loop. A result of the step's own loop is given
196
+ // for the current item whole, for the items it depends on summarized, and not for other items; any
197
+ // other per-item result is summarized (SUMMARY_DROPS left out).
198
+ function keyStep(k) { return k.split(/[.:]/)[0]; }
199
+ function keyItem(k) { const i = k.indexOf(":"); return i < 0 ? null : k.slice(i + 1); }
200
+ function summarized(v) {
201
+ if (Array.isArray(v)) return v.map(summarized);
202
+ if (!v || typeof v !== "object") return v;
203
+ const o = {};
204
+ Object.keys(v).forEach(function (k) { if (SUMMARY_DROPS.indexOf(k) < 0) o[k] = summarized(v[k]); });
205
+ return o;
206
+ }
207
+ function visibleOutputs(stepId, item) {
208
+ const base = keyStep(stepId);
209
+ const reads = READS[base] || null;
210
+ const loop = LOOPS[base] || null;
211
+ const deps = (item && item.dependsOn) || [];
212
+ const out = {};
213
+ Object.keys(state.outputs).forEach(function (k) {
214
+ const s = keyStep(k);
215
+ const it = keyItem(k);
216
+ const own = !!loop && LOOPS[s] === loop;
217
+ if (!own && s !== base && reads && reads.indexOf(s) < 0) return;
218
+ if (it === null) { out[k] = state.outputs[k]; return; }
219
+ if (own && item && item.id) {
220
+ if (it === item.id) out[k] = state.outputs[k];
221
+ else if (deps.indexOf(it) >= 0) out[k] = summarized(state.outputs[k]);
222
+ return;
223
+ }
224
+ out[k] = summarized(state.outputs[k]);
225
+ });
226
+ return out;
227
+ }
228
+
163
229
  // Per-repo command map: level id -> commands, from args.commands or the handoff's commands.
164
230
  // The pack's commands are only the default; an npm repo with test:architecture maps its own.
165
231
  const COMMANDS = Object.assign({}, (HANDOFF && HANDOFF.commands) || {}, A.commands || {});
@@ -189,10 +255,45 @@ function midRunAnswersText(stepId, item) {
189
255
  });
190
256
  if (!own.length) return "";
191
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" +
192
- own.map(function (a) { return "- Q: " + a.question + "\n A: " + a.answer + (a.interpretation ? "\n Interpretation: " + a.interpretation : ""); }).join("\n");
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);
193
294
  }
194
295
 
195
- async function call(stepId, ref, task, schema, item, phase) {
296
+ async function call(stepId, ref, task, schema, item, phase, noPark) {
196
297
  if (halted()) return null;
197
298
  task = withCommands(task);
198
299
  const r = resolveRef(ref, item);
@@ -200,22 +301,34 @@ async function call(stepId, ref, task, schema, item, phase) {
200
301
  const opts = { label: stepId + (item && item.id ? ":" + item.id : "") + " " + r.agentType, phase: phase, agentType: r.agentType, model: r.model, schema: schema };
201
302
  if (r.effort) opts.effort = r.effort;
202
303
  task = task + guideFor(schema) + midRunAnswersText(stepId, item);
203
- let out = await agent(context(stepId, item) + "\n\n## Your task\n\n" + task, opts);
304
+ let out = await metered(stepId, item, context(stepId, item) + "\n\n## Your task\n\n" + task, opts);
204
305
  if (out === null || out === undefined) { stop({ status: "failed", step: stepId, reason: r.agentType + " returned no result" }); return null; }
205
306
  if (out.status === "blocked" && HANDOFF) {
206
307
  // Decider in delivery: the lead developer settles what the standing policy allows; the step
207
308
  // runs once more with the decision. Product, copy and security-widening still stop the run.
208
309
  const d = await decide(stepId, item, out, phase);
209
310
  if (d && d.settled) {
210
- 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);
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);
211
312
  if (again && again.status !== "blocked") return again;
212
313
  if (again) out = again;
213
314
  }
214
315
  }
215
316
  if (out.status === "blocked") {
216
- // With a handoff, a blocker goes back upstream; without one (release) it is reported as is.
217
- if (HANDOFF) needsUpstream(stepId, item, (out.blocked && out.blocked.reason) || out.summary, (out.blocked && out.blocked.questions) || []);
218
- else stop({ status: "blocked", step: stepId, item: item && item.id, reason: (out.blocked && out.blocked.reason) || out.summary, questions: (out.blocked && out.blocked.questions) || [] });
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) || [] });
219
332
  }
220
333
  return out;
221
334
  }
@@ -223,7 +336,63 @@ async function call(stepId, ref, task, schema, item, phase) {
223
336
  // A downstream stop the people upstream answer: the same run resumes with the answers.
224
337
  function needsUpstream(stepId, item, reason, questions, extra) {
225
338
  stop(Object.assign({ status: "needs-upstream", step: stepId, item: item && item.id, reason: reason, questions: questions || [],
226
- 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);
227
396
  }
228
397
 
229
398
  // Test file -> the task whose red step wrote it. Verify reads it to tell its own failures from
@@ -235,22 +404,34 @@ function ownersText(item) {
235
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");
236
405
  }
237
406
  // A foreign failure counts only when its owner is another known task; anything else is this task's.
238
- function foreignOk(v, item) {
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) {
239
409
  const ids = Object.keys(state.testOwners).map(function (f) { return state.testOwners[f]; });
240
- return (v.foreignFailures || []).every(function (x) { return x.owner && x.owner !== (item && item.id) && ids.indexOf(x.owner) >= 0; });
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);
241
417
  }
418
+ function foreignOk(v, item) { return !foreignProblems(v, item).length; }
242
419
 
243
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.
244
423
  async function decide(stepId, item, out, phase) {
245
424
  if (!DECIDER || !(HANDOFF.deliveryPolicy || A.decider)) return null;
246
425
  const r = resolveRef(DECIDER, null);
247
426
  if (r.error) return null;
248
427
  const q = ((out.blocked && out.blocked.reason) || out.summary) + "\n" + JSON.stringify((out.blocked && out.blocked.questions) || []);
249
- 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,
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,
250
429
  { label: "decide:" + stepId + (item && item.id ? ":" + item.id : "") + " " + r.agentType, phase: phase, agentType: r.agentType, model: r.model, schema: SCHEMAS.DECISION });
251
- 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 });
252
430
  const never = ["product", "copy", "security-widening"];
253
- return d && never.indexOf(d.kind) < 0 ? d : null;
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;
254
435
  }
255
436
 
256
437
  function key(stepId, item) { return item && item.id ? stepId + ":" + item.id : stepId; }
@@ -282,6 +463,45 @@ function guardGaps(stepId, out) {
282
463
  });
283
464
  }
284
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
+
285
505
  // Git step options: handoff.git, then args.git. Defaults keep the pack's behaviour (open a
286
506
  // ready PR that links the handoff); an uncommitted handoff is never linked.
287
507
  function gitText() {
@@ -298,7 +518,8 @@ function gitText() {
298
518
  function retroFacts() {
299
519
  return "\n\nRun facts:\n" + JSON.stringify({
300
520
  halt: state.halt, round: ROUND, scopeFrozen: FROZEN,
301
- 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,
302
523
  autoAnswers: state.autoAnswers || [], dropped: state.dropped, deferred: state.deferred,
303
524
  redRounds: state.red || [], pyramidViolations: state.violations, foreignFailures: state.foreign,
304
525
  trace: state.trace, testChanges: state.testChanges,
@@ -310,7 +531,11 @@ async function retro(ref, task) {
310
531
  if (r.error) return null;
311
532
  const opts = { label: "retro " + r.agentType, phase: "retro", agentType: r.agentType, model: r.model, schema: SCHEMAS.RETRO };
312
533
  if (r.effort) opts.effort = r.effort;
313
- const out = await agent(context("retro", null) + "\n\n## Your task\n\n" + task + guideFor(SCHEMAS.RETRO) + retroFacts(), opts);
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);
314
539
  return out ? { path: out.retroPath, improvements: out.improvements || [] } : null;
315
540
  }
316
541
 
@@ -365,8 +590,12 @@ function consolidate(stepId, out) {
365
590
  raw[k].forEach(function (x) { if (!seen.has(x.id)) next[k].push(x); });
366
591
  });
367
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.
368
595
  (out.contradictions || []).forEach(function (c) {
369
- if (!ANSWERED.has(c.id)) state.contradictions.push(Object.assign({}, c, { step: stepId }));
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 }));
370
599
  });
371
600
  }
372
601
 
@@ -375,6 +604,10 @@ function consolidate(stepId, out) {
375
604
  // reason, unless it says it contradicts that answer.
376
605
  const ANSWERED_TOPICS = {};
377
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; }); });
378
611
  function dedupe() {
379
612
  const byTopic = {};
380
613
  function pass(list) {
@@ -382,6 +615,11 @@ function dedupe() {
382
615
  list.forEach(function (x) {
383
616
  if (!x.topic) { out.push(x); return; }
384
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
+ }
385
623
  if (ANSWERED_TOPICS[t] && !(x.contradicts || []).length) {
386
624
  state.dropped.push({ id: x.id, reason: "topic " + t + " is settled by answer " + ANSWERED_TOPICS[t], step: x.step });
387
625
  return;
@@ -394,22 +632,27 @@ function dedupe() {
394
632
  state.questions = pass(state.questions); state.assumptions = pass(state.assumptions); state.gaps = pass(state.gaps);
395
633
  }
396
634
 
397
- // Close-out (args.closeOut, the user's choice): only blockers or contradictions go to the user;
398
- // the rest take the recommended option, recorded as answers marked by close-out.
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.
399
640
  const CLOSE_OUT = A.closeOut === true;
400
641
  state.autoAnswers = [];
401
642
  function closeOut() {
402
643
  if (!CLOSE_OUT) return;
403
- function keep(x) { return x.blocking !== false || (x.contradicts || []).length > 0; }
644
+ function keep(x) { return x.changesBehaviour !== false || (x.contradicts || []).length > 0; }
404
645
  function auto(x, answer) { state.autoAnswers.push({ id: x.id, question: x.question || x.assumption || x.gap, answer: answer, by: "close-out" }); }
405
646
  state.questions = state.questions.filter(function (x) {
406
- if (keep(x)) return true;
407
- auto(x, ((x.options || [])[x.recommended] || {}).label || "recommended option"); return false;
647
+ const pick = (x.options || [])[x.recommended];
648
+ if (keep(x) || !pick) return true;
649
+ auto(x, pick.label); return false;
408
650
  });
409
651
  state.assumptions = state.assumptions.filter(function (x) { if (keep(x)) return true; auto(x, "Confirmed"); return false; });
410
652
  state.gaps = state.gaps.filter(function (x) {
411
- if (keep(x)) return true;
412
- auto(x, ((x.solutions || [])[x.recommended] || {}).option || "recommended solution"); return false;
653
+ const pick = (x.solutions || [])[x.recommended];
654
+ if (keep(x) || !pick) return true;
655
+ auto(x, pick.option); return false;
413
656
  });
414
657
  }
415
658
 
@@ -496,6 +739,43 @@ function waves(items, order) {
496
739
  // its start until its closedBy tasks are done (decision 50).
497
740
  function markSeen(item) { if (item && item.id && state.seen.indexOf(item.id) < 0) state.seen.push(item.id); }
498
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
+ }
499
779
  function openBreaks() {
500
780
  return ((HANDOFF && HANDOFF.tasks) || []).filter(function (t) {
501
781
  return (t.breaks || []).length && state.seen.indexOf(t.id) >= 0;