@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
@@ -22,6 +22,7 @@ steps:
22
22
  # contracts instead of inventing their own, and every red test has a known owner.
23
23
  - id: contracts
24
24
  type: agent
25
+ reads: []
25
26
  persona: architect
26
27
  taskKind: decide
27
28
  prompt: >-
@@ -35,15 +36,24 @@ steps:
35
36
  interface already exists, name it and keep its shape. Put them in result.contracts (one
36
37
  entry per interface, with the task ids that use it) and result.standards (the cross-cutting
37
38
  rules: naming, error, audit, logging and versioning). Write no code. Anything the handoff does
38
- not settle is a blocker: return blocked with the question.
39
+ not settle is a blocker, but one blocker does not end the step: go through every task first,
40
+ then return blocked once, with every question in blocked.questions and the ids of the tasks
41
+ they affect in blocked.tasks, so the other tasks go on (decision 56). Write each option as the
42
+ complete rule the code would follow (the exact formula, merge, default or threshold) and trace
43
+ it through every contract that touches it, so choosing it leaves no follow-up question.
39
44
  - id: interfaces
40
45
  type: agent
46
+ reads: [contracts]
41
47
  persona: lead-developer
42
48
  taskKind: integrate
43
49
  prompt: >-
44
50
  Code the interfaces the contracts step defined, and only those: contracts, schemas, event
45
51
  types, port interfaces and shared types, in the repository's contract and core packages, with
46
- no behaviour. They must compile, and every contract gets a contract or schema test. Run the
52
+ no behaviour. DSL first, code after (decision 65): code every new or changed interface
53
+ contract from the approved DSL (the handoff's interfaceContracts and shapes, or the OpenAPI or
54
+ AsyncAPI document its spec names) exactly, in the codebase's own language: as types where it
55
+ has them, as the validators it uses where it has none. Add no field, operation or error the
56
+ DSL does not have; a contract it cannot express is a blocker. They must compile, and every contract gets a contract or schema test, against the JSON Schema `friday contracts schema` writes from the shapes. Run the
47
57
  static checks and the unit tests of the packages you touched. They must be green: an
48
58
  interface that would make another test red is a blocker. Commit them as one commit. From now
49
59
  on they are frozen. List every file and exported name in result.interfaces, with the task ids
@@ -51,6 +61,7 @@ steps:
51
61
  change it.
52
62
  - id: orchestration
53
63
  type: agent
64
+ reads: [contracts, interfaces]
54
65
  persona: backend-engineer
55
66
  taskKind: integrate
56
67
  prompt: >-
@@ -71,8 +82,9 @@ steps:
71
82
  # task's own paths, code only in the task's files, against the frozen interfaces.
72
83
  - id: tdd
73
84
  type: tdd-pair
85
+ reads: [contracts, interfaces, orchestration]
74
86
  test: { persona: qa-engineer, taskKind: test-design }
75
- impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
87
+ impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter, document] }
76
88
  verify: { persona: qa-engineer, taskKind: verify }
77
89
  # The task loop stays at the bottom of the pyramid; integration runs the rest.
78
90
  testScope: [static, unit]
@@ -81,12 +93,14 @@ steps:
81
93
  # that goes back through the bottom-of-pyramid loop. Repeats until green or maxRounds.
82
94
  - id: integrate
83
95
  type: integration-loop
96
+ reads: [contracts, interfaces, orchestration, build]
84
97
  integrate: { persona: "{{stack}}", taskKind: integrate }
85
98
  testScope: [static, unit, integration, e2e]
86
99
  maxRounds: 3
87
100
  followup:
88
101
  - id: followup-tdd
89
102
  type: tdd-pair
103
+ reads: [contracts, interfaces, orchestration]
90
104
  test: { persona: qa-engineer, taskKind: test-design }
91
105
  impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
92
106
  verify: { persona: qa-engineer, taskKind: verify }
@@ -97,6 +111,7 @@ steps:
97
111
  # steward checks the controls. Only when the handoff holds pii.
98
112
  - id: privacy-review
99
113
  type: gate
114
+ reads: [contracts, orchestration]
100
115
  when: pii
101
116
  persona: data-analyst-pii
102
117
  taskKind: analysis
@@ -105,6 +120,7 @@ steps:
105
120
  onFail: { persona: backend-engineer, taskKind: integrate }
106
121
  - id: security-review
107
122
  type: gate
123
+ reads: [contracts, orchestration]
108
124
  persona: security-steward
109
125
  taskKind: review
110
126
  prompt: Review the full diff against the security, data-classification, rules and config conventions and the handoff's decisions.
@@ -112,6 +128,7 @@ steps:
112
128
  onFail: { persona: backend-engineer, taskKind: integrate }
113
129
  - id: acceptance
114
130
  type: gate
131
+ reads: [orchestration, build, integrate]
115
132
  persona: lead-developer
116
133
  taskKind: integrate
117
134
  prompt: >-
@@ -123,6 +140,7 @@ steps:
123
140
  onFail: { persona: backend-engineer, taskKind: integrate }
124
141
  - id: pr
125
142
  type: agent
143
+ reads: [orchestration, build, integrate]
126
144
  persona: git-steward
127
145
  taskKind: git
128
146
  output: git
@@ -20,6 +20,7 @@ steps:
20
20
  taskKind: verify
21
21
  - id: contracts
22
22
  type: agent
23
+ reads: []
23
24
  persona: architect
24
25
  taskKind: decide
25
26
  prompt: >-
@@ -30,20 +31,30 @@ steps:
30
31
  its owner context and consumers, and the trade-offs it accepts. The approved prompt pyramid
31
32
  levels (handoff promptPyramid.levels and their files) are fixed: the prompt, examples and
32
33
  eval cases are used exactly as approved. Put them in result.contracts and result.standards.
33
- Write no code. Anything the handoff does not settle is a blocker: return blocked with the
34
- question.
34
+ Write no code. Anything the handoff does not settle is a blocker, but one blocker does not end
35
+ the step: go through every task first, then return blocked once, with every question in
36
+ blocked.questions and the ids of the tasks they affect in blocked.tasks, so the other tasks go
37
+ on (decision 56). Write each option as the complete rule the code would follow (the exact
38
+ formula, merge, default or threshold) and trace it through every contract that touches it, so
39
+ choosing it leaves no follow-up question.
35
40
  - id: interfaces
36
41
  type: agent
42
+ reads: [contracts]
37
43
  persona: lead-developer
38
44
  taskKind: integrate
39
45
  prompt: >-
40
- Code the interfaces the contracts step defined, and only those, with no behaviour. They must
41
- compile, and every contract gets a contract or schema test. Run the static checks and the unit
46
+ Code the interfaces the contracts step defined, and only those, with no behaviour. DSL
47
+ first, code after (decision 65): code every new or changed interface contract from the
48
+ approved DSL (the handoff's interfaceContracts and shapes, or the OpenAPI or AsyncAPI document
49
+ its spec names) exactly, in the codebase's own language: as types where it has them, as the
50
+ validators it uses where it has none. Add no field, operation or error the DSL does not have;
51
+ a contract it cannot express is a blocker. They must compile, and every contract gets a contract or schema test, against the JSON Schema `friday contracts schema` writes from the shapes. Run the static checks and the unit
42
52
  tests of the packages you touched; they must be green. Commit them as one commit; from now on
43
53
  they are frozen. List every file and exported name in result.interfaces, with the task ids
44
54
  that consume each.
45
55
  - id: orchestration
46
56
  type: agent
57
+ reads: [contracts, interfaces]
47
58
  persona: backend-engineer
48
59
  taskKind: integrate
49
60
  prompt: >-
@@ -62,19 +73,22 @@ steps:
62
73
  steps:
63
74
  - id: tdd
64
75
  type: tdd-pair
76
+ reads: [contracts, interfaces, orchestration]
65
77
  test: { persona: qa-engineer, taskKind: test-design }
66
- impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
78
+ impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter, document] }
67
79
  verify: { persona: qa-engineer, taskKind: verify }
68
80
  testScope: [static, unit]
69
81
  maxRounds: 3
70
82
  - id: integrate
71
83
  type: integration-loop
84
+ reads: [contracts, interfaces, orchestration, build]
72
85
  integrate: { persona: "{{stack}}", taskKind: integrate }
73
86
  testScope: [static, unit, integration, e2e]
74
87
  maxRounds: 3
75
88
  followup:
76
89
  - id: followup-tdd
77
90
  type: tdd-pair
91
+ reads: [contracts, interfaces, orchestration]
78
92
  test: { persona: qa-engineer, taskKind: test-design }
79
93
  impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
80
94
  verify: { persona: qa-engineer, taskKind: verify }
@@ -83,6 +97,7 @@ steps:
83
97
  # The top of the prompt pyramid. Neither agent wrote the prompt (decision 25).
84
98
  - id: eval-run
85
99
  type: agent
100
+ reads: [contracts, interfaces]
86
101
  level: eval-run
87
102
  persona: qa-engineer
88
103
  taskKind: verify
@@ -101,6 +116,7 @@ steps:
101
116
  changing one reopens its level in prompt-discovery.
102
117
  - id: eval-review
103
118
  type: agent
119
+ reads: [contracts, eval-run]
104
120
  level: eval-run
105
121
  persona: security-steward
106
122
  taskKind: review
@@ -115,6 +131,7 @@ steps:
115
131
  blocked.reason starting "Level <id>:". Never fix anything yourself.
116
132
  - id: privacy-review
117
133
  type: gate
134
+ reads: [contracts, orchestration]
118
135
  when: pii
119
136
  persona: data-analyst-pii
120
137
  taskKind: analysis
@@ -123,6 +140,7 @@ steps:
123
140
  onFail: { persona: backend-engineer, taskKind: integrate }
124
141
  - id: security-review
125
142
  type: gate
143
+ reads: [contracts, orchestration]
126
144
  persona: security-steward
127
145
  taskKind: review
128
146
  prompt: Review the full diff against the security, data-classification, rules and config conventions and the handoff's decisions. The approved prompt, examples and eval cases are not findings to fix here; a problem in one is a high finding naming its level.
@@ -130,6 +148,7 @@ steps:
130
148
  onFail: { persona: backend-engineer, taskKind: integrate }
131
149
  - id: acceptance
132
150
  type: gate
151
+ reads: [orchestration, build, integrate, eval-run]
133
152
  persona: lead-developer
134
153
  taskKind: integrate
135
154
  prompt: >-
@@ -143,6 +162,7 @@ steps:
143
162
  onFail: { persona: backend-engineer, taskKind: integrate }
144
163
  - id: pr
145
164
  type: agent
165
+ reads: [orchestration, build, integrate]
146
166
  persona: git-steward
147
167
  taskKind: git
148
168
  output: git
@@ -20,6 +20,9 @@ sizing:
20
20
  large: 10
21
21
  maxAgentsPerWorkflow: 6
22
22
  maxRounds: 5
23
+ # From round 3 the driver offers the close-out rule once: only items that change behaviour or
24
+ # contradict an answer still go to the user, the rest take the recommended option (decision 59).
25
+ closeOutFromRound: 3
23
26
  deferNonBlocking: true
24
27
  maxItemsPerRound: 15
25
28
  inputs:
package/pack/pack.yaml CHANGED
@@ -102,16 +102,26 @@ checkpoints:
102
102
  description: The request brief, the structured prompt discovery starts from (goal, who, today, wanted, constraints, acceptance, out of scope, facts checked, unknowns)
103
103
  approver: requester
104
104
  source: decision 39 (friday docs/decisions.md)
105
+ # The orchestration check (decision 58) computes every orchestration's worst-case agent calls from
106
+ # its loop limits and warns above warnAbove for a handoff of this size. Today's largest delivery
107
+ # (prompt-delivery) is 472 at this size.
108
+ agentCallBudget:
109
+ warnAbove: 500
110
+ # friday handoff check estimates the run's prompt tokens spent on the handoff from the real
111
+ # handoff and warns above this (decision 61). A 22-task handoff of about 120,000 tokens comes to
112
+ # about 13 million in the worst case even with task slices; at 5 million it warns.
113
+ warnPromptTokensAbove: 5000000
114
+ assume: { task: 10, stack: 3, followup: 3, item: 10 }
105
115
  # Rules the agents cannot break: checked before each tool call, not only stated in the prompt.
106
116
  # Skills and prompts advise; these hooks enforce (The AI-native SDLC playbook, Build and Test).
107
117
  guardrails:
108
118
  # Every agent kind that runs inside a TDD pair. integrate is left out: it runs the integration
109
119
  # loop, the one place the whole pyramid runs.
110
120
  loopCommands:
111
- taskKinds: [test-design, implement, scaffold, adapter, verify]
121
+ taskKinds: [test-design, implement, scaffold, adapter, verify, document]
112
122
  # QA writes the failing test; the implementer makes it pass without touching it.
113
123
  protectedTests:
114
- taskKinds: [implement]
124
+ taskKinds: [implement, document]
115
125
  patterns:
116
126
  - '(^|/)(test|tests|__tests__|e2e)/'
117
127
  - '\.(test|spec)\.[cm]?[jt]sx?$'
@@ -2,7 +2,7 @@ id: backend-engineer
2
2
  name: Backend Engineer
3
3
  role: Implements the core, adapters, functions and services.
4
4
  description: Implements tasks in the core, its adapters, functions and services in TDD with the QA engineer.
5
- taskKinds: [implement, scaffold, adapter, integrate]
5
+ taskKinds: [implement, scaffold, adapter, integrate, document]
6
6
  tools: [Read, Edit, Write, Grep, Glob, Bash]
7
7
  conventions: [hexagonal, typescript-node, testing, security-code, config-secrets]
8
8
  pairsWith: qa-engineer
@@ -2,7 +2,7 @@ id: devops-engineer
2
2
  name: DevOps Engineer
3
3
  role: Owns CI/CD, infrastructure as code, GitHub workflows and releases.
4
4
  description: Implements pipeline, infrastructure-as-code, .github/workflows, config/ and release tasks in TDD with the QA engineer (pipeline checks are the tests).
5
- taskKinds: [implement, scaffold, integrate]
5
+ taskKinds: [implement, scaffold, integrate, document]
6
6
  tools: [Read, Edit, Write, Grep, Glob, Bash]
7
7
  conventions: [changesets, ci-workflows, config-secrets, security-code]
8
8
  pairsWith: qa-engineer
@@ -2,7 +2,7 @@ id: frontend-engineer
2
2
  name: Frontend Engineer
3
3
  role: Implements web apps under apps/.
4
4
  description: Implements web app tasks under apps/<app> in TDD with the QA engineer. Server actions and API routes call the core.
5
- taskKinds: [implement, scaffold, adapter, integrate]
5
+ taskKinds: [implement, scaffold, adapter, integrate, document]
6
6
  tools: [Read, Edit, Write, Grep, Glob, Bash]
7
7
  conventions: [hexagonal, typescript-node, testing, security-code]
8
8
  pairsWith: qa-engineer
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@digital-agora/friday",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "description": "Friday: the source of truth for AI-assisted SDLC. Compiles YAML personas, workflows and conventions into agent bundles (Claude Code, OpenCode).",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,28 @@
1
+ # A project's documented decisions, keyed by topic (decision 64): decisions.yaml at the root of a
2
+ # pack, a specialization or a project's .friday/. Upstream, an open item whose topic a decision
3
+ # names is settled by it instead of asked; one that contradicts it stays a contradiction.
4
+ $id: https://friday.digital-agora/schemas/decisions.schema.yaml
5
+ title: Documented decisions
6
+ type: object
7
+ additionalProperties: false
8
+ required: [decisions]
9
+ properties:
10
+ decisions:
11
+ type: array
12
+ items:
13
+ type: object
14
+ additionalProperties: false
15
+ required: [id, topics, decision, source]
16
+ properties:
17
+ id: { type: string, pattern: "^[A-Za-z][A-Za-z0-9._-]{0,60}$", description: "e.g. ADR-007; a specialization's entry with the same id replaces the pack's." }
18
+ topics:
19
+ description: The kebab-case subjects it settles; an open item with one of these topics is settled by it. One topic belongs to one decision.
20
+ type: array
21
+ minItems: 1
22
+ uniqueItems: true
23
+ items: { type: string, pattern: "^[a-z0-9][a-z0-9-]{0,60}$" }
24
+ decision: { type: string, minLength: 1, description: The rule, as complete as the code follows it. }
25
+ why: { type: string }
26
+ source:
27
+ type: string
28
+ description: Where it is documented, "document, don't invent" (decision 30) - <repo>/<path> of a repository in sources, an https:// page, or a Friday decision.
@@ -43,6 +43,7 @@ properties:
43
43
  decision: { type: string }
44
44
  why: { type: string }
45
45
  where: { type: string }
46
+ source: { type: string, description: "For a documented decision the work relies on (decision 64): where it is documented." }
46
47
  contracts:
47
48
  description: Architect's contract outcomes per interaction (type and why, errors, audit and logging, owner, consumers, accepted trade-offs).
48
49
  type: array
@@ -84,7 +85,11 @@ properties:
84
85
  test: { type: string }
85
86
  owner: { type: string }
86
87
  interfaceContracts:
87
- description: Technical-lead definitions of implementation-facing boundaries for developers.
88
+ description: >-
89
+ Technical-lead definitions of implementation-facing boundaries for developers. DSL first,
90
+ code after (decision 65): a contract the work adds (new) or changes (changed) is written in
91
+ the DSL below, with its data in shapes, or points at an OpenAPI or AsyncAPI document (spec);
92
+ an existing one is only referenced (owner). Delivery codes the interfaces from it.
88
93
  type: array
89
94
  items:
90
95
  type: object
@@ -92,9 +97,45 @@ properties:
92
97
  properties:
93
98
  id: { type: string }
94
99
  boundary: { type: string }
95
- contract: { type: string }
100
+ contract: { type: string, description: The contract in one or two sentences. }
96
101
  consumers: { type: array, items: { type: string } }
97
102
  rationale: { type: string }
103
+ change: { enum: [new, changed, existing], description: "new and changed need the DSL (kind and its body); existing is a reference: owner says where it lives." }
104
+ kind: { enum: [port, callable, event, type, http, async], description: "port and callable: operations; event: payload; type: shape; http and async: spec." }
105
+ owner: { type: string, description: "The codebase (path) that owns it." }
106
+ operations:
107
+ type: array
108
+ items:
109
+ type: object
110
+ additionalProperties: false
111
+ required: [name, errors]
112
+ properties:
113
+ name: { type: string }
114
+ input: { type: string, description: "A shape name or a primitive (string, integer, number, boolean, date, datetime)." }
115
+ output: { type: string, description: "A shape name or a primitive; leave out when it returns nothing." }
116
+ errors: { type: array, items: { type: string }, description: "Every error it can return, by name; [] when it returns none." }
117
+ realizes:
118
+ type: array
119
+ items: { type: string }
120
+ description: "The inner-layer contracts this one implements or exposes, by id (an adapter implements a port, a callable or http endpoint exposes a use-case port): each is another codebase's contract, with no cycle."
121
+ payload: { type: string, description: "kind event: the shape it carries." }
122
+ shape: { type: string, description: "kind type: the shape it is." }
123
+ spec:
124
+ type: object
125
+ additionalProperties: false
126
+ required: [file, format]
127
+ description: "kind http or async: the OpenAPI or AsyncAPI document that is the contract, by its path in the repository."
128
+ properties:
129
+ file: { type: string }
130
+ format: { enum: [openapi, asyncapi] }
131
+ ref: { type: string, description: "The part of it that is this contract, e.g. a path or a channel." }
132
+ shapes:
133
+ description: >-
134
+ The data shapes the interface contracts name (decision 65), language-neutral: a typed codebase
135
+ codes them as types, an untyped one as the validators it uses. friday contracts schema writes
136
+ them as JSON Schema.
137
+ type: object
138
+ additionalProperties: { $ref: "#/$defs/shape" }
98
139
  testPlan:
99
140
  description: QA-authored behavioral scenarios; delivery QA writes the executable tests.
100
141
  type: array
@@ -131,7 +172,9 @@ properties:
131
172
  stack: { type: string }
132
173
  codebase: { type: string, description: 'Path in the monorepo, e.g. packages/core or services/<name>-api.' }
133
174
  scope: { type: string, description: The id of the scope (scope.scopes) this task delivers. }
134
- taskKind: { enum: [implement, scaffold, adapter] }
175
+ taskKind:
176
+ description: "document: a task that only writes documents (an ADR, a guide); it skips test design and verify runs only the static level (decision 62)."
177
+ enum: [implement, scaffold, adapter, document]
135
178
  acceptance: { type: array, minItems: 1, items: { type: string } }
136
179
  dependsOn: { type: array, items: { type: string } }
137
180
  conventions: { type: array, items: { type: string } }
@@ -236,8 +279,13 @@ properties:
236
279
  additionalProperties: false
237
280
  properties:
238
281
  maySettle:
282
+ description: >-
283
+ The kinds the delivery decider may settle; a kind not listed is never applied. answer-detail
284
+ is the technical detail an answer already given implies (the exact formula, merge rule or
285
+ edge case of the chosen option) when the handoff and the repository support one reading.
286
+ other is any further kind the user allowed, limited by notes.
239
287
  type: array
240
- items: { enum: [test-fixture, lint-suppression, repo-fact-exception, command-mapping] }
288
+ items: { enum: [test-fixture, lint-suppression, repo-fact-exception, command-mapping, answer-detail, other] }
241
289
  notes: { type: string, description: "Limits, e.g. the named repo facts an exception may cover." }
242
290
  briefs:
243
291
  description: >-
@@ -301,3 +349,17 @@ properties:
301
349
  description: Must be empty for downstream to start.
302
350
  type: array
303
351
  maxItems: 0
352
+ $defs:
353
+ shape:
354
+ type: object
355
+ additionalProperties: false
356
+ required: [type]
357
+ properties:
358
+ type: { enum: [string, integer, number, boolean, date, datetime, object, array, enum, ref] }
359
+ description: { type: string }
360
+ fields: { type: object, additionalProperties: { $ref: "#/$defs/shape" }, description: "type object: its fields." }
361
+ required: { type: array, items: { type: string }, description: "type object: the fields that are always present." }
362
+ items: { $ref: "#/$defs/shape", description: "type array: its items." }
363
+ values: { type: array, items: { type: string }, minItems: 1, description: "type enum: its values." }
364
+ ref: { type: string, description: "type ref: the shape it is." }
365
+ nullable: { type: boolean }
@@ -63,8 +63,8 @@ properties:
63
63
  required: { type: boolean }
64
64
  maxRounds:
65
65
  description: >-
66
- Upstream only: how many question rounds the driver runs before it stops and asks the user
67
- to freeze the scope or explicitly allow more rounds. Without it the loop is unbounded.
66
+ Upstream only, and required there (decision 58): how many question rounds the driver runs
67
+ before it stops and asks the user to freeze the scope or explicitly allow more rounds.
68
68
  type: integer
