@digital-agora/friday 0.0.0-stage → 0.10.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 (67) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +296 -2
  3. package/bundles/friday-claude-0.1.0.zip +0 -0
  4. package/bundles/friday-opencode-0.1.0.zip +0 -0
  5. package/dist/adapters/adapter.js +6 -0
  6. package/dist/adapters/claude/guards.js +40 -0
  7. package/dist/adapters/claude/index.js +161 -0
  8. package/dist/adapters/claude/runtime.js +645 -0
  9. package/dist/adapters/claude/workflows.js +323 -0
  10. package/dist/adapters/drivers.js +300 -0
  11. package/dist/adapters/index.js +16 -0
  12. package/dist/adapters/opencode/index.js +232 -0
  13. package/dist/adapters/skill.js +327 -0
  14. package/dist/build.js +77 -0
  15. package/dist/cli.js +197 -0
  16. package/dist/frontmatter.js +16 -0
  17. package/dist/graph.js +218 -0
  18. package/dist/handoff.js +329 -0
  19. package/dist/install.js +137 -0
  20. package/dist/ir.js +177 -0
  21. package/dist/load.js +42 -0
  22. package/dist/paths.js +24 -0
  23. package/dist/prompts.js +230 -0
  24. package/dist/specialize.js +237 -0
  25. package/dist/step-schemas.js +444 -0
  26. package/dist/types.js +8 -0
  27. package/dist/validate.js +576 -0
  28. package/pack/conventions/changesets.yaml +20 -0
  29. package/pack/conventions/ci-workflows.yaml +16 -0
  30. package/pack/conventions/config-secrets.yaml +16 -0
  31. package/pack/conventions/data-classification.yaml +16 -0
  32. package/pack/conventions/decisions.yaml +13 -0
  33. package/pack/conventions/git.yaml +28 -0
  34. package/pack/conventions/hexagonal.yaml +31 -0
  35. package/pack/conventions/security-code.yaml +17 -0
  36. package/pack/conventions/testing.yaml +44 -0
  37. package/pack/conventions/typescript-node.yaml +16 -0
  38. package/pack/model-policy.yaml +80 -0
  39. package/pack/orchestrations/architecture-decision.yaml +52 -0
  40. package/pack/orchestrations/bugfix-tdd.yaml +67 -0
  41. package/pack/orchestrations/data-analysis.yaml +23 -0
  42. package/pack/orchestrations/discovery.yaml +214 -0
  43. package/pack/orchestrations/feature-delivery.yaml +129 -0
  44. package/pack/orchestrations/prompt-delivery.yaml +155 -0
  45. package/pack/orchestrations/prompt-discovery.yaml +201 -0
  46. package/pack/orchestrations/release.yaml +40 -0
  47. package/pack/pack.yaml +137 -0
  48. package/pack/personas/architect.yaml +18 -0
  49. package/pack/personas/backend-engineer.yaml +21 -0
  50. package/pack/personas/data-analyst-non-pii.yaml +14 -0
  51. package/pack/personas/data-analyst-pii.yaml +28 -0
  52. package/pack/personas/devops-engineer.yaml +19 -0
  53. package/pack/personas/frontend-engineer.yaml +18 -0
  54. package/pack/personas/git-steward.yaml +24 -0
  55. package/pack/personas/lead-developer.yaml +23 -0
  56. package/pack/personas/prompt-engineer.yaml +38 -0
  57. package/pack/personas/qa-engineer.yaml +24 -0
  58. package/pack/personas/security-steward.yaml +20 -0
  59. package/package.json +47 -4
  60. package/schemas/convention.schema.yaml +46 -0
  61. package/schemas/handoff.schema.yaml +303 -0
  62. package/schemas/model-policy.schema.yaml +33 -0
  63. package/schemas/orchestration.schema.yaml +224 -0
  64. package/schemas/pack.schema.yaml +168 -0
  65. package/schemas/persona.schema.yaml +41 -0
  66. package/schemas/specialization-patch.schema.yaml +39 -0
  67. package/schemas/specialization.schema.yaml +57 -0
