@digital-agora/friday 0.9.0 → 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.
package/README.md CHANGED
@@ -21,7 +21,7 @@ that on (decision 43, "Develop" below). From npmjs.com it needs no token: leave
21
21
  `@digital-agora:registry` line out of `~/.npmrc`.
22
22
 
23
23
  Internal packages (Hybrid-Day's specialization, decision 42) are on GitHub Packages only, and so
24
- is every version of Friday. Installing from there needs a GitHub personal access token (classic)
24
+ is every version of Friday and of the open-source specializations (Google Cloud's, decision 53). Installing from there needs a GitHub personal access token (classic)
25
25
  with `read:packages`, from https://github.com/settings/tokens/new?scopes=read:packages, in
26
26
  `~/.npmrc`:
27
27
 
@@ -98,8 +98,25 @@ npx -y @digital-agora/friday install --with ./path/to/specialization --with @acm
98
98
  A project rule cites its repository (`<repo>/<path>`, a repository in the specialization's
99
99
  `sources`); `friday validate --with <it>` checks the merged pack.
100
100
 
101
- Hybrid-Day's specialization lives in `specializations/hybrid-day/` and is published to GitHub
102
- Packages only, as `@digital-agora/friday-hybrid-day`:
101
+ A specialization can build on another with `extends` in `specialization.yaml` (a folder, or a
102
+ package it depends on); what it extends is applied first, so it wins (decision 53):
103
+
104
+ ```yaml
105
+ extends: ["@digital-agora/friday-google-cloud"]
106
+ ```
107
+
108
+ Google Cloud's specialization lives in `specializations/google-cloud/`: the rules that hold for any
109
+ project on Google Cloud and Firebase (Firestore rules and `private/` documents for protected fields,
110
+ service accounts and Workload Identity Federation, Secret Manager, Cloud Run, `demo-` emulator
111
+ projects), each citing Google's documentation. It is MIT-licensed and published with friday, to
112
+ npmjs.com too, as `@digital-agora/friday-google-cloud`:
113
+
114
+ ```bash
115
+ npx -y @digital-agora/friday-google-cloud install
116
+ ```
117
+
118
+ Hybrid-Day's specialization lives in `specializations/hybrid-day/`, extends Google Cloud's, and is
119
+ published to GitHub Packages only, as `@digital-agora/friday-hybrid-day`:
103
120
 
104
121
  ```bash
105
122
  npx -y @digital-agora/friday-hybrid-day install
@@ -251,14 +268,17 @@ pnpm typecheck && pnpm build && pnpm lint && pnpm test
251
268
  Friday releases itself from changesets too: `pnpm changeset` in every PR (CI checks it), then
252
269
  **Actions › Release › Run workflow** on `main` versions friday and the specializations, publishes
253
270
  them to GitHub Packages, and pushes the `chore(release)` commit and the tags (`v<version>` for
254
- friday, `friday-hybrid-day@<version>` for Hybrid-Day's; decision 22). **dry-run** rehearses it
271
+ friday, `friday-<id>@<version>` for a specialization, such as `friday-hybrid-day@<version>`;
272
+ decision 22). **dry-run** rehearses it
255
273
  and pushes nothing.
256
274
 
257
- Publishing friday to npmjs.com as well is off unless turned on (decision 43):
275
+ Publishing friday and the open-source specializations to npmjs.com as well is off unless turned
276
+ on (decisions 43, 53):
258
277
 
259
- 1. The `@digital-agora` scope is an npm organization that can publish `@digital-agora/friday`.
278
+ 1. The `@digital-agora` scope is an npm organization that can publish `@digital-agora/friday` and
279
+ `@digital-agora/friday-google-cloud`.
260
280
  2. The organization secret `NPM_TOKEN` (an automation token, or a granular token with read and
261
- write on `@digital-agora/friday` and bypass 2FA) is shared with this repository: Organization ›
281
+ write on the `@digital-agora` scope, or on both packages once they exist, and bypass 2FA) is shared with this repository: Organization ›
262
282
  Settings › Secrets and variables › Actions › `NPM_TOKEN` › Repository access.
263
283
  3. Turn it on for every release with the repository variable `PUBLISH_NPMJS` = `true`, or for one
264
284
  with **npmjs** ticked in Run workflow. `NPM_ACCESS` = `restricted` keeps it private (default
@@ -266,11 +286,12 @@ Publishing friday to npmjs.com as well is off unless turned on (decision 43):
266
286
 
267
287
  The npmjs.com step runs after GitHub Packages and before anything is pushed; a rerun skips what is
268
288
  already published. Without the secret it stops with an error instead of releasing to one registry
269
- only. Specializations never go to npmjs.com.
289
+ only. A specialization goes to npmjs.com only when its license is not `UNLICENSED` (Google
290
+ Cloud's); Hybrid-Day's never does.
270
291
 
271
292
  Layout: `schemas/` (the YAML schemas), `pack/` (Friday's personas, conventions, workflows,
272
- model policy and test pyramid, all generic), `specializations/` (project specializations, such
273
- as Hybrid-Day's, each its own package), `src/` (loader, validator, IR,
293
+ model policy and test pyramid, all generic), `specializations/` (platform and project specializations,
294
+ such as Google Cloud's and Hybrid-Day's, each its own package), `src/` (loader, validator, IR,
274
295
  `src/adapters/<target>/`, bundle, install, CLI), `test/` (vitest, including a harness that runs
275
296
  the generated workflow scripts with mocked agents). See `CLAUDE.md` for the rules and
276
297
  `docs/decisions.md` for why things are the way they are.
Binary file
Binary file
@@ -217,9 +217,11 @@ user's behalf, never skip one, never fill a gap with a guess.
217
217
  - each **gap**: "<gap>. Why: <why>. Impact: <impact>." with its solutions as options
218
218
  (each with its trade-off), the recommended one first.${consolidates(w) ? `
219
219
  - each **contradiction**: "Contradiction: <conflict> (between <between>). Why: <why>. Both
220
- sides agree on: <overlap>." with its options, the inner-join sweet spot (the overlap plus the
220
+ sides agree on: <overlap>. It rests on: <premise>." with its options, the inner-join sweet spot (the overlap plus the
221
221
  least each side must add) first, marked "(Recommended)" when it is. Never pick for the user. Record the answer with
222
222
  \`supersedes\`: the ids in \`between\` that are answers; the run then reads only the new one.
223
+ If the user picks "None of these: the premise is wrong", ask for their design in the same
224
+ turn and record their words, verbatim, as the answer (decision 54).
223
225
  - **dropped**: list each in one line with its reason, after the questions. If the user wants
224
226
  one back, record what they say about it as an answer.` : ""}
225
227
  ${w.deferNonBlocking ? "Do not ask about an item explicitly marked \`blocking: false\`; defer it to \`scope.outOfScope\` and continue. Contradictions and items that block writing or testing a task still require an answer. " : ""}Keep asking until every blocking item has an answer. Append each answer to \`answers\`
@@ -227,9 +229,13 @@ user's behalf, never skip one, never fill a gap with a guess.
227
229
  \`resolution\`, to \`gapResolutions\`.
228
230
  **Record answers faithfully.** \`answer\` is the user's own words, verbatim (or the option
229
231
  label they picked); what you take it to mean goes in a separate \`interpretation\` line. Never
230
- fold an option, a detail or a safeguard the user did not pick into the answer. When an answer
231
- addresses a different layer than the question (e.g. the UI when the question is about the
232
- server), it does not answer it: record it as a note and re-ask the question in the same turn. Save them${bounded ? " and the round state" : ""} to \`docs/friday/<workId>/answers.yaml\` after
232
+ fold an option, a detail or a safeguard the user did not pick into the answer.
233
+ **Classify every free-text answer before you record it** (decision 54): an answer; a question
234
+ back (answer it now, from the results so far, then ask the item again in the same turn); a
235
+ directive (a rule for the whole work: record it verbatim as an answer with id
236
+ \`directive-<n>\` and ask the item again if it does not settle it); or another layer (e.g. the UI
237
+ when the question is about the server: it does not answer it, so record it as a note and ask
238
+ the question again in the same turn). Only an answer closes the item. Save them${bounded ? " and the round state" : ""} to \`docs/friday/<workId>/answers.yaml\` after
233
239
  every round, then go back to step 2. A re-run sees every answer, so new questions are
234
240
  follow-ups, not repeats. When the lists grow (more than about 20 items), pass
235
241
  \`answersFile: docs/friday/<workId>/answers.yaml\` with \`answeredIds\` and \`resolvedIds\` (the ids
package/dist/prompts.js CHANGED
@@ -57,6 +57,8 @@ export const CONSOLIDATE = [
57
57
  " plus the least each side must add to meet the acceptance criteria; then each side as it",
58
58
  " stands. Recommend the sweet spot unless the overlap is empty or cannot meet an acceptance",
59
59
  " criterion (say which in why). Do not pick one yourself: the user does.",
60
+ " State in premise the assumption every option rests on (decision 54), and end the options",
61
+ " with \"None of these: the premise is wrong\", which asks the user for their design.",
60
62
  "4. Add the gaps you find yourself. A scope (result.scopes) whose expected outcome the user has",
61
63
  " not stated, in the request or an answer, is a blocking question: never drop or defer it.",
62
64
  "Every open item below must end up in your output, in a mergedFrom, or in dropped.",
@@ -138,23 +138,59 @@ function mergePack(base, spec, file, raw) {
138
138
  return out;
139
139
  }
140
140
  /**
141
- * Merge specializations into a raw pack, in order. Problems become parse errors of the
142
- * specialization's file, so validation reports them with the rest.
141
+ * The specializations to apply, in order: each one's `extends` (decision 53) comes before it,
142
+ * depth first, and a folder reached twice is applied once, at its first place. A reference that
143
+ * does not resolve, or a cycle, becomes a parse error of the specialization that names it.
143
144
  */
144
- export function applySpecializations(raw, dirs) {
145
- const applied = [];
146
- for (const dir of dirs) {
145
+ function expandExtends(dirs, raw) {
146
+ const out = [];
147
+ const done = new Set();
148
+ const visit = (dir, stack) => {
149
+ const key = resolve(dir);
150
+ if (done.has(key))
151
+ return;
147
152
  const specFile = join(dir, SPECIALIZATION_FILE);
153
+ if (stack.includes(key)) {
154
+ raw.parseErrors.push({ file: specFile, message: `extends: cycle through ${[...stack, key].join(" -> ")}` });
155
+ return;
156
+ }
148
157
  let spec;
149
158
  try {
150
159
  spec = parse(readFileSync(specFile, "utf8"));
151
160
  }
152
161
  catch (err) {
153
162
  raw.parseErrors.push({ file: specFile, message: err.message });
154
- continue;
163
+ return;
155
164
  }
156
165
  if (!check(schemas().spec, spec, specFile, raw))
157
- continue;
166
+ return;
167
+ for (const ref of spec.extends ?? []) {
168
+ let base;
169
+ try {
170
+ base = resolveSpecialization(ref, dir);
171
+ }
172
+ catch (err) {
173
+ raw.parseErrors.push({ file: `${String(spec.id)}:${SPECIALIZATION_FILE}`, message: `extends: ${err.message}` });
174
+ continue;
175
+ }
176
+ visit(base, [...stack, key]);
177
+ }
178
+ if (done.has(key))
179
+ return;
180
+ done.add(key);
181
+ out.push({ dir, spec });
182
+ };
183
+ for (const dir of dirs)
184
+ visit(dir, []);
185
+ return out;
186
+ }
187
+ /**
188
+ * Merge specializations into a raw pack, in order, each after the ones it extends. Problems
189
+ * become parse errors of the specialization's file, so validation reports them with the rest.
190
+ */
191
+ export function applySpecializations(raw, dirs) {
192
+ const applied = [];
193
+ for (const { dir, spec } of expandExtends(dirs, raw)) {
158
194
  const label = spec.id;
159
195
  const name = spec.name;
160
196
  const file = `${label}:${SPECIALIZATION_FILE}`;
@@ -75,7 +75,7 @@ const mergedFrom = {
75
75
  const merged = (s) => ({ ...s, properties: { ...s.properties, mergedFrom } });
76
76
  export const CONTRADICTION = {
77
77
  type: "object",
78
- required: ["id", "conflict", "between", "why", "overlap", "options", "recommended"],
78
+ required: ["id", "conflict", "between", "why", "overlap", "premise", "options", "recommended"],
79
79
  properties: {
80
80
  id: { type: "string", description: "Stable id, e.g. C-export-format. Reuse it on re-runs." },
81
81
  conflict: { type: "string", description: "What contradicts what, in one sentence." },
@@ -85,9 +85,13 @@ export const CONTRADICTION = {
85
85
  type: "string",
86
86
  description: "The inner join: what every conflicting source already holds or accepts. Empty when they share nothing.",
87
87
  },
88
+ premise: {
89
+ type: "string",
90
+ description: "The assumption every option rests on, e.g. that the consumer pulls the data (decision 54).",
91
+ },
88
92
  options: {
89
93
  ...QUESTION.properties.options,
90
- description: "First the sweet spot: the overlap plus the least each side must add to meet the acceptance criteria. Then each side as it stands.",
94
+ description: 'First the sweet spot: the overlap plus the least each side must add to meet the acceptance criteria. Then each side as it stands. Last "None of these: the premise is wrong".',
91
95
  },
92
96
  recommended: QUESTION.properties.recommended,
93
97
  },
@@ -56,7 +56,13 @@ steps:
56
56
  or an answer excludes), facts checked (what you verified in the repository, with the file, so
57
57
  no later step asks about it) and unknowns. Every field names its source: request,
58
58
  repository (file), answer (id), convention (id) or proposed. Never invent one; what you would
59
- have to guess is a proposal or a question. Put it in result.brief.
59
+ have to guess is a proposal or a question. Premises (decision 54): for the data the request
60
+ touches, state the classification of every named field, the consumers and the trust boundary
61
+ between them, whether protected data is pushed or pulled, the role of each data store (the
62
+ record or a live view), the load, and the latency targets with their measurement window. A
63
+ premise the request, the repository or an answer does not settle is a blocking question,
64
+ never a proposal, so every perspective starts from approved premises. Put the brief in
65
+ result.brief and the premises in result.brief.premises.
60
66
  - id: approve-brief
61
67
  type: approval
62
68
  checkpoint: brief
@@ -74,7 +80,11 @@ steps:
74
80
  blocking question to the user with 2-4 concrete outcomes as options (outcomeSource:
75
81
  answer, answerId: the question id). Never assume an outcome or derive it from the scope's
76
82
  title. Put them in result.scopes as { id, title, expectedOutcome, outcomeSource, answerId };
77
- a split you are unsure of is an assumption.
83
+ a split you are unsure of is an assumption. Trace the data the request touches (decision 54):
84
+ every producer, consumer and contract owner, each with the repository that holds it. Put them
85
+ in result.dataFlow as { data, role, owner, repository }. A repository that is not in this
86
+ session is a blocking question in this round: ask to add it, so no consumer turns up after
87
+ the design is set.
78
88
  - id: perspectives
79
89
  type: parallel
80
90
  steps:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@digital-agora/friday",
3
- "version": "0.9.0",
3
+ "version": "0.10.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",
@@ -12,6 +12,12 @@ properties:
12
12
  id: { type: string, pattern: "^[a-z][a-z0-9-]{1,40}$" }
13
13
  name: { type: string }
14
14
  version: { type: string, pattern: "^\\d+\\.\\d+\\.\\d+$" }
15
+ extends:
16
+ description: >-
17
+ Specializations this one builds on (decision 53): folders relative to this one, or package
18
+ names resolved from it. Each is applied before this one, once, so this one wins over them.
19
+ type: array
20
+ items: { type: string }
15
21
  description:
16
22
  type: string
17
23
  description: Replaces the pack's description in the bundles built with this specialization.