69
69
  minimum: 1
70
70
  maximum: 10
@@ -96,6 +96,9 @@ properties:
96
96
  type: array
97
97
  minItems: 1
98
98
  items: { $ref: "#/$defs/step" }
99
+ # Every loop has a finite limit (decision 58): an upstream workflow's question rounds too.
100
+ if: { properties: { stream: { const: upstream } }, required: [stream] }
101
+ then: { required: [maxRounds] }
99
102
 
100
103
  $defs:
101
104
  common:
@@ -118,6 +121,16 @@ $defs:
118
121
  The checkpoint (pack.yaml checkpoints) this step builds, or an approval step approves
119
122
  (decision 39). A person approves it; a change to it reopens every approval after it.
120
123
  type: string
124
+ reads:
125
+ description: >-
126
+ The earlier steps whose results this step's agents are given (decision 55), by step id; a
127
+ step that holds others stands for all of them. Unset: every earlier step. Either way, a
128
+ result of the step's own loop is given only for the current item (whole) and the items it
129
+ depends on (summarized), and a per-item result of another loop is summarized. Not on
130
+ parallel, sequential or foreach: set it on the steps they hold.
131
+ type: array
132
+ uniqueItems: true
133
+ items: { type: string, pattern: "^[a-z][a-z0-9-]{1,40}$" }
121
134
  override:
122
135
  type: object
123
136
  additionalProperties: false
@@ -144,8 +157,11 @@ $defs:
144
157
  required: [persona, taskKind, prompt]
145
158
  properties:
146
159
  output:
147
- description: The shape the agent returns; briefs is one task brief per task (decision 40).
148
- enum: [result, tasks, briefs, review, git]
160
+ description: >-
161
+ The shape the agent returns; briefs is one task brief per task (decision 40);
162
+ interfaces is a result whose interfaceContracts and shapes are the DSL, checked
163
+ before the run goes on (decision 65).
164
+ enum: [result, tasks, briefs, review, git, interfaces]
149
165
  - if: { properties: { type: { const: clarify } } }
150
166
  then: { required: [persona, taskKind, topic] }
151
167
  - if: { properties: { type: { const: gap-analysis } } }
@@ -122,6 +122,31 @@ properties:
122
122
  type: string
123
123
  pattern: "^[a-z][a-z0-9-]*$"
124
124
  source: { type: string }
125
+ agentCallBudget:
126
+ description: >-
127
+ The orchestration check's budget (decision 58): every orchestration's worst-case agent calls
128
+ are computed from its nested loop limits; the validator warns, and never fails, when the
129
+ count for a handoff of the assumed size is above warnAbove.
130
+ type: object
131
+ additionalProperties: false
132
+ required: [warnAbove, assume]
133
+ properties:
134
+ warnAbove: { type: integer, minimum: 1, description: Worst-case agent calls above which validation warns. }
135
+ warnPromptTokensAbove:
136
+ type: integer
137
+ minimum: 1
138
+ description: >-
139
+ Worst-case prompt tokens of handoff above which friday handoff check warns (decision 61),
140
+ estimated from the real handoff before the run.
141
+ assume:
142
+ description: The size the worst case is evaluated at; a unit left out counts 1.
143
+ type: object
144
+ additionalProperties: false
145
+ properties:
146
+ task: { type: integer, minimum: 1, description: Tasks in the handoff. }
147
+ stack: { type: integer, minimum: 1, description: Stacks the tasks use (one integration run each per round). }
148
+ followup: { type: integer, minimum: 0, description: Follow-up tasks one integration round proposes. }
149
+ item: { type: integer, minimum: 1, description: Items of an earlier step's list (<stepId>.tasks). }
125
150
  guardrails:
126
151
  description: >-
127
152
  Pack rules the generated agents cannot break. A skill or a prompt makes a rule likely to be