@@ -0,0 +1,576 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { Ajv } from "ajv";
4
+ import { parse } from "yaml";
5
+ import { SCHEMAS_DIR } from "./paths.js";
6
+ import { loadRawPack } from "./load.js";
7
+ import { applySpecializations } from "./specialize.js";
8
+ import { SKILL_STEP_TYPES, emits } from "./types.js";
9
+ const SCHEMA_FILES = {
10
+ pack: "pack.schema.yaml",
11
+ "model-policy": "model-policy.schema.yaml",
12
+ persona: "persona.schema.yaml",
13
+ convention: "convention.schema.yaml",
14
+ orchestration: "orchestration.schema.yaml",
15
+ handoff: "handoff.schema.yaml",
16
+ };
17
+ let validators;
18
+ export function schemaValidator(kind) {
19
+ if (!validators) {
20
+ const ajv = new Ajv({ allErrors: true, strict: false });
21
+ validators = {};
22
+ for (const [k, file] of Object.entries(SCHEMA_FILES)) {
23
+ validators[k] = ajv.compile(parse(readFileSync(join(SCHEMAS_DIR, file), "utf8")));
24
+ }
25
+ }
26
+ return validators[kind];
27
+ }
28
+ function schemaIssues(doc) {
29
+ const v = schemaValidator(doc.kind);
30
+ if (v(doc.data))
31
+ return [];
32
+ return (v.errors ?? []).map((e) => ({
33
+ level: "error",
34
+ file: doc.file,
35
+ message: `${e.instancePath || "/"} ${e.message ?? "is invalid"}${e.params && "allowedValues" in e.params ? ` (${e.params.allowedValues.join(", ")})` : ""}`,
36
+ }));
37
+ }
38
+ /** Template values allowed in a step's persona / taskKind. */
39
+ const STACK_TEMPLATE = "{{stack}}";
40
+ const ANALYST_TEMPLATE = "{{analyst}}";
41
+ const TASKKIND_TEMPLATE = "{{task.taskKind}}";
42
+ /** Inputs the runtime reads itself (glossary and facts go into every step's context). */
43
+ const CONTEXT_INPUTS = ["glossary", "environmentFacts", "answersFile"];
44
+ const UPSTREAM_ONLY = new Set(["clarify", "gap-analysis", "handoff", "approval"]);
45
+ // integration-loop is downstream-only too; it is checked with its own message below.
46
+ /** Walk every step, depth first, with the chain of enclosing foreach steps. */
47
+ export function walkSteps(steps, visit, foreachOver = []) {
48
+ for (const step of steps) {
49
+ visit(step, foreachOver);
50
+ if (step.type === "parallel" || step.type === "sequential")
51
+ walkSteps(step.steps, visit, foreachOver);
52
+ if (step.type === "foreach")
53
+ walkSteps(step.steps, visit, [...foreachOver, step.over]);
54
+ // Follow-up tasks are tasks: the same templates apply inside `followup`.
55
+ if (step.type === "integration-loop")
56
+ walkSteps(step.followup, visit, [...foreachOver, `${step.id}.followups.tasks`]);
57
+ }
58
+ }
59
+ function crossRefIssues(lp, files) {
60
+ const issues = [];
61
+ const err = (file, message) => issues.push({ level: "error", file, message });
62
+ const warn = (file, message) => issues.push({ level: "warning", file, message });
63
+ const { pack, policy } = lp;
64
+ const personas = new Map(lp.personas.map((p) => [p.id, p]));
65
+ const conventions = new Map(lp.conventions.map((c) => [c.id, c]));
66
+ const kinds = new Set(Object.keys(policy.taskKinds));
67
+ const dup = (items, what) => {
68
+ const seen = new Set();
69
+ for (const i of items) {
70
+ if (seen.has(i.id))
71
+ err(files.get(i) ?? what, `duplicate ${what} id "${i.id}"`);
72
+ seen.add(i.id);
73
+ }
74
+ };
75
+ dup(lp.personas, "persona");
76
+ dup(lp.conventions, "convention");
77
+ dup(lp.orchestrations, "orchestration");
78
+ for (const t of pack.targets) {
79
+ if (!policy.targets[t])
80
+ err("model-policy.yaml", `targets.${t} is missing but pack.yaml lists target ${t}`);
81
+ }
82
+ for (const [stack, pid] of Object.entries(pack.stacks)) {
83
+ if (!personas.has(pid))
84
+ err("pack.yaml", `stacks.${stack} names unknown persona "${pid}"`);
85
+ }
86
+ if (pack.analysts) {
87
+ for (const [cls, pid] of Object.entries(pack.analysts)) {
88
+ const p = personas.get(pid);
89
+ if (!p)
90
+ err("pack.yaml", `analysts.${cls} names unknown persona "${pid}"`);
91
+ else if (p.dataAccess !== cls)
92
+ err("pack.yaml", `analysts.${cls} persona "${pid}" has dataAccess ${p.dataAccess}`);
93
+ }
94
+ }
95
+ if (pack.testPyramid) {
96
+ const ids = pack.testPyramid.levels.map((l) => l.id);
97
+ if (new Set(ids).size !== ids.length)
98
+ err("pack.yaml", "testPyramid.levels has duplicate ids");
99
+ const loop = pack.testPyramid.loopLevels;
100
+ if (loop.some((l, i) => ids[i] !== l)) {
101
+ err("pack.yaml", `testPyramid.loopLevels must be the bottom of the pyramid, in order (${ids.join(" < ")})`);
102
+ }
103
+ if (loop.length >= ids.length)
104
+ err("pack.yaml", "testPyramid.loopLevels must leave at least one level to integration");
105
+ }
106
+ // Prompt pyramid (decision 32): people approve every level; the prompt's author never judges it.
107
+ if (pack.promptPyramid) {
108
+ const levels = pack.promptPyramid.levels;
109
+ const ids = levels.map((l) => l.id);
110
+ if (new Set(ids).size !== ids.length)
111
+ err("pack.yaml", "promptPyramid.levels has duplicate ids");
112
+ for (const l of levels) {
113
+ for (const s of l.specialists) {
114
+ const p = personas.get(s.persona);
115
+ if (!p)
116
+ err("pack.yaml", `promptPyramid.${l.id}: unknown persona "${s.persona}"`);
117
+ else if (!p.taskKinds.includes(s.taskKind))
118
+ err("pack.yaml", `promptPyramid.${l.id}: persona "${s.persona}" has no taskKind "${s.taskKind}"`);
119
+ }
120
+ if (personas.has(l.approver))
121
+ err("pack.yaml", `promptPyramid.${l.id}: approver "${l.approver}" is an agent; name the role of the person who approves`);
122
+ }
123
+ const all = levels.flatMap((l) => l.specialists);
124
+ const authors = new Set(all.filter((s) => s.taskKind === "prompt-design").map((s) => s.persona));
125
+ for (const a of authors) {
126
+ if (all.some((s) => s.persona === a && (s.taskKind === "verify" || s.taskKind === "review"))) {
127
+ err("pack.yaml", `promptPyramid: "${a}" writes the prompt (prompt-design) and may not review or verify it (decision 25)`);
128
+ }
129
+ }
130
+ }
131
+ // Guardrails are enforced per task kind (decision 24).
132
+ const guards = pack.guardrails;
133
+ for (const [name, g] of Object.entries(guards ?? {})) {
134
+ for (const k of g.taskKinds)
135
+ if (!kinds.has(k))
136
+ err("pack.yaml", `guardrails.${name}.taskKinds: "${k}" is not in model-policy.yaml`);
137
+ }
138
+ if (guards?.loopCommands && !pack.testPyramid)
139
+ err("pack.yaml", "guardrails.loopCommands blocks testPyramid.forbiddenInLoop; testPyramid is missing");
140
+ for (const name of ["protectedTests", "approvedPrompts"]) {
141
+ for (const p of guards?.[name]?.patterns ?? []) {
142
+ try {
143
+ new RegExp(p);
144
+ }
145
+ catch {
146
+ err("pack.yaml", `guardrails.${name}.patterns: "${p}" is not a regular expression`);
147
+ }
148
+ }
149
+ }
150
+ for (const p of lp.personas) {
151
+ const f = files.get(p) ?? p.id;
152
+ for (const k of p.taskKinds)
153
+ if (!kinds.has(k))
154
+ err(f, `taskKind "${k}" is not in model-policy.yaml`);
155
+ for (const k of Object.keys(p.taskKindNotes ?? {})) {
156
+ if (!p.taskKinds.includes(k))
157
+ err(f, `taskKindNotes.${k} is not one of the persona's taskKinds`);
158
+ }
159
+ for (const c of p.conventions ?? [])
160
+ if (!conventions.has(c))
161
+ err(f, `unknown convention "${c}"`);
162
+ if (p.pairsWith && !personas.has(p.pairsWith))
163
+ err(f, `pairsWith names unknown persona "${p.pairsWith}"`);
164
+ }
165
+ // A concrete or templated agent reference must resolve to personas that have the task kind(s).
166
+ const checkRef = (f, where, ref, inForeach) => {
167
+ let candidates = [];
168
+ if (ref.persona === STACK_TEMPLATE) {
169
+ if (inForeach.length === 0)
170
+ err(f, `${where}: "{{stack}}" is only valid inside a foreach`);
171
+ candidates = Object.values(pack.stacks).map((id) => personas.get(id)).filter((p) => !!p);
172
+ }
173
+ else if (ref.persona === ANALYST_TEMPLATE) {
174
+ if (!pack.analysts)
175
+ err(f, `${where}: "{{analyst}}" needs analysts in pack.yaml`);
176
+ candidates = Object.values(pack.analysts ?? {}).map((id) => personas.get(id)).filter((p) => !!p);
177
+ }
178
+ else {
179
+ const p = personas.get(ref.persona);
180
+ if (!p) {
181
+ err(f, `${where}: unknown persona "${ref.persona}"`);
182
+ return;
183
+ }
184
+ candidates = [p];
185
+ }
186
+ let needed;
187
+ if (ref.taskKind === TASKKIND_TEMPLATE) {
188
+ if (!inForeach.some((o) => o.endsWith(".tasks")))
189
+ err(f, `${where}: "{{task.taskKind}}" is only valid inside a foreach over tasks`);
190
+ if (!ref.allowedTaskKinds?.length) {
191
+ err(f, `${where}: "{{task.taskKind}}" needs allowedTaskKinds`);
192
+ return;
193
+ }
194
+ needed = ref.allowedTaskKinds;
195
+ }
196
+ else {
197
+ needed = [ref.taskKind];
198
+ }
199
+ const templated = ref.persona === STACK_TEMPLATE || ref.persona === ANALYST_TEMPLATE;
200
+ for (const k of needed) {
201
+ if (!kinds.has(k))
202
+ err(f, `${where}: taskKind "${k}" is not in model-policy.yaml`);
203
+ const missing = candidates.filter((p) => !p.taskKinds.includes(k));
204
+ if (!templated || missing.length === candidates.length) {
205
+ for (const p of missing)
206
+ err(f, `${where}: persona "${p.id}" has no taskKind "${k}"`);
207
+ }
208
+ else {
209
+ // The task decides at run time; `friday handoff check --pack` rejects such a task upstream.
210
+ for (const p of missing)
211
+ warn(f, `${where}: persona "${p.id}" has no taskKind "${k}"; handoff check rejects ${k} tasks for it`);
212
+ }
213
+ }
214
+ };
215
+ // Which upstream orchestrations have a person approve each prompt pyramid level.
216
+ const upstreamApprovals = new Map();
217
+ for (const w of lp.orchestrations) {
218
+ if (w.stream !== "upstream")
219
+ continue;
220
+ for (const s of w.steps)
221
+ if (s.type === "approval" && s.level)
222
+ upstreamApprovals.set(s.level, [...(upstreamApprovals.get(s.level) ?? []), w.id]);
223
+ }
224
+ for (const w of lp.orchestrations) {
225
+ const f = files.get(w) ?? w.id;
226
+ if (!personas.has(w.orchestrator))
227
+ err(f, `orchestrator "${w.orchestrator}" is not a persona`);
228
+ const ids = new Set();
229
+ const hasHandoffStep = { value: false };
230
+ const fromHandoff = !!w.requires?.includes("handoff");
231
+ if (w.stream === "downstream" && !w.requires?.length) {
232
+ err(f, "a downstream workflow must declare requires: [handoff] or [changesets]");
233
+ }
234
+ if (w.stream === "upstream" && w.requires?.length) {
235
+ err(f, "an upstream workflow produces the handoff; it cannot require anything");
236
+ }
237
+ if (w.stream === "downstream" && (w.maxItemsPerRound !== undefined || w.closeOutFromRound !== undefined || w.deferNonBlocking !== undefined)) {
238
+ err(f, "maxItemsPerRound, closeOutFromRound and deferNonBlocking shape the upstream question loop; downstream workflows never ask");
239
+ }
240
+ if (w.stream === "downstream" && w.maxRounds !== undefined) {
241
+ err(f, "maxRounds bounds the upstream question loop; downstream workflows never ask");
242
+ }
243
+ const asSkill = emits(w, "skill");
244
+ if (asSkill && !w.sizing)
245
+ err(f, "a skill output needs sizing: the skill measures the work before it picks how many agents run at once");
246
+ if (!asSkill && w.sizing)
247
+ err(f, "sizing applies only to a skill output; a workflow script fixes its own concurrency");
248
+ if (w.sizing && w.sizing.medium >= w.sizing.large)
249
+ err(f, `sizing.medium (${w.sizing.medium}) must be below sizing.large (${w.sizing.large})`);
250
+ let taskLoops = 0;
251
+ walkSteps(w.steps, (step, inForeach) => {
252
+ const where = `step ${step.id}`;
253
+ if (step.type === "tdd-pair")
254
+ taskLoops++;
255
+ if (step.type === "preflight") {
256
+ if (!fromHandoff)
257
+ err(f, `${where}: preflight resolves a handoff's prerequisites; the workflow must require a handoff`);
258
+ if (w.steps[0] !== step)
259
+ err(f, `${where}: preflight must be the first step of the workflow`);
260
+ }
261
+ if (ids.has(step.id))
262
+ err(f, `${where}: duplicate step id`);
263
+ if (asSkill && !SKILL_STEP_TYPES.has(step.type)) {
264
+ err(f, `${where}: ${step.type} needs the workflow runtime (bounded loops, waves); use outputs: [workflow]`);
265
+ }
266
+ ids.add(step.id);
267
+ if (UPSTREAM_ONLY.has(step.type) && w.stream === "downstream") {
268
+ err(f, `${where}: ${step.type} steps ask or hand off and are only allowed upstream`);
269
+ }
270
+ if (step.type === "handoff")
271
+ hasHandoffStep.value = true;
272
+ if (step.when && !fromHandoff)
273
+ err(f, `${where}: when reads the handoff; the workflow must require one`);
274
+ const refs = [];
275
+ if ("persona" in step && "taskKind" in step)
276
+ refs.push({ persona: step.persona, taskKind: step.taskKind });
277
+ if (step.type === "tdd-pair")
278
+ refs.push(step.test, step.impl, step.verify);
279
+ if (step.type === "gate" && step.onFail)
280
+ refs.push(step.onFail);
281
+ for (const r of refs)
282
+ checkRef(f, where, r, inForeach);
283
+ // Agents never approve their own work (decision 25): the agent that judges is not the one
284
+ // whose work it judges.
285
+ const stackPersonas = new Set(Object.values(pack.stacks));
286
+ const same = (a, b) => a === b || (a === STACK_TEMPLATE && stackPersonas.has(b)) || (b === STACK_TEMPLATE && stackPersonas.has(a));
287
+ if (step.type === "gate" && step.onFail && same(step.persona, step.onFail.persona)) {
288
+ err(f, `${where}: the gate's persona fixes its own findings (onFail ${step.onFail.persona}); agents never approve their own work`);
289
+ }
290
+ if (step.type === "tdd-pair") {
291
+ for (const [role, ref] of [["test", step.test], ["verify", step.verify]]) {
292
+ if (same(ref.persona, step.impl.persona))
293
+ err(f, `${where}: ${role} and impl are the same persona; the implementer never writes or verifies its own tests`);
294
+ }
295
+ }
296
+ // The loop guardrail would block the integration loop's own suites.
297
+ if (step.type === "integration-loop" && guards?.loopCommands?.taskKinds.includes(step.integrate.taskKind)) {
298
+ err(f, `${where}: guardrails.loopCommands blocks taskKind "${step.integrate.taskKind}", which runs the integration loop`);
299
+ }
300
+ // Test pyramid: the task loop stays at the bottom; integration covers what it skips.
301
+ const pyramid = pack.testPyramid;
302
+ const levelIds = new Set(pyramid?.levels.map((l) => l.id) ?? []);
303
+ if (step.type === "tdd-pair") {
304
+ if (!pyramid)
305
+ err(f, `${where}: tdd-pair needs testPyramid in pack.yaml`);
306
+ for (const l of step.testScope) {
307
+ if (!levelIds.has(l))
308
+ err(f, `${where}: unknown test level "${l}"`);
309
+ else if (!pyramid.loopLevels.includes(l)) {
310
+ err(f, `${where}: task loops run only the bottom of the pyramid (${pyramid.loopLevels.join(", ")}); "${l}" belongs to integration`);
311
+ }
312
+ }
313
+ }
314
+ if (step.type === "integration-loop") {
315
+ if (!fromHandoff)
316
+ err(f, `${where}: integration-loop builds handoff tasks; the workflow must require a handoff`);
317
+ checkRef(f, where, step.integrate, [...inForeach, "handoff.stacks"]);
318
+ if (!pyramid)
319
+ err(f, `${where}: integration-loop needs testPyramid in pack.yaml`);
320
+ else {
321
+ for (const l of step.testScope)
322
+ if (!levelIds.has(l))
323
+ err(f, `${where}: unknown test level "${l}"`);
324
+ const skipped = pyramid.levels.map((l) => l.id).filter((l) => !pyramid.loopLevels.includes(l));
325
+ for (const l of skipped) {
326
+ if (!step.testScope.includes(l))
327
+ err(f, `${where}: integration must run "${l}", which task loops never run`);
328
+ }
329
+ }
330
+ }
331
+ if (step.type === "foreach") {
332
+ const ok = step.over === "handoff.tasks" || step.over === "handoff.stacks" || /^[a-z][a-z0-9-]*\.tasks$/.test(step.over);
333
+ if (!ok)
334
+ err(f, `${where}: over must be handoff.tasks, handoff.stacks or <stepId>.tasks`);
335
+ if (step.over.startsWith("handoff.") && !fromHandoff)
336
+ err(f, `${where}: ${step.over} needs requires: [handoff]`);
337
+ }
338
+ // Model policy: a step may not pick a different model than its task kind without a reason.
339
+ if (step.model && "taskKind" in step && kinds.has(step.taskKind)) {
340
+ const expected = policy.taskKinds[step.taskKind].model;
341
+ if (step.model !== expected) {
342
+ const msg = `${where}: model ${step.model} overrides policy (${step.taskKind} -> ${expected})`;
343
+ if (!step.override?.reason) {
344
+ if (policy.enforce === "strict")
345
+ err(f, `${msg} without override.reason`);
346
+ else
347
+ warn(f, msg);
348
+ }
349
+ else
350
+ warn(f, `${msg}: ${step.override.reason}`);
351
+ }
352
+ }
353
+ });
354
+ approvalIssues(w, pack, upstreamApprovals, err.bind(null, f));
355
+ if (w.retro)
356
+ checkRef(f, "retro", w.retro, []);
357
+ else
358
+ warn(f, "no retro: finished runs will not write retro.md or propose Friday improvements");
359
+ if (w.stream === "upstream" && !hasHandoffStep.value)
360
+ err(f, "an upstream workflow must end in a handoff step");
361
+ // Task loops reuse one install and never discover a missing prerequisite halfway (decision 48).
362
+ if (taskLoops && w.steps[0]?.type !== "preflight")
363
+ err(f, "a workflow with task loops must start with a preflight step");
364
+ if (w.stream === "upstream") {
365
+ const last = w.steps[w.steps.length - 1];
366
+ if (last && last.type !== "handoff")
367
+ err(f, "the handoff step must be the last step of an upstream workflow");
368
+ }
369
+ for (const k of Object.keys(w.inputs ?? {})) {
370
+ if (w.stream === "upstream" && !["workId", "request", ...CONTEXT_INPUTS].includes(k))
371
+ warn(f, `input ${k} is passed through as context only`);
372
+ }
373
+ }
374
+ return issues;
375
+ }
376
+ /**
377
+ * Approvals (decisions 33 and 39): a person approves every prompt pyramid level, from the bottom,
378
+ * in order, and every checkpoint; nothing builds a level before the level below it is approved,
379
+ * and nothing builds a level or a checkpoint after its own approval.
380
+ */
381
+ function approvalIssues(w, pack, upstreamApprovals, err) {
382
+ const pyramid = pack.promptPyramid;
383
+ // Every leaf step with the top-level position it runs at and the level or checkpoint it builds
384
+ // (inherited from its group).
385
+ const leavesOf = [];
386
+ const nested = (steps, top, level, checkpoint) => {
387
+ for (const s of steps) {
388
+ const lv = s.level ?? level;
389
+ const cp = s.checkpoint ?? checkpoint;
390
+ if (s.type === "approval" && !w.steps.includes(s))
391
+ err(`step ${s.id}: an approval step must be a top-level step`);
392
+ if (lv && cp)
393
+ err(`step ${s.id}: names both a level and a checkpoint`);
394
+ if ("steps" in s)
395
+ nested(s.steps, top, lv, cp);
396
+ else
397
+ leavesOf.push({ step: s, top, ...(lv ? { level: lv } : {}), ...(cp ? { checkpoint: cp } : {}) });
398
+ }
399
+ };
400
+ w.steps.forEach((s, i) => nested([s], i, undefined, undefined));
401
+ const approvals = leavesOf.filter((l) => l.step.type === "approval");
402
+ const levelApprovals = approvals.filter((a) => a.level);
403
+ const cpApprovals = approvals.filter((a) => a.checkpoint && !a.level);
404
+ const builders = leavesOf.filter((l) => l.step.type !== "approval" && l.level && !l.checkpoint);
405
+ const cpBuilders = leavesOf.filter((l) => l.step.type !== "approval" && l.checkpoint && !l.level);
406
+ if (!approvals.length && !builders.length && !cpBuilders.length)
407
+ return;
408
+ if (approvals.length && emits(w, "workflow"))
409
+ err("approval steps need outputs: [skill]; a workflow script cannot wait for a person between steps");
410
+ if (approvals.length && !leavesOf.some((l) => l.step.type === "gap-analysis" && l.step.consolidate)) {
411
+ err("approval steps need a gap-analysis step with consolidate: true; its agent merges each level's open items at the stop");
412
+ }
413
+ // Checkpoints (decision 39): built and approved upstream, each approval after its builders.
414
+ if (cpBuilders.length || cpApprovals.length) {
415
+ const ids = new Set((pack.checkpoints ?? []).map((c) => c.id));
416
+ const knownCp = (id, step) => {
417
+ if (ids.has(id))
418
+ return true;
419
+ err(`step ${step.id}: unknown checkpoint "${id}"`);
420
+ return false;
421
+ };
422
+ if (w.stream === "downstream") {
423
+ for (const b of cpBuilders)
424
+ err(`step ${b.step.id}: checkpoints are built and approved upstream; downstream never asks`);
425
+ }
426
+ else {
427
+ const at = new Map();
428
+ for (const a of cpApprovals)
429
+ if (knownCp(a.checkpoint, a.step))
430
+ at.set(a.checkpoint, a.top);
431
+ for (const b of cpBuilders) {
432
+ if (!knownCp(b.checkpoint, b.step))
433
+ continue;
434
+ const own = at.get(b.checkpoint);
435
+ if (own === undefined)
436
+ err(`step ${b.step.id}: checkpoint "${b.checkpoint}" has no approval step`);
437
+ else if (b.top > own)
438
+ err(`step ${b.step.id}: builds checkpoint "${b.checkpoint}" after its approval step`);
439
+ }
440
+ for (const a of cpApprovals) {
441
+ if (ids.has(a.checkpoint) && !cpBuilders.some((b) => b.checkpoint === a.checkpoint && b.top < a.top)) {
442
+ err(`step ${a.step.id}: no step builds checkpoint "${a.checkpoint}" before it`);
443
+ }
444
+ }
445
+ }
446
+ }
447
+ // Prompt pyramid levels (decisions 33 and 34).
448
+ if (!levelApprovals.length && !builders.length)
449
+ return;
450
+ if (!pyramid) {
451
+ err("approval steps and step levels need promptPyramid in pack.yaml");
452
+ return;
453
+ }
454
+ const levels = pyramid.levels.map((l) => l.id);
455
+ const known = (id, step) => {
456
+ if (levels.includes(id))
457
+ return true;
458
+ err(`step ${step.id}: unknown promptPyramid level "${id}"`);
459
+ return false;
460
+ };
461
+ const specialist = (step, level) => {
462
+ if (!("persona" in step) || !("taskKind" in step))
463
+ return;
464
+ const { persona, taskKind } = step;
465
+ const specialists = pyramid.levels.find((l) => l.id === level).specialists;
466
+ if (!specialists.some((sp) => sp.persona === persona && sp.taskKind === taskKind)) {
467
+ err(`step ${step.id}: ${persona} (${taskKind}) is not a specialist of level "${level}"`);
468
+ }
469
+ };
470
+ // Downstream never asks: it builds only the levels no upstream run has a person approve, and a
471
+ // person approves those through the pull request (decision 34).
472
+ if (w.stream === "downstream") {
473
+ for (const b of builders) {
474
+ const level = b.level;
475
+ if (!known(level, b.step))
476
+ continue;
477
+ const by = upstreamApprovals.get(level);
478
+ if (by)
479
+ err(`step ${b.step.id}: level "${level}" is approved upstream by a person (${by.join(", ")}); downstream builds only the levels no upstream run approves`);
480
+ specialist(b.step, level);
481
+ }
482
+ return;
483
+ }
484
+ const approvedAt = new Map();
485
+ for (const a of levelApprovals)
486
+ if (known(a.level, a.step))
487
+ approvedAt.set(a.level, a.top);
488
+ const order = levelApprovals.map((a) => a.level);
489
+ if (order.some((l, i) => levels[i] !== l)) {
490
+ err(`approvals must cover the prompt pyramid from the bottom, in order (${levels.join(" < ")}); found ${order.join(", ")}`);
491
+ }
492
+ for (const b of builders) {
493
+ const level = b.level;
494
+ if (!known(level, b.step))
495
+ continue;
496
+ const own = approvedAt.get(level);
497
+ if (own === undefined)
498
+ err(`step ${b.step.id}: level "${level}" has no approval step`);
499
+ else if (b.top > own)
500
+ err(`step ${b.step.id}: builds level "${level}" after its approval step`);
501
+ const below = levels[levels.indexOf(level) - 1];
502
+ const belowAt = below === undefined ? undefined : approvedAt.get(below);
503
+ if (below !== undefined && (belowAt === undefined || b.top < belowAt)) {
504
+ err(`step ${b.step.id}: builds level "${level}" before level "${below}" is approved`);
505
+ }
506
+ specialist(b.step, level);
507
+ }
508
+ for (const a of levelApprovals) {
509
+ if (levels.includes(a.level) && !builders.some((b) => b.level === a.level && b.top < a.top)) {
510
+ err(`step ${a.step.id}: no step builds level "${a.level}" before it`);
511
+ }
512
+ }
513
+ }
514
+ // "Document, don't invent": a rule names where it comes from (decision 30). A project rule cites
515
+ // <repo>/<path> of a repository in the pack's sources, which only a specialization adds (decision
516
+ // 42); a generic rule cites an https:// page; Friday's own rules cite a decision or give a why.
517
+ const SOURCE_FORMS = /^(https:\/\/|decision \d+)/;
518
+ function sourceIssues(lp, files) {
519
+ const repos = (lp.pack.sources ?? []).map((s) => s.split("/").pop().toLowerCase());
520
+ const bad = (src) => !SOURCE_FORMS.test(src) && !repos.includes(src.split("/")[0].toLowerCase());
521
+ const issues = [];
522
+ const msg = (src) => `source "${src}" is neither an https:// page, a decision, nor <repo>/<path> of a repository in sources (${repos.join(", ") || "none"})`;
523
+ for (const c of lp.conventions) {
524
+ for (const r of c.rules) {
525
+ if (r.source && bad(r.source))
526
+ issues.push({ level: "error", file: files.get(c) ?? c.id, message: `rule ${r.id}: ${msg(r.source)}` });
527
+ }
528
+ }
529
+ for (const l of lp.pack.testPyramid?.levels ?? []) {
530
+ if (l.source && bad(l.source))
531
+ issues.push({ level: "error", file: files.get(lp.pack) ?? "pack.yaml", message: `testPyramid level ${l.id}: ${msg(l.source)}` });
532
+ }
533
+ return issues;
534
+ }
535
+ /**
536
+ * Validate a pack, with the specializations (folders, already resolved) merged in, in order
537
+ * (decision 41).
538
+ */
539
+ export function validatePack(packArg, specs = []) {
540
+ const raw = loadRawPack(packArg);
541
+ const applied = applySpecializations(raw, specs);
542
+ const issues = raw.parseErrors.map((e) => ({ level: "error", file: e.file, message: e.message }));
543
+ for (const w of raw.warnings)
544
+ issues.push({ level: "warning", file: w.file, message: w.message });
545
+ for (const doc of raw.docs)
546
+ issues.push(...schemaIssues(doc));
547
+ if (issues.some((i) => i.level === "error"))
548
+ return { ok: false, issues };
549
+ const files = new Map();
550
+ const of = (kind) => raw.docs
551
+ .filter((d) => d.kind === kind)
552
+ .map((d) => {
553
+ files.set(d.data, d.file);
554
+ return d.data;
555
+ });
556
+ const lp = {
557
+ dir: raw.dir,
558
+ pack: of("pack")[0],
559
+ policy: of("model-policy")[0],
560
+ personas: of("persona"),
561
+ conventions: of("convention"),
562
+ orchestrations: of("orchestration"),
563
+ specializations: applied,
564
+ };
565
+ issues.push(...crossRefIssues(lp, files), ...sourceIssues(lp, files));
566
+ const ok = !issues.some((i) => i.level === "error");
567
+ return ok ? { ok, issues, pack: lp } : { ok, issues };
568
+ }
569
+ export function loadPack(packArg, specs = []) {
570
+ const r = validatePack(packArg, specs);
571
+ if (!r.ok || !r.pack) {
572
+ const lines = r.issues.filter((i) => i.level === "error").map((i) => ` ${i.file}: ${i.message}`);
573
+ throw new Error(`friday: pack is invalid:\n${lines.join("\n")}`);
574
+ }
575
+ return r.pack;
576
+ }
@@ -0,0 +1,20 @@
1
+ id: changesets
2
+ stack: release
3
+ description: Versioning and changelogs with changesets. Every user-facing change carries a changeset; releases are prepared from them.
4
+ appliesTo:
5
+ paths: [".changeset/**", "**/CHANGELOG.md", "**/package.json"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: one-per-change
9
+ rule: "Every PR with a user-facing change adds a changeset (pnpm changeset, or .changeset/<slug>.md) naming each package it changes and the bump: fix -> patch, feat -> minor, a breaking change (feat! or BREAKING CHANGE) -> major."
10
+ why: The release is prepared from the changesets, so a change without one is missing from the version and the changelog.
11
+ source: decision 16 (friday docs/decisions.md)
12
+ - id: summary
13
+ rule: The changeset summary is one user-facing sentence in the imperative; a major bump adds the migration steps.
14
+ source: https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md
15
+ - id: no-change
16
+ rule: A PR with no user-facing change (tests, CI, docs) adds an empty changeset (pnpm changeset --empty) so the check can tell it was considered.
17
+ source: decision 16 (friday docs/decisions.md)
18
+ - id: release
19
+ rule: Releases are cut from the pending changesets (changeset version, then publish), by the repository's release workflow, never by hand-editing versions or changelogs.
20
+ source: https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md
@@ -0,0 +1,16 @@
1
+ id: ci-workflows
2
+ stack: github-actions
3
+ description: GitHub Actions and pipeline security checks.
4
+ appliesTo:
5
+ paths: [".github/**"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: permissions
9
+ rule: "permissions: contents: read at the top; a job adds only what it needs (id-token: write for OIDC)."
10
+ source: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions
11
+ - id: pins
12
+ rule: Third-party actions pinned by full SHA with a # vX.Y.Z comment; actions/checkout with persist-credentials false unless a later step pushes.
13
+ source: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions
14
+ - id: forbidden
15
+ rule: No pull_request_target with a checkout of the PR's code. No secrets inherit; pass each secret by name. Workflow inputs reach scripts through env, never inline in run:.
16
+ source: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions
@@ -0,0 +1,16 @@
1
+ id: config-secrets
2
+ stack: config
3
+ description: Settings and secrets.
4
+ appliesTo:
5
+ paths: ["config/**", "**/.env*", ".github/**"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: conf-files
9
+ rule: Non-secret settings are committed, one key per line with a comment saying why, and the same keys exist for every environment. An unknown or missing key fails the build.
10
+ source: https://12factor.net/config
11
+ - id: secrets
12
+ rule: Secrets live in a secret manager and reach the runtime as environment, at run time. Never in a flag, an image layer, a log or a committed file.
13
+ source: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
14
+ - id: github-vars
15
+ rule: A setting never comes from a CI variable when it can be committed.
16
+ why: A committed setting is reviewed and versioned with the code that reads it.
@@ -0,0 +1,16 @@
1
+ id: data-classification
2
+ stack: data
3
+ description: Classification and handling of personal (PII) and non-personal data.
4
+ emit: [rule, skill]
5
+ rules:
6
+ - id: classify
7
+ rule: Every collection and field a change touches is classified pii or non-pii, with an owner project and a retention period, recorded in the handoff and docs/decisions.md.
8
+ why: Unclassified data cannot be secured or analysed safely; it is a gap upstream.
9
+ - id: owner
10
+ rule: Personal data is read and written only by the project that owns it. Other projects use its API or a personal-data-safe use case.
11
+ source: https://eur-lex.europa.eu/eli/reg/2016/679/oj
12
+ - id: analysis
13
+ rule: PII analysis goes through data-analyst-pii and outputs aggregates or pseudonymised identifiers only. data-analyst-non-pii refuses pii or unclassified inputs.
14
+ - id: no-copies
15
+ rule: Never copy personal data into tests, seeds, fixtures, logs, prompts, commits or PRs.
16
+ source: https://eur-lex.europa.eu/eli/reg/2016/679/oj
@@ -0,0 +1,13 @@
1
+ id: decisions
2
+ stack: docs
3
+ description: Numbered decisions in docs/decisions.md.
4
+ appliesTo:
5
+ paths: ["docs/decisions.md"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: format
9
+ rule: "## topic sections; each decision is a numbered bold one-line rule, then the reason, then where it lives in code."
10
+ source: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
11
+ - id: numbers
12
+ rule: Numbers are never reused. A reversed decision stays, marked "Replaced by N". Code and workflow comments cite them ("decision 7").
13
+ source: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions