sdd-engine 0.0.0-stage → 0.1.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 (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +165 -2
  3. package/dist/engine/cli.js +95 -0
  4. package/dist/engine/simulate.js +214 -0
  5. package/dist/judge/conversation.js +45 -0
  6. package/dist/judge/judge.js +122 -0
  7. package/dist/judge/outcome.js +42 -0
  8. package/dist/judge/regrade.js +74 -0
  9. package/dist/pipeline/agent.js +78 -0
  10. package/dist/pipeline/agentstage.js +88 -0
  11. package/dist/pipeline/approve.js +68 -0
  12. package/dist/pipeline/cli.js +261 -0
  13. package/dist/pipeline/derive.js +287 -0
  14. package/dist/pipeline/designloop.js +385 -0
  15. package/dist/pipeline/facts.js +108 -0
  16. package/dist/pipeline/mock.js +253 -0
  17. package/dist/pipeline/project.js +79 -0
  18. package/dist/pipeline/render.js +95 -0
  19. package/dist/pipeline/spec.js +272 -0
  20. package/dist/pipeline/try.js +162 -0
  21. package/dist/runner/batch-lib.js +157 -0
  22. package/dist/runner/batch.js +56 -0
  23. package/dist/runner/cli.js +61 -0
  24. package/dist/runner/llm/claude-code.js +123 -0
  25. package/dist/runner/llm/index.js +12 -0
  26. package/dist/runner/llm/types.js +17 -0
  27. package/dist/runner/reader/answer.js +76 -0
  28. package/dist/runner/reader/extract.js +106 -0
  29. package/dist/runner/reader/run.js +111 -0
  30. package/dist/runner/reader/skim.js +115 -0
  31. package/dist/runner/rng.js +22 -0
  32. package/dist/runner/sandbox/cli.js +60 -0
  33. package/dist/runner/sandbox/sandbox.js +144 -0
  34. package/dist/runner/sandbox/server.js +64 -0
  35. package/dist/runner/spec.js +84 -0
  36. package/dist/runner/talker/decide.js +110 -0
  37. package/dist/runner/talker/run.js +159 -0
  38. package/dist/runner/talker/world.js +36 -0
  39. package/dist/runner/trace.js +130 -0
  40. package/dist/runner/visitor/decide.js +159 -0
  41. package/dist/runner/visitor/observe.js +102 -0
  42. package/dist/runner/visitor/run.js +296 -0
  43. package/dist/scorer/compare.js +119 -0
  44. package/dist/scorer/score.js +201 -0
  45. package/dist/scorer/spot-check-compare.js +41 -0
  46. package/dist/scorer/spot-check-view.js +45 -0
  47. package/dist/scorer/stats.js +45 -0
  48. package/dist/scorer/summary.js +62 -0
  49. package/package.json +49 -4
@@ -0,0 +1,253 @@
1
+ // Step 4, the design side: a designer that writes cheap static mocks, and the
2
+ // guardrails every mock has to clear before it is scored.
3
+ //
4
+ // The designer is one model call with no tools. It is handed the brief as
5
+ // text and returns HTML. It cannot open a file, so it cannot read the
6
+ // held-back people or touch the referee, whatever it is told.
7
+ //
8
+ // The guardrails are the owner's rules and nothing more: true claims only,
9
+ // each one from the repository; no em dashes; links stay in the owner's own
10
+ // places. Outside requests are blocked when visitors see the page.
11
+ import { readFile, rm } from 'node:fs/promises';
12
+ import path from 'node:path';
13
+ import { checkCitations } from "./facts.js";
14
+ /** What a designer may know: the result, the audience, the people it may see, what each stage asks, and the ledger. */
15
+ export function buildBrief(spec, ledger, places = ownPlaces(spec, ledger)) {
16
+ const working = spec.personas.filter((p) => !p.holdout);
17
+ const stage = (s) => {
18
+ if (s.kind === 'read') {
19
+ return `- Reading: ${s.goal} Visitors skim for ${s.timeBudgetSeconds} seconds on ${s.viewports.join(' and ')}, then answer from memory:\n${s.questions.map((q) => ` - ${q.ask}`).join('\n')}`;
20
+ }
21
+ if (s.kind === 'decide') {
22
+ const actions = [...s.success.leavesTo.map((a) => `a link to an address that includes ${a}`), ...s.success.clicks.map((c) => `a control labelled with "${c}"`)];
23
+ return `- Deciding: ${s.goal} Nobody asks them to act, and leaving is the default. It counts only if they use: ${actions.join('; ')}.`;
24
+ }
25
+ if (s.kind === 'agent') {
26
+ const shown = s.requests.filter((r) => !r.holdout);
27
+ return [
28
+ `- AI agents as visitors: ${s.goal} A developer asks their coding agent for something. The agent reads this page's whole text, with no layout or images, and replies to its developer. Developers ask things like:`,
29
+ ...shown.map((r) => ` - "${r.ask}" (${r.fits ? 'the product fits this' : 'the product does NOT fit this'})`),
30
+ ` When the product fits, it counts if the agent recommends it, says nothing false, and gets these right: ${s.required.join('; ')}.`,
31
+ ' When the product does not fit, it counts only if the agent does not recommend it. So say plainly what the product is not for. Other requests you are not shown are tried too.',
32
+ ].join('\n');
33
+ }
34
+ return `- Trying: ${s.goal} A developer at a terminal on a clean machine (${s.machine.preinstalled.join(', ')}; without: ${s.machine.notPresent.join(', ')}) gets only this page's text and follows it. It counts when: ${s.success.observable}`;
35
+ };
36
+ return [
37
+ '# The result wanted',
38
+ '',
39
+ spec.result,
40
+ '',
41
+ '# Who it is for',
42
+ '',
43
+ spec.audience.who,
44
+ '',
45
+ '# Some of the people who will arrive',
46
+ '',
47
+ ...working.map((p) => `- ${p.archetype}. Arrives from ${p.arrivalSource} having seen: "${p.arrivalSaw}". Hopes for: ${p.needs.join('; ')}. Doubts: ${p.objections.join('; ')}. Skips ${Math.round(p.skimRate * 100)}% of body text.`),
48
+ '',
49
+ 'Other people will arrive too. You are not told who they are.',
50
+ '',
51
+ '# What the page has to make happen',
52
+ '',
53
+ ...spec.stages.map(stage),
54
+ '',
55
+ '# What has been checked as true about the product',
56
+ '',
57
+ 'Each of these is cited to the repository. Prefer them. Anything else you say is checked against the repository before the page is scored.',
58
+ '',
59
+ ...ledger.facts.map((f) => `- ${f.claim}`),
60
+ '',
61
+ '# The owner\'s own places, the only ones you may link to',
62
+ '',
63
+ ...places.map((a) => `- ${a}`),
64
+ '',
65
+ '# Things you must not say, because they are false or not true yet',
66
+ '',
67
+ ...ledger.notTrue.map((n) => `- ${n.claim} (${n.why})`),
68
+ '',
69
+ ].join('\n');
70
+ }
71
+ const DESIGNER_SYSTEM = `You design one static web page. It is a cheap stand-in used to test an idea before anything real is built.
72
+
73
+ What you return
74
+ - One complete HTML document, with its CSS in a <style> element.
75
+ - It must work on a phone and on a desktop.
76
+ - When visitors see the page, every request to anywhere outside it is blocked. Anything you load from elsewhere (a font, an image, a script) will simply not appear, so the page has to stand without it.
77
+
78
+ How it is judged
79
+ - Simulated visitors skim it. They take in headings and the first words of things, skip much of the body text, and leave when nothing speaks to why they came. Then they are asked questions from memory, or they decide on their own whether to act, or a developer follows the page's instructions at a terminal on a clean machine, or an AI agent reads the whole text for its developer.
80
+ - Put what matters where a skimmer's eye lands. Say the true thing plainly. Do not repeat the same sentence in several places, and do not stuff headings.
81
+
82
+ The owner's rules. Breaking one fails the page whatever it scores.
83
+ - True claims only. Every statement about the product comes from its repository. The brief lists what has been checked so far; anything you say beyond it is checked against the repository, and the page is thrown out if the repository does not support it. No invented features, numbers, quotes or users.
84
+ - Nothing from the list of things you must not say.
85
+ - No em dashes anywhere.
86
+ - Links stay in the owner's own places, which the brief lists. Do not link anywhere else.`;
87
+ export async function designMock(llm, input) {
88
+ const parts = [input.brief];
89
+ if (input.previous) {
90
+ parts.push('# The page as it stands', '', '```html', input.previous.html, '```', '', '# What happened when visitors tried it', '', input.previous.findings, '', 'Revise the page so that more of these visitors get there.', 'Change as little as you can. For every question that already meets what it needs, keep the words that answer it exactly as they are and where they are: do not reword them, shorten them or move them further down. Change only what the findings point at for the questions that fall short. A skimmer holds only a few things, so do not win one answer by burying another.');
91
+ }
92
+ else {
93
+ parts.push('Design the first version of the page.');
94
+ }
95
+ if (input.rejected?.length) {
96
+ parts.push('', '# Your last attempt was thrown out before it was scored', '', ...input.rejected.map((r) => `- ${r}`), '', 'Fix every one of these.');
97
+ }
98
+ const response = await llm.complete({
99
+ role: 'reviser',
100
+ system: DESIGNER_SYSTEM,
101
+ prompt: parts.join('\n'),
102
+ schema: {
103
+ type: 'object',
104
+ properties: {
105
+ html: { type: 'string', description: 'The complete HTML document.' },
106
+ notes: { type: 'string', description: 'Two or three lines: what you did and why.' },
107
+ },
108
+ required: ['html', 'notes'],
109
+ additionalProperties: false,
110
+ },
111
+ });
112
+ const out = response.structured;
113
+ if (!out?.html || !/<html[\s>]/i.test(out.html))
114
+ throw new Error('The designer did not return an HTML document.');
115
+ return { html: out.html, notes: out.notes ?? '', costUsd: response.costUsd };
116
+ }
117
+ // ---- Guardrails ----
118
+ /** The words a visitor could read: tags, styles and scripts removed. */
119
+ export function visibleText(html) {
120
+ return html
121
+ .replace(/<(style|script|noscript|template)[\s\S]*?<\/\1>/gi, ' ')
122
+ .replace(/<!--[\s\S]*?-->/g, ' ')
123
+ .replace(/<(br|\/p|\/div|\/h[1-6]|\/li|\/section|\/tr|\/pre)[^>]*>/gi, '\n')
124
+ .replace(/<[^>]+>/g, ' ')
125
+ .replace(/&nbsp;/g, ' ').replace(/&middot;/g, '·').replace(/&mdash;/g, '—').replace(/&ndash;/g, '–').replace(/&rarr;/g, '→').replace(/&copy;/g, '©').replace(/&#(\d+);/g, (_m, n) => String.fromCodePoint(Number(n))).replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
126
+ .replace(/[ \t]+/g, ' ')
127
+ .split('\n').map((line) => line.trim()).filter((line) => line.length > 0).join('\n');
128
+ }
129
+ /**
130
+ * The owner's own places, which a page may link to: any they named, the addresses
131
+ * the decide stage counts, and addresses that appear in the ledger.
132
+ */
133
+ export function ownPlaces(spec, ledger, named = []) {
134
+ const fromStages = spec.stages.flatMap((s) => (s.kind === 'decide' ? s.success.leavesTo : []));
135
+ const fromLedger = ledger.facts.flatMap((f) => [...`${f.claim} ${f.source.kind === 'file' ? f.source.quote : f.source.reading}`.matchAll(/https?:\/\/[^\s"'<>)]+/g)].map((m) => m[0].replace(/^https?:\/\//, '').replace(/[.,]$/, '')));
136
+ return [...new Set([...named, ...fromStages, ...fromLedger])];
137
+ }
138
+ /**
139
+ * The owner's rules that plain code can check: no em dashes, and links stay in
140
+ * the owner's own places. An empty list means the page goes on to the claims review.
141
+ * Outside files are not a failure here. They are blocked when visitors see the page.
142
+ */
143
+ export function mechanicalProblems(html, places) {
144
+ const problems = [];
145
+ if (html.includes('—'))
146
+ problems.push('The page contains an em dash.');
147
+ for (const m of html.matchAll(/<a\b[^>]*\bhref=["']([^"']+)["']/gi)) {
148
+ const href = m[1];
149
+ if (!/^https?:\/\//i.test(href))
150
+ continue;
151
+ // "www." is not a different place, and a path under one of the owner's places is still theirs.
152
+ const bare = href.replace(/^https?:\/\//i, '').replace(/^www\./i, '').toLowerCase();
153
+ if (!places.some((a) => bare.startsWith(a.replace(/^https?:\/\//i, '').replace(/^www\./i, '').toLowerCase())))
154
+ problems.push(`The page links to ${href}, which is outside the owner's own places (${places.join(', ')}).`);
155
+ }
156
+ return [...new Set(problems)];
157
+ }
158
+ const CLAIMS_SYSTEM = `You check a web page against a ledger of true statements about a product.
159
+
160
+ Go through what the page says about the product: what it is, what it does, what it needs, what it costs, numbers, comparisons, who uses it, and every command it tells a visitor to run.
161
+ - A statement passes if the ledger supports it. Rewording, summarising and leaving things out are fine.
162
+ - A statement fails if the ledger does not support it, if it goes further than the ledger does, or if it matches something on the "not true" list.
163
+ - Ordinary page furniture is not a claim: headings like "How it works", calls to action, the visitor's own situation.
164
+ Report only failures. Quote the page's words exactly.`;
165
+ /** The claims review: does the page say anything about the product that the ledger does not support? */
166
+ export async function reviewClaims(llm, html, ledger, alsoTrue = []) {
167
+ const response = await llm.complete({
168
+ role: 'judge',
169
+ system: CLAIMS_SYSTEM,
170
+ prompt: [
171
+ '# True statements', '', ...ledger.facts.map((f) => `- ${f.claim}`), ...alsoTrue.map((c) => `- ${c}`), '',
172
+ '# Not true', '', ...ledger.notTrue.map((n) => `- ${n.claim} (${n.why})`), '',
173
+ '# The page, as a visitor reads it', '', visibleText(html),
174
+ ].join('\n'),
175
+ schema: {
176
+ type: 'object',
177
+ properties: {
178
+ violations: {
179
+ type: 'array',
180
+ items: { type: 'object', properties: { statement: { type: 'string' }, why: { type: 'string' } }, required: ['statement', 'why'], additionalProperties: false },
181
+ },
182
+ },
183
+ required: ['violations'],
184
+ additionalProperties: false,
185
+ },
186
+ });
187
+ const out = response.structured;
188
+ return { violations: out?.violations ?? [], costUsd: response.costUsd };
189
+ }
190
+ // ---- Checking a statement against the repository itself ----
191
+ const VERIFY_TOOLS = ['Read', 'Glob', 'Grep', 'Write'];
192
+ export const VERIFIED_FILE = 'verified.json';
193
+ /**
194
+ * The owner's rule is that every statement comes from the repository, not that it
195
+ * appears on a list someone wrote earlier. So a statement the ledger does not cover
196
+ * gets looked up in the repository by a session that can read it. A statement
197
+ * counts as supported only if it comes back with a file, a line and a quote, and
198
+ * code then finds that quote at that place. Anything on the "not true" list stays out.
199
+ */
200
+ export async function checkAgainstRepo(agent, violations, ledger, sourceDirs, scratch, budgetUsd) {
201
+ if (violations.length === 0 || sourceDirs.length === 0)
202
+ return { supported: [], unsupported: violations, costUsd: 0 };
203
+ await rm(path.join(scratch, VERIFIED_FILE), { force: true });
204
+ const run = await agent.run({
205
+ name: 'claims checker',
206
+ cwd: scratch,
207
+ addDirs: sourceDirs,
208
+ tools: VERIFY_TOOLS,
209
+ budgetUsd,
210
+ prompt: [
211
+ 'A web page about a product makes the statements below. A first review could not match them to a list of checked facts. Your job is to find out, from the product\'s own repository, whether each one is true.',
212
+ '',
213
+ `The repository is at: ${sourceDirs.join(', ')}. Read the code and the docs. Code wins over docs when they disagree.`,
214
+ '',
215
+ 'For each statement decide:',
216
+ '- supported: the repository shows it is true, with no stretch. Give the file (relative to the repository), the line number, and an exact quote of 8 or more characters copied from that line or the lines right next to it, and a one-sentence plain claim that says only what that code or text shows.',
217
+ '- not supported: the repository does not show it, shows only part of it, or shows the opposite. Say why in one line.',
218
+ 'A number, a quote from a person, a customer or a comparison with another product is supported only if the repository itself contains it. Be strict: when unsure, it is not supported.',
219
+ '',
220
+ 'These are known to be false or not true yet. Any statement that says one of them is not supported, whatever else you find:',
221
+ ...ledger.notTrue.map((n) => `- ${n.claim} (${n.why})`),
222
+ '',
223
+ '# The statements',
224
+ '',
225
+ ...violations.map((v, i) => `${i + 1}. "${v.statement}" (first review: ${v.why})`),
226
+ '',
227
+ `Write your answer to the file ${VERIFIED_FILE} in the current folder, as JSON in this shape, one entry per statement in the same order:`,
228
+ '[ { "n": 1, "supported": true, "claim": "...", "file": "src/x.ts", "line": 12, "quote": "..." }, { "n": 2, "supported": false, "why": "..." } ]',
229
+ ].join('\n'),
230
+ });
231
+ let answers = [];
232
+ try {
233
+ answers = JSON.parse(await readFile(path.join(scratch, VERIFIED_FILE), 'utf8'));
234
+ }
235
+ catch { /* no usable answer: everything stays a violation */ }
236
+ const supported = [];
237
+ const unsupported = [];
238
+ for (const [i, v] of violations.entries()) {
239
+ const a = Array.isArray(answers) ? answers.find((x) => x?.n === i + 1) : undefined;
240
+ if (a?.supported === true && typeof a.file === 'string' && typeof a.line === 'number' && typeof a.quote === 'string' && a.quote.trim().length >= 8 && typeof a.claim === 'string') {
241
+ // The session's word is not enough. Code looks for the quote where it says it is.
242
+ const problems = await checkCitations({ schema: ledger.schema, facts: [{ id: `checked-${i + 1}`, claim: a.claim, source: { kind: 'file', file: a.file, line: a.line, quote: a.quote } }], notTrue: [] }, sourceDirs);
243
+ if (problems.length === 0) {
244
+ supported.push({ statement: v.statement, claim: a.claim, file: a.file, line: a.line, quote: a.quote });
245
+ continue;
246
+ }
247
+ unsupported.push({ statement: v.statement, why: `${v.why} A citation was offered but did not check out: ${problems[0]}` });
248
+ continue;
249
+ }
250
+ unsupported.push({ statement: v.statement, why: a?.why ? `${v.why} Checked against the repository: ${a.why}` : v.why });
251
+ }
252
+ return { supported, unsupported, costUsd: run.costUsd };
253
+ }
@@ -0,0 +1,79 @@
1
+ // A pipeline project: one result, and everything derived from it.
2
+ //
3
+ // The folder is split by who may touch what. The split is the rule that keeps
4
+ // the simulation honest: whoever designs or builds must never be able to edit
5
+ // the referee or read the held-back personas.
6
+ //
7
+ // <project>/
8
+ // referee/ result.txt, spec.yaml, personas/working, personas/holdout
9
+ // Written only by the deriver. Never shown to a designer or builder.
10
+ // brief/ facts.yaml (the claims ledger) and, later, working-set results.
11
+ // The only thing a designer or builder is given.
12
+ // design/ mocks, one folder per iteration.
13
+ // evidence/ traces, reports and the cost log. Written by the engine and the pipeline.
14
+ // scratch/ where an agent session runs. Emptied before each session.
15
+ // derived-spec.md the spec in plain language, for the owner to approve.
16
+ import { createHash } from 'node:crypto';
17
+ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
18
+ import { homedir } from 'node:os';
19
+ import path from 'node:path';
20
+ /** Where projects live: outside any repository. Override with SDD_HOME. */
21
+ export function projectsRoot(env = process.env) {
22
+ return path.join(env.SDD_HOME?.trim() || path.join(homedir(), '.sdd'), 'projects');
23
+ }
24
+ /** A readable, stable id: the first words of the result, plus a hash of all of it. */
25
+ export function projectId(result) {
26
+ const words = result.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().split(' ').filter((w) => w.length > 2).slice(0, 5).join('-');
27
+ const hash = createHash('sha256').update(result.trim()).digest('hex').slice(0, 8);
28
+ return `${words || 'project'}-${hash}`.slice(0, 60);
29
+ }
30
+ export function layout(root) {
31
+ const referee = path.join(root, 'referee');
32
+ const brief = path.join(root, 'brief');
33
+ const evidence = path.join(root, 'evidence');
34
+ return {
35
+ root,
36
+ referee,
37
+ brief,
38
+ design: path.join(root, 'design'),
39
+ evidence,
40
+ scratch: path.join(root, 'scratch'),
41
+ resultFile: path.join(referee, 'result.txt'),
42
+ specFile: path.join(referee, 'spec.yaml'),
43
+ personasWorking: path.join(referee, 'personas', 'working'),
44
+ personasHoldout: path.join(referee, 'personas', 'holdout'),
45
+ factsFile: path.join(brief, 'facts.yaml'),
46
+ costLog: path.join(evidence, 'cost.jsonl'),
47
+ derivedSpec: path.join(root, 'derived-spec.md'),
48
+ };
49
+ }
50
+ export async function createProject(root) {
51
+ const l = layout(root);
52
+ for (const dir of [l.referee, l.brief, l.design, l.evidence, l.scratch])
53
+ await mkdir(dir, { recursive: true });
54
+ return l;
55
+ }
56
+ /** A fresh, empty folder for one agent session. */
57
+ export async function freshScratch(l, name) {
58
+ const dir = path.join(l.scratch, name);
59
+ await rm(dir, { recursive: true, force: true });
60
+ await mkdir(dir, { recursive: true });
61
+ return dir;
62
+ }
63
+ /** Every run's cost is appended here. Nothing is ever rewritten. */
64
+ export async function logCost(l, entry) {
65
+ await mkdir(l.evidence, { recursive: true });
66
+ await writeFile(l.costLog, JSON.stringify({ at: new Date().toISOString(), ...entry }) + '\n', { flag: 'a' });
67
+ }
68
+ export async function readCosts(l) {
69
+ const text = await readFile(l.costLog, 'utf8').catch(() => '');
70
+ return text.split('\n').filter((line) => line.trim()).map((line) => JSON.parse(line));
71
+ }
72
+ export async function spentUsd(l) {
73
+ return (await readCosts(l)).reduce((sum, e) => sum + e.usd, 0);
74
+ }
75
+ /** True when `file` is inside `dir`. Used to refuse writes that cross the split. */
76
+ export function isInside(dir, file) {
77
+ const rel = path.relative(path.resolve(dir), path.resolve(file));
78
+ return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
79
+ }
@@ -0,0 +1,95 @@
1
+ // The derived spec in plain language, for the owner to read and approve.
2
+ // Everything in it comes from the checked spec and ledger. Nothing is scored
3
+ // here, and the page says so.
4
+ const pct = (x) => `${Math.round(x * 100)}%`;
5
+ function persona(p) {
6
+ return [
7
+ `**${p.id}**${p.holdout ? ' (held back)' : ''}: ${p.archetype}`,
8
+ ` - ${p.role}. ${p.experience}`,
9
+ ` - Already uses: ${p.alreadyUses.join(', ')}`,
10
+ ` - Arrives from ${p.arrivalSource}, having seen: "${p.arrivalSaw}"`,
11
+ ` - Hopes for: ${p.needs.join('; ')}`,
12
+ ` - Doubts: ${p.objections.join('; ')}`,
13
+ ` - Reads at ${p.readingWpm} words a minute and skips ${pct(p.skimRate)} of body text`,
14
+ ].join('\n');
15
+ }
16
+ function stage(s, n) {
17
+ const lines = [];
18
+ if (s.kind === 'read') {
19
+ lines.push(`### Stage ${n}: ${s.id} (reading)`, '', s.goal, '');
20
+ lines.push(`Each person arrives from ${s.entryFrom}, skims for ${s.timeBudgetSeconds} seconds on ${s.viewports.join(' and ')}, then the page is taken away and they answer from memory.`, '');
21
+ lines.push('| Question | A passing answer states | Must pass | Why |', '|---|---|---|---|');
22
+ for (const q of s.questions)
23
+ lines.push(`| ${q.ask} | ${q.required.join('<br>')} | ${pct(q.threshold)} | ${q.reason} |`);
24
+ }
25
+ else if (s.kind === 'decide') {
26
+ lines.push(`### Stage ${n}: ${s.id} (deciding)`, '', s.goal, '');
27
+ lines.push(`Nobody asks them to do anything. They arrive from ${s.entryFrom} on ${s.viewports.join(' and ')}, have ${s.patienceSeconds} seconds of patience, and leaving is the default.`, '');
28
+ lines.push('It counts when a person does any one of these:');
29
+ for (const a of s.success.leavesTo)
30
+ lines.push(`- follows a link to an address that includes \`${a}\``);
31
+ for (const c of s.success.clicks)
32
+ lines.push(`- presses a control whose label includes "${c}"`);
33
+ lines.push('', `**Must succeed: ${pct(s.threshold)}.** ${s.reason}`);
34
+ }
35
+ else if (s.kind === 'agent') {
36
+ lines.push(`### Stage ${n}: ${s.id} (an AI agent is the visitor)`, '', s.goal, '');
37
+ lines.push('A developer asks their coding agent for something. The agent reads the whole page as text, with no layout, images or time limit, and replies to its developer. A judge grades the reply.', '');
38
+ lines.push('| The developer asks | Is the product a fit? | Shown to the designer? |', '|---|---|---|');
39
+ for (const r of s.requests)
40
+ lines.push(`| ${r.ask} | ${r.fits ? 'yes' : 'no'} | ${r.holdout ? 'no, held back' : 'yes'} |`);
41
+ lines.push('', 'When the product fits, it counts if the agent recommends it, says nothing the ledger does not support, and gets these right:');
42
+ for (const r of s.required)
43
+ lines.push(`- ${r}`);
44
+ lines.push('', 'When the product does not fit, it counts only if the agent does not recommend it. A page that oversells scores worse.');
45
+ lines.push('', `**Must succeed: ${pct(s.threshold)}.** ${s.reason}`);
46
+ }
47
+ else {
48
+ lines.push(`### Stage ${n}: ${s.id} (trying, in a terminal)`, '', s.goal, '');
49
+ lines.push(`- Machine: \`${s.machine.image}\``);
50
+ lines.push(`- Already installed: ${s.machine.preinstalled.join(', ') || 'nothing'}`);
51
+ lines.push(`- Deliberately absent: ${s.machine.notPresent.join(', ') || 'nothing'}`);
52
+ lines.push(`- The agent is given: ${s.given}`);
53
+ lines.push(`- It counts when: ${s.success.observable}`);
54
+ lines.push(`- How that is seen: ${s.success.check}`);
55
+ lines.push(`- Time limit: ${s.timeLimitSeconds} seconds`);
56
+ lines.push('', `**Must succeed: ${pct(s.threshold)}.** ${s.reason}`);
57
+ }
58
+ return lines.join('\n');
59
+ }
60
+ function assumption(a) {
61
+ const value = `${a.value}${a.unit ? ` ${a.unit}` : ''}`;
62
+ return `| ${a.statement} | ${value} | ${a.source} | ${a.how} | ${a.sweep.join(', ')} | ${a.affects.join(', ')} |`;
63
+ }
64
+ export function renderDerivedSpec(spec, ledger, run) {
65
+ const working = spec.personas.filter((p) => !p.holdout);
66
+ const holdout = spec.personas.filter((p) => p.holdout);
67
+ const fileFacts = ledger.facts.filter((f) => f.source.kind === 'file').length;
68
+ const out = [];
69
+ out.push('# Derived spec', '');
70
+ out.push(`> ${spec.result}`, '');
71
+ out.push('This is what the sentence above was turned into. Nothing here has been simulated or scored: every score is **not run**. Read it, correct it, and approve it before anything is designed.', '');
72
+ out.push('## Who it is for', '', spec.audience.who, '', 'Inferred from:', ...spec.audience.inferredFrom.map((s) => `- ${s}`), '');
73
+ out.push(`## The people (${working.length} seen by the designer, ${holdout.length} held back)`, '');
74
+ out.push('Held-back people are never shown to whoever designs or builds. They check that the result works for people it was not tuned for.', '');
75
+ out.push(...working.map(persona), '', ...holdout.map(persona), '');
76
+ out.push('## What has to happen, in order', '');
77
+ spec.stages.forEach((s, i) => out.push(stage(s, i + 1), ''));
78
+ out.push('## What the simulation takes as given', '');
79
+ out.push('"measured" means the deriver ran something and this is the reading. "assumed" means it could not check. The sweep is the range that will be tried to find where scores break.', '');
80
+ out.push('| Assumption | Value | Source | How | Sweep | Affects |', '|---|---|---|---|---|---|');
81
+ out.push(...spec.assumptions.map(assumption), '');
82
+ out.push('## What a page is allowed to say', '');
83
+ out.push(`The ledger holds ${ledger.facts.length} statements about the product, ${fileFacts} quoted from files (each quote checked against the file) and ${ledger.facts.length - fileFacts} measured or looked up. A design that says anything else about the product fails, whatever it scores.`, '');
84
+ if (ledger.notTrue.length > 0) {
85
+ out.push('Things a page would be tempted to say that are not true, or not true yet:', '');
86
+ out.push(...ledger.notTrue.map((n) => `- **${n.claim}** ${n.why}`), '');
87
+ }
88
+ out.push('## Questions only you can answer', '');
89
+ out.push(...(spec.openQuestions.length > 0 ? spec.openQuestions.map((q) => `- ${q}`) : ['- None.']), '');
90
+ out.push('## This step', '');
91
+ out.push(`- Looked at: ${run.sources.join(', ') || 'no sources given'}`);
92
+ out.push(`- Cost of deriving, at list prices: $${run.costUsd.toFixed(2)}`);
93
+ out.push('- Simulated: not run. Built: not run.', '');
94
+ return out.join('\n');
95
+ }