@ogygie/studio 0.26.0 → 0.28.0

package/dist/server.js

@@ -826,6 +826,15 @@ function compositionOfSpec(content) {
   const section = next === null ? rest : rest.slice(0, next.index);
   return COMPOSITION_LINE.exec(section)?.[1] ?? null;
 }
+var ASSUMPTIONS_SECTION_TITLE = "Hypoth\xE8ses";
+function assumptionsOfSpec(content) {
+  const heading = new RegExp(`^# ${ASSUMPTIONS_SECTION_TITLE}\\s*$`, "mu").exec(content);
+  if (heading === null) return [];
+  const rest = content.slice(heading.index + heading[0].length);
+  const next = /^# /mu.exec(rest);
+  const section = next === null ? rest : rest.slice(0, next.index);
+  return section.split("\n").map((line) => line.trim()).filter((line) => /^[-*]\s+\S/u.test(line)).map((line) => line.replace(/^[-*]\s+/u, "").trim());
+}
 
 // ../ogygie-core/src/proposal.ts
 var DECISION_FILES = ["DECISIONS.md", "DECISIONS.product.md"];
@@ -1326,6 +1335,16 @@ function parseSpec(filePath, fileName, content) {
   }
   return { ok: true, spec: { frontmatter: checked.data, body: split.body } };
 }
+function intentOf(body) {
+  const heading = /^# @intent\s*$/mu.exec(body);
+  if (heading === null) return "";
+  const rest = body.slice(heading.index + heading[0].length);
+  const next = /^# /mu.exec(rest);
+  const section = (next === null ? rest : rest.slice(0, next.index)).trim();
+  const paragraph = section.split(/\n\s*\n/u)[0]?.replace(/\s+/gu, " ").trim() ?? "";
+  const sentence = /^.*?[.!?](?:\s|$)/u.exec(paragraph)?.[0]?.trim() ?? paragraph;
+  return sentence.length > 160 ? `${sentence.slice(0, 157).trimEnd()}\u2026` : sentence;
+}
 function toReadableSummary(filePath, spec) {
   return {
     id: spec.frontmatter.id,
@@ -1333,7 +1352,8 @@ function toReadableSummary(filePath, spec) {
     priority: spec.frontmatter.priority,
     depends_on: spec.frontmatter.depends_on,
     filePath,
-    presentSections: presentSectionsOf(spec.body)
+    presentSections: presentSectionsOf(spec.body),
+    intent: intentOf(spec.body)
   };
 }
 async function listSpecFileNames(deps) {
@@ -1540,7 +1560,9 @@ var ReadableSpecSummarySchema = z6.object({
   priority: SpecFrontmatterSchema.shape.priority,
   depends_on: z6.array(FeatureNameSchema),
   filePath: z6.string(),
-  presentSections: z6.array(z6.string())
+  presentSections: z6.array(z6.string()),
+  /** The first sentence of `# @intent`, for a list that reads (v1.20: the target-spec suggestions of the brief). */
+  intent: z6.string().default("")
 });
 var UnreadableSpecSummarySchema = z6.object({
   id: z6.string(),
@@ -1584,16 +1606,31 @@ var BriefAttachmentSchema = z6.object({
   name: z6.string().min(1).max(200),
   contentBase64: z6.string().min(1).max(57e5)
 });
+var BriefAnswerSchema = z6.object({ questionId: FeatureNameSchema, answer: z6.string().min(1).max(2e3) });
 var BriefInputSchema = z6.object({
   brief: z6.string().min(50).max(2e4),
   /** Absent: the model names the new spec. Present and existing: an amendment. */
   specId: FeatureNameSchema.optional(),
   /** The client's material — a mock-up, a workbook, a document; five at most, formats md, txt, csv, json, html, xlsx, pdf. */
-  attachments: z6.array(BriefAttachmentSchema).max(5).default([])
+  attachments: z6.array(BriefAttachmentSchema).max(5).default([]),
+  /** D57: the answers of the past rounds of questions, three rounds at most. */
+  answers: z6.array(BriefAnswerSchema).max(15).default([]),
+  /** D57: the round this send opens; at 3 the draft is asked without a question. */
+  round: z6.number().int().min(1).max(4).default(1),
+  /** D57: « Passer les questions » — the draft is asked, the unknown becomes an assumption. */
+  skipQuestions: z6.boolean().default(false)
+});
+var BriefQuestionSchema = z6.object({
+  /** kebab-case, stable from one read to the next. */
+  id: FeatureNameSchema,
+  text: z6.string().min(1),
+  /** The proposed answers; a free answer is always possible. */
+  options: z6.array(z6.string().min(1)).min(2).max(4)
 });
 var BriefOutputSchema = z6.object({
   specId: FeatureNameSchema,
-  attempts: z6.number().int().min(1).max(2),
+  /** 1 when the first draft passed; up to 4 when the model corrected itself and a refused round of questions cost a turn (D57). */
+  attempts: z6.number().int().min(1).max(4),
   problemsFixed: z6.array(z6.string()),
   /** No feature of the manifest carries this id: its first schemas.ts awaits the operator (D52, lot C). */
   isNewFeature: z6.boolean(),
@@ -1602,10 +1639,30 @@ var BriefOutputSchema = z6.object({
   compositions: z6.array(z6.string()).default([]),
   /** The generator's tally on the draft's `# Génération` block (lines bound without a model, lines carried by a hole); null without a block. */
   generation: z6.object({ derivable: z6.number().int().nonnegative(), hole: z6.number().int().nonnegative() }).nullable().default(null),
+  /** D57: the points the model decided that the brief did not say — the `# Hypothèses` lines of the draft. */
+  assumptions: z6.array(z6.string()).default([]),
   usage: z6.array(
     z6.object({ model: z6.string(), inputTokens: z6.number().int().nonnegative(), outputTokens: z6.number().int().nonnegative() })
   )
 });
+var BriefStartOutputSchema = z6.object({ jobId: z6.string() });
+var BriefStageSchema = z6.enum(["questions", "drafting", "judging", "compositions", "writing", "done", "failed"]);
+var BriefJobSchema = z6.object({
+  jobId: z6.string(),
+  stage: BriefStageSchema,
+  /** On questions: the round in progress. */
+  round: z6.number().int().min(1).max(3).optional(),
+  /** On drafting / judging: the attempt. */
+  attempt: z6.number().int().min(1).max(4).optional(),
+  /** On compositions: k of N. */
+  composition: z6.object({ done: z6.number().int().nonnegative(), total: z6.number().int().nonnegative() }).optional(),
+  elapsedMs: z6.number().int().nonnegative(),
+  /** The P95 of B3: 90 000 ms. */
+  budgetMs: z6.number().int().positive(),
+  questions: z6.array(BriefQuestionSchema).min(3).max(5).optional(),
+  result: BriefOutputSchema.optional(),
+  error: OgygieErrorSchema.optional()
+});
 var ChecksStateSchema = z6.enum(["green", "red", "pending", "none"]);
 var PullRequestStatusSchema = z6.object({
   specId: FeatureNameSchema,
@@ -1648,6 +1705,26 @@ var EnvironmentsStatusSchema = z6.object({
   /** release/<date>.<n>, most recent first. */
   releases: z6.array(z6.string())
 });
+var EnvironmentReadParamsSchema = z6.object({ environment: EnvironmentNameSchema });
+var CommitReachSchema = z6.enum(["deployed", "forward", "backward", "unreachable"]);
+var EnvironmentCommitSchema = z6.object({
+  sha: z6.string(),
+  /** The first line of the message without its `spec: merge` prefix and its `(#n)` suffix. */
+  title: z6.string(),
+  specId: FeatureNameSchema.nullable(),
+  author: z6.string(),
+  authoredAt: z6.string(),
+  releaseTag: z6.string().nullable(),
+  reach: CommitReachSchema,
+  /** The reason, in the client's language. */
+  why: z6.string()
+});
+var EnvironmentCommitsSchema = z6.object({
+  environment: EnvironmentNameSchema,
+  ref: z6.string(),
+  deployedSha: z6.string().nullable(),
+  commits: z6.array(EnvironmentCommitSchema).max(30)
+});
 var PromotionInputSchema = z6.object({
   sha: z6.string().regex(/^[0-9a-f]{40}$/),
   /** Operator only: a step back, forced, with its reason. */
@@ -2031,6 +2108,9 @@ ${link}
   });
 }
 
+// src/server/hosted/brief-routes.ts
+import { z as z10 } from "zod";
+
 // src/server/hosted/attachments.ts
 import { createHash } from "node:crypto";
 import { inflateRawSync } from "node:zlib";
@@ -2276,6 +2356,9 @@ var MAX_COMPOSITIONS = 3;
 var COMPOSITION_SEPARATOR = "=== COMPOSITION ===";
 var DERIVED_BRIEF_MAX = 6e3;
 var BRIEF_IN_MESSAGE_MAX = 2e3;
+var MAX_QUESTION_ROUNDS = 3;
+var QUESTIONS_MARKER = /^\s*QUESTIONS\s*$/mu;
+var NO_MORE_QUESTIONS = "no more questions: write the draft now, and put what you do not know under # Hypoth\xE8ses";
 async function readIfPresent(storage, path) {
   return await storage.exists(path) ? storage.readFile(path) : null;
 }
@@ -2339,6 +2422,25 @@ async function existingSpecIds(storage) {
   const entries = await storage.listDirectory("specs");
   return entries.map((entry) => entry.path).filter((path) => !path.includes("/") && path.endsWith(".spec.md") && !path.startsWith("_")).map((path) => path.replace(/\.spec\.md$/, "")).sort();
 }
+function extractQuestions(text) {
+  const marker = QUESTIONS_MARKER.exec(text);
+  if (marker === null) return null;
+  const raw = text.slice(marker.index + marker[0].length).replace(/^\s*```(?:json)?\s*/u, "").replace(/\s*```\s*$/u, "").trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { problem: "QUESTIONS: the JSON after the marker does not parse" };
+  }
+  const shape = z9.object({
+    questions: z9.array(z9.object({ id: FeatureNameSchema, text: z9.string().trim().min(1), options: z9.array(z9.string().trim().min(1)).min(2).max(4) })).min(3).max(5)
+  });
+  const checked = shape.safeParse(parsed);
+  if (!checked.success) return { problem: `QUESTIONS: ${checked.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(" ; ")}` };
+  const ids = new Set(checked.data.questions.map((question) => question.id));
+  if (ids.size !== checked.data.questions.length) return { problem: "QUESTIONS: two questions share an id" };
+  return { questions: checked.data.questions };
+}
 function buildBriefPrompt(context) {
   const system = [
     "Tu r\xE9diges des SPECS de features pour un produit construit avec le framework Ogygie. Une spec est un contrat, relu et sign\xE9 par un humain non d\xE9veloppeur, puis impl\xE9ment\xE9 par une cha\xEEne de g\xE9n\xE9ration : tu \xE9cris pour ce lecteur, en fran\xE7ais, pr\xE9cis, sans jargon.",
@@ -2358,6 +2460,8 @@ function buildBriefPrompt(context) {
     "- Tu n'\xE9cris jamais de code ni de design (couleurs, composants) : la spec dit QUOI, jamais COMMENT. Le bloc YAML de `# G\xE9n\xE9ration` n'est pas du code : c'est la d\xE9claration que le g\xE9n\xE9rateur lit.",
     ...context.grammarCard === null || context.grammarCard === void 0 ? [] : ["- Quand la rubrique apporte des op\xE9rations ou un \xE9cran que le g\xE9n\xE9rateur sait d\xE9river, \xE9cris la section `# G\xE9n\xE9ration` apr\xE8s `# @intent` et ses `# Comportements` dans la grammaire ferm\xE9e (carte ci-dessous) : le brouillon est jug\xE9 par le v\xE9rificateur du g\xE9n\xE9rateur avant d'\xEAtre montr\xE9. Quand elle ne se g\xE9n\xE8re pas, n'\xE9cris pas la section."],
     "- Tu ne proposes jamais `status: validated` ni `implemented` : valider est le geste de l'humain.",
+    "- HYPOTH\xC8SES : quand tu tranches un point que le brief ne dit pas (un nombre, un ordre, un p\xE9rim\xE8tre, un mot), ajoute apr\xE8s `# Budget` (et avant `# Design` si elle existe) une section `# Hypoth\xE8ses`, une puce par choix, en fran\xE7ais, courte ; sans hypoth\xE8se, pas de section.",
+    '- QUESTIONS : quand la demande ci-dessous t\'y autorise et qu\'une r\xE9ponse du client CHANGERAIT la spec, tu peux, AU LIEU du fichier, r\xE9pondre par une ligne `QUESTIONS` seule puis un objet JSON `{"questions":[{"id":"kebab-case","text":"la question, en fran\xE7ais","options":["r\xE9ponse","r\xE9ponse"]}]}` \u2014 trois \xE0 cinq questions ferm\xE9es, deux \xE0 quatre options chacune, rien d\'autre avant ni apr\xE8s. Une question dont la r\xE9ponse ne changerait pas la spec ne se pose pas : elle devient une hypoth\xE8se.',
     "- Quand la rubrique est un \xC9CRAN (une page du tableau de bord), ajoute apr\xE8s `# Budget` une section `# Design` qui commence par une ligne `Composition : <nom-kebab>` (le nom de la disposition, ex. `liste-d-abord`), puis l'ordre des vues, le pattern du catalogue de chacune (liste, formulaire, \xE9tat vide\u2026) et les \xE9tats mis en avant \u2014 jamais une couleur, jamais un composant invent\xE9.",
     "",
     "GABARIT DU REPO (\xE0 respecter \xE0 la lettre) :",
@@ -2379,7 +2483,10 @@ function buildBriefPrompt(context) {
     ...context.existingSpec === null ? [] : ["SPEC EXISTANTE :", context.existingSpec, ""],
     "BRIEF :",
     context.brief.trim(),
-    ...attachmentsPromptSection(context.attachments ?? [])
+    ...attachmentsPromptSection(context.attachments ?? []),
+    ...(context.answers ?? []).length === 0 ? [] : ["", "R\xC9PONSES DU CLIENT \xC0 TES QUESTIONS :", ...(context.answers ?? []).map((answer) => `- ${answer.questionId} : ${answer.answer}`)],
+    "",
+    context.questions?.allowed === true ? `Tourn\xE9e ${context.questions.round} sur ${MAX_QUESTION_ROUNDS} : si une r\xE9ponse du client changerait la spec, pose tes questions (format QUESTIONS) ; sinon, r\xE9dige le fichier.` : "N'interroge plus : r\xE9dige le fichier maintenant, et consigne ce que tu ne sais pas sous `# Hypoth\xE8ses`."
   ].join("\n");
   return { system, user, documents: attachmentDocumentsOf(context.attachments ?? []) };
 }
@@ -2471,7 +2578,7 @@ function judgeDraft(input) {
   }
   return { specId, problems: [...new Set(problems)] };
 }
-async function draftSpecFromBrief(deps, input) {
+async function runBrief(deps, input) {
   if (input.specId !== void 0 && !FeatureNameSchema.safeParse(input.specId).success) {
     throwOgygieError(
       {
@@ -2502,6 +2609,8 @@ async function draftSpecFromBrief(deps, input) {
   const knownDecisionIds = (await Promise.all(DECISION_FILES.map((file) => readIfPresent(deps.storage, file)))).flatMap((content) => parseKnownDecisionIds(content ?? ""));
   const existingSpec = input.specId !== void 0 ? await readIfPresent(deps.storage, `specs/${input.specId}.spec.md`) : null;
   const isAmendment = existingSpec !== null;
+  const round = Math.min(Math.max(input.round ?? 1, 1), MAX_QUESTION_ROUNDS + 1);
+  const questionsAllowed = input.skipQuestions !== true && round <= MAX_QUESTION_ROUNDS;
   const prompt = buildBriefPrompt({
     template,
     productRules,
@@ -2512,15 +2621,40 @@ async function draftSpecFromBrief(deps, input) {
     existingSpec,
     specId: input.specId,
     brief: input.brief,
-    attachments: input.attachments
+    attachments: input.attachments,
+    answers: input.answers,
+    questions: { allowed: questionsAllowed, round }
   });
   const usage = [];
+  let refusedQuestions = false;
   let previous;
   let firstProblems = [];
   let maxAttempts = MAX_ATTEMPTS;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    deps.onStage?.({ stage: "drafting", attempt });
     const answer = await deps.writer.write({ ...prompt, previous });
     usage.push({ model: answer.model, ...answer.usage });
+    const asked = extractQuestions(answer.text);
+    if (asked !== null) {
+      if ("problem" in asked) {
+        deps.log(JSON.stringify({ action: "brief", attempt, questions: "malformed", ...answer.usage }));
+        if (attempt === 1) firstProblems = [asked.problem];
+        previous = { draft: answer.text, problems: [asked.problem] };
+        continue;
+      }
+      if (questionsAllowed) {
+        deps.log(JSON.stringify({ action: "brief", attempt, round, questions: asked.questions.length, ...answer.usage }));
+        return { kind: "questions", round, questions: asked.questions, usage };
+      }
+      deps.log(JSON.stringify({ action: "brief", attempt, round, questions: "refused", ...answer.usage }));
+      if (!refusedQuestions) {
+        refusedQuestions = true;
+        maxAttempts += 1;
+      }
+      previous = { draft: answer.text, problems: [NO_MORE_QUESTIONS] };
+      continue;
+    }
+    deps.onStage?.({ stage: "judging", attempt });
     const content = extractSpecText(answer.text);
     const judged = judgeDraft({
       content,
@@ -2535,7 +2669,11 @@ async function draftSpecFromBrief(deps, input) {
     deps.log(JSON.stringify({ action: "brief", attempt, specId: judged.specId, problems: judged.problems.length, generated: generationJudgement.tally !== null, ...answer.usage }));
     if (judged.problems.length === 0 && judged.specId !== null) {
       const specId = judged.specId;
-      const briefForMessage = (input.brief.length > BRIEF_IN_MESSAGE_MAX ? `${input.brief.slice(0, BRIEF_IN_MESSAGE_MAX)} (\u2026)` : input.brief) + attachmentsProvenance(input.attachments ?? []);
+      const assumptions = assumptionsOfSpec(content);
+      const briefForMessage = (input.brief.length > BRIEF_IN_MESSAGE_MAX ? `${input.brief.slice(0, BRIEF_IN_MESSAGE_MAX)} (\u2026)` : input.brief) + attachmentsProvenance(input.attachments ?? []) + (assumptions.length === 0 ? "" : `
+
+Hypoth\xE8ses du mod\xE8le (D57) :
+${assumptions.map((line) => `- ${line}`).join("\n")}`);
       const composition = isAmendment ? null : compositionOfSpec(content);
       const compositions = [];
       if (composition !== null) {
@@ -2553,7 +2691,9 @@ async function draftSpecFromBrief(deps, input) {
           deps.log(JSON.stringify({ action: "composition", specId, outcome: thrown instanceof OgygieFailure ? thrown.error.code : "error" }));
         }
         const seen = /* @__PURE__ */ new Set([composition]);
-        for (const candidate of splitCompositions(answerText)) {
+        const candidates = splitCompositions(answerText);
+        deps.onStage?.({ stage: "compositions", composition: { done: 0, total: Math.min(candidates.length, MAX_COMPOSITIONS - 1) } });
+        for (const candidate of candidates) {
           if (seen.size >= MAX_COMPOSITIONS) break;
           const name = compositionOfSpec(candidate);
           const verdict = judgeDraft({ content: candidate, expectedId: specId, knownDecisionIds, takenIds: specIds, isAmendment: false });
@@ -2561,6 +2701,7 @@ async function draftSpecFromBrief(deps, input) {
           deps.log(JSON.stringify({ action: "composition", specId, composition: name, problems: problems.length }));
           if (problems.length > 0 || name === null) continue;
           seen.add(name);
+          deps.onStage?.({ stage: "compositions", composition: { done: seen.size - 1, total: Math.min(candidates.length, MAX_COMPOSITIONS - 1) } });
           await deps.storage.write(`specs/${specId}.spec.md`, candidate, `spec: composition ${name} pour ${specId}, propos\xE9e par le mod\xE8le
 
 Une autre disposition du m\xEAme \xE9cran ; la composition retenue par d\xE9faut suit dans le commit suivant.
@@ -2571,6 +2712,7 @@ ${briefForMessage}`);
         }
         compositions.unshift(composition);
       }
+      deps.onStage?.({ stage: "writing" });
       await deps.storage.write(
         `specs/${specId}.spec.md`,
         content,
@@ -2580,14 +2722,18 @@ Brief :
 ${briefForMessage}`
       );
       return {
-        specId,
-        attempts: attempt,
-        problemsFixed: firstProblems,
-        isNewFeature: !manifest.featureIds.has(specId),
-        isAmendment,
-        compositions,
-        generation: generationJudgement.tally,
-        usage
+        kind: "draft",
+        result: {
+          specId,
+          attempts: attempt,
+          problemsFixed: firstProblems,
+          isNewFeature: !manifest.featureIds.has(specId),
+          isAmendment,
+          compositions,
+          generation: generationJudgement.tally,
+          assumptions,
+          usage
+        }
       };
     }
     if (attempt === 1) firstProblems = judged.problems;
@@ -2606,37 +2752,144 @@ ${briefForMessage}`
   );
 }
 
+// src/server/hosted/brief-jobs.ts
+import { randomUUID } from "node:crypto";
+var BRIEF_BUDGET_MS = 9e4;
+var BRIEF_JOB_TTL_MS = 15 * 6e4;
+function createBriefJobs(deps) {
+  const budgetMs = deps.budgetMs ?? BRIEF_BUDGET_MS;
+  const ttlMs = deps.ttlMs ?? BRIEF_JOB_TTL_MS;
+  const idOf = deps.idOf ?? randomUUID;
+  const jobs = /* @__PURE__ */ new Map();
+  const settlements = /* @__PURE__ */ new Map();
+  const sweep = () => {
+    const now = deps.now();
+    for (const [jobId, job] of jobs) {
+      if (job.endedAt !== null && job.endedAt + ttlMs <= now) {
+        jobs.delete(jobId);
+        settlements.delete(jobId);
+      }
+    }
+  };
+  const errorOf = (thrown) => thrown instanceof OgygieFailure ? thrown.error : ogygieError({
+    code: "BRIEF_FAILED",
+    message: "The brief failed before a draft or a round of questions came out.",
+    file: null,
+    cause: thrown instanceof Error ? thrown.message : String(thrown),
+    suggestedFix: "Send the brief again; if it repeats, read the instance log."
+  });
+  return {
+    start(owner, run) {
+      sweep();
+      const running = [...jobs.values()].find((job2) => job2.owner === owner && job2.endedAt === null);
+      if (running !== void 0) {
+        throwOgygieError(
+          {
+            code: "BRIEF_IN_PROGRESS",
+            message: "A brief of yours is still running: one at a time.",
+            file: null,
+            cause: `job ${running.jobId} started ${deps.now() - running.startedAt} ms ago`,
+            suggestedFix: "Wait for it to end (GET /api/briefs/<id>), then send the next brief.",
+            details: { jobId: running.jobId }
+          },
+          409
+        );
+      }
+      const job = { jobId: idOf(), owner, startedAt: deps.now(), endedAt: null, progress: null, outcome: null, error: null };
+      jobs.set(job.jobId, job);
+      const settlement = run((progress) => {
+        job.progress = progress;
+      }).then((outcome) => {
+        job.outcome = outcome;
+      }).catch((thrown) => {
+        job.error = errorOf(thrown);
+      }).finally(() => {
+        job.endedAt = deps.now();
+      });
+      settlements.set(job.jobId, settlement);
+      return job.jobId;
+    },
+    read(jobId) {
+      sweep();
+      const job = jobs.get(jobId);
+      if (job === void 0) {
+        return throwOgygieError(
+          {
+            code: "BRIEF_JOB_LOST",
+            message: "This brief job is unknown here: it expired, or the instance restarted since.",
+            file: null,
+            cause: `no job ${jobId} in memory`,
+            suggestedFix: "Send the brief again; its text is still in your editor."
+          },
+          404
+        );
+      }
+      const base = { jobId: job.jobId, elapsedMs: Math.max(0, (job.endedAt ?? deps.now()) - job.startedAt), budgetMs };
+      if (job.error !== null) return { ...base, stage: "failed", error: job.error };
+      if (job.outcome !== null) {
+        return job.outcome.kind === "draft" ? { ...base, stage: "done", result: job.outcome.result } : { ...base, stage: "questions", round: job.outcome.round, questions: job.outcome.questions };
+      }
+      const progress = job.progress ?? { stage: "drafting", attempt: 1 };
+      switch (progress.stage) {
+        case "drafting":
+        case "judging":
+          return { ...base, stage: progress.stage, attempt: progress.attempt };
+        case "compositions":
+          return { ...base, stage: "compositions", composition: progress.composition };
+        case "writing":
+          return { ...base, stage: "writing" };
+      }
+    },
+    async settled(jobId) {
+      await (settlements.get(jobId) ?? Promise.resolve());
+    }
+  };
+}
+
 // src/server/hosted/brief-routes.ts
 var BRIEF_BODY_LIMIT = 16 * 1024 * 1024;
 async function registerBriefRoutes(app, deps) {
   const route = app.withTypeProvider();
+  const now = deps.now ?? Date.now;
+  const jobs = deps.jobs ?? createBriefJobs({ now });
   route.route({
     method: "POST",
     url: "/api/briefs",
     bodyLimit: BRIEF_BODY_LIMIT,
-    schema: { body: BriefInputSchema, response: { 201: BriefOutputSchema } },
+    schema: { body: BriefInputSchema, response: { 202: BriefStartOutputSchema } },
     handler: async (request, reply) => {
       const user = hostedUserOf(request);
       requireRole(user, "author", "write a brief");
       const attachments = prepareBriefAttachments(request.body.attachments ?? []);
       const storage = deps.storageFor(user);
-      const result = await draftSpecFromBrief(
-        { storage, writer: deps.writer, log: deps.log },
-        { brief: request.body.brief, specId: request.body.specId, attachments }
-      );
-      const proposal = "lastProposal" in storage ? storage.lastProposal : null;
-      if (deps.usage !== void 0 && proposal !== null) {
-        const at = new Date((deps.now ?? Date.now)()).toISOString();
-        try {
-          await deps.usage.appendUsage(
-            proposal.pullRequestNumber,
-            result.usage.map((usage, index) => ({ at, action: "brief", attempt: index + 1, model: usage.model, inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, actor: user.email, specId: result.specId }))
-          );
-        } catch (thrown) {
-          deps.log(JSON.stringify({ action: "usage-journal", specId: result.specId, outcome: thrown instanceof Error ? thrown.message : String(thrown) }));
+      const { brief, specId, answers, round, skipQuestions } = request.body;
+      const jobId = jobs.start(user.email, async (onStage) => {
+        const outcome = await runBrief({ storage, writer: deps.writer, log: deps.log, onStage }, { brief, specId, attachments, answers, round, skipQuestions });
+        if (outcome.kind !== "draft") return outcome;
+        const proposal = "lastProposal" in storage ? storage.lastProposal : null;
+        if (deps.usage !== void 0 && proposal !== null) {
+          const at = new Date(now()).toISOString();
+          try {
+            await deps.usage.appendUsage(
+              proposal.pullRequestNumber,
+              outcome.result.usage.map((usage, index) => ({ at, action: "brief", attempt: index + 1, model: usage.model, inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, actor: user.email }))
+            );
+          } catch (thrown) {
+            deps.log(JSON.stringify({ action: "usage-journal", specId: outcome.result.specId, outcome: thrown instanceof Error ? thrown.message : String(thrown) }));
+          }
         }
-      }
-      return reply.code(201).send(result);
+        return outcome;
+      });
+      return reply.code(202).send({ jobId });
+    }
+  });
+  route.route({
+    method: "GET",
+    url: "/api/briefs/:jobId",
+    schema: { params: z10.object({ jobId: z10.string().min(1) }), response: { 200: BriefJobSchema } },
+    handler: async (request, reply) => {
+      hostedUserOf(request);
+      return reply.code(200).send(jobs.read(request.params.jobId));
     }
   });
 }
@@ -3004,6 +3257,48 @@ async function environmentsStatus(deps) {
     releases: releases.sort().reverse()
   };
 }
+var LINE_LENGTH = 30;
+function commitTitleOf(message) {
+  const firstLine = message.split("\n")[0] ?? "";
+  return firstLine.replace(/^spec: merge /u, "").replace(/\s*\(#\d+\)\s*$/u, "").trim();
+}
+function reachOf(environment, index, deployedIndex, stagingIndex) {
+  if (index === deployedIndex) return { reach: "deployed", why: "d\xE9ploy\xE9" };
+  if (environment === "development") return { reach: "unreachable", why: "le d\xE9veloppement suit la branche par d\xE9faut, il ne se promeut pas" };
+  const newer = deployedIndex === -1 || index < deployedIndex;
+  if (environment === "staging") {
+    return newer ? { reach: "forward", why: "avance rapide depuis le d\xE9veloppement" } : { reach: "backward", why: "retour arri\xE8re : op\xE9rateur, avec un motif" };
+  }
+  if (index === stagingIndex && newer) return { reach: "forward", why: "le commit de la pr\xE9production" };
+  if (newer) return { reach: "unreachable", why: stagingIndex !== -1 && index < stagingIndex ? "la pr\xE9production ne l'a pas re\xE7u (PROMOTION_ORDER_VIOLATED)" : "seul le commit de la pr\xE9production est promouvable" };
+  return { reach: "backward", why: "retour arri\xE8re : op\xE9rateur, avec un motif" };
+}
+async function environmentCommits(deps, environment) {
+  const ref = environment === "development" ? deps.defaultBranch : ENVIRONMENT_REFS[environment];
+  const [deployedSha, stagingSha, commits, tags] = await Promise.all([
+    deps.deploy.getRefSha(ref),
+    environment === "production" ? deps.deploy.getRefSha(ENVIRONMENT_REFS.staging) : Promise.resolve(null),
+    deps.deploy.listCommits(deps.defaultBranch, LINE_LENGTH),
+    deps.deploy.listReleaseTags("release/")
+  ]);
+  const tagOf = new Map(tags.map((tag) => [tag.sha, tag.name]));
+  const deployedIndex = commits.findIndex((commit) => commit.sha === deployedSha);
+  const stagingIndex = stagingSha === null ? -1 : commits.findIndex((commit) => commit.sha === stagingSha);
+  return {
+    environment,
+    ref,
+    deployedSha,
+    commits: commits.map((commit, index) => ({
+      sha: commit.sha,
+      title: commitTitleOf(commit.message),
+      specId: MERGED_SPEC.exec(commit.message.split("\n")[0] ?? "")?.[1] ?? null,
+      author: commit.author,
+      authoredAt: commit.authoredAt,
+      releaseTag: tagOf.get(commit.sha) ?? null,
+      ...reachOf(environment, index, deployedIndex, stagingIndex)
+    }))
+  };
+}
 function pullRequestsOf(commits) {
   const included = [];
   for (const commit of commits) {
@@ -3134,6 +3429,15 @@ async function registerPromotionRoutes(app, deps) {
       return reply.code(200).send(await environmentsStatus(promotionDeps));
     }
   });
+  route.route({
+    method: "GET",
+    url: "/api/environments/:environment/commits",
+    schema: { params: EnvironmentReadParamsSchema, response: { 200: EnvironmentCommitsSchema } },
+    handler: async (request, reply) => {
+      hostedUserOf(request);
+      return reply.code(200).send(await environmentCommits(promotionDeps, request.params.environment));
+    }
+  });
   route.route({
     method: "POST",
     url: "/api/environments/:environment/promotions",
@@ -3147,17 +3451,17 @@ async function registerPromotionRoutes(app, deps) {
 }
 
 // src/server/hosted/usage.ts
-import { z as z10 } from "zod";
-var UsageEntrySchema = z10.object({
-  at: z10.string(),
+import { z as z11 } from "zod";
+var UsageEntrySchema = z11.object({
+  at: z11.string(),
   /** brief → spec from the instance; `speculate` entries arrive with the generator's lot. */
-  action: z10.enum(["brief", "speculate"]),
-  attempt: z10.number().int().positive().optional(),
-  model: z10.string(),
-  inputTokens: z10.number().int().nonnegative(),
-  outputTokens: z10.number().int().nonnegative(),
-  actor: z10.string().optional(),
-  specId: z10.string().optional()
+  action: z11.enum(["brief", "speculate"]),
+  attempt: z11.number().int().positive().optional(),
+  model: z11.string(),
+  inputTokens: z11.number().int().nonnegative(),
+  outputTokens: z11.number().int().nonnegative(),
+  actor: z11.string().optional(),
+  specId: z11.string().optional()
 });
 var USAGE_MARKER = "<!-- ogygie-usage -->";
 var DEFAULT_MODEL_COSTS = {
@@ -3192,7 +3496,7 @@ function parseUsageComment(body) {
   const block = /```json\n([\s\S]*?)\n```/.exec(body)?.[1];
   if (block === void 0) return [];
   try {
-    const parsed = z10.array(UsageEntrySchema).safeParse(JSON.parse(block));
+    const parsed = z11.array(UsageEntrySchema).safeParse(JSON.parse(block));
     return parsed.success ? parsed.data : [];
   } catch {
     return [];
@@ -3267,9 +3571,9 @@ async function registerConsumptionRoutes(app, deps) {
 }
 
 // src/server/hosted/preview-routes.ts
-import { z as z11 } from "zod";
-var PreviewParamsSchema = SpecParamsSchema.extend({ state: z11.string().min(1).max(80) });
-var CompositionPreviewParamsSchema = PreviewParamsSchema.extend({ composition: z11.string().min(1).max(80) });
+import { z as z12 } from "zod";
+var PreviewParamsSchema = SpecParamsSchema.extend({ state: z12.string().min(1).max(80) });
+var CompositionPreviewParamsSchema = PreviewParamsSchema.extend({ composition: z12.string().min(1).max(80) });
 var PREVIEW_CSP = "sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data:";
 async function registerPreviewRoutes(app, deps) {
   const route = app.withTypeProvider();
@@ -3311,7 +3615,7 @@ async function registerPreviewRoutes(app, deps) {
 }
 
 // src/server/hosted/composition-routes.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 
 // src/server/hosted/compositions.ts
 var COMPOSITION_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -3355,7 +3659,7 @@ La composition \xAB ${composition} \xBB est retenue parmi celles propos\xE9es ;
 }
 
 // src/server/hosted/composition-routes.ts
-var CompositionParamsSchema = SpecParamsSchema.extend({ composition: z12.string().min(1).max(80) });
+var CompositionParamsSchema = SpecParamsSchema.extend({ composition: z13.string().min(1).max(80) });
 async function registerCompositionRoutes(app, deps) {
   const route = app.withTypeProvider();
   route.route({
@@ -3849,6 +4153,29 @@ function createGithubDeployClient(deps) {
         commits: (answer?.commits ?? []).map((entry) => ({ sha: entry.sha, message: entry.commit.message, authoredAt: entry.commit.author.date }))
       };
     },
+    async listReleaseTags(prefix) {
+      const refs = await request("GET", `${repoUrl}/git/matching-refs/tags/${prefix}`, void 0) ?? [];
+      const tags = [];
+      for (const entry of refs) {
+        const name = entry.ref.replace(/^refs\/tags\//u, "");
+        if (entry.object.type !== "tag") {
+          tags.push({ name, sha: entry.object.sha });
+          continue;
+        }
+        const tag = await request("GET", `${repoUrl}/git/tags/${entry.object.sha}`, void 0, true);
+        if (tag !== null) tags.push({ name, sha: tag.object.sha });
+      }
+      return tags;
+    },
+    async listCommits(ref, perPage) {
+      const answer = await request(
+        "GET",
+        `${repoUrl}/commits?sha=${encodeURIComponent(ref)}&per_page=${Math.min(Math.max(perPage, 1), 100)}`,
+        void 0,
+        true
+      );
+      return (answer ?? []).map((entry) => ({ sha: entry.sha, message: entry.commit.message, authoredAt: entry.commit.author.date, author: entry.commit.author.name }));
+    },
     async updateRef(ref, sha, force) {
       await request("PATCH", `${repoUrl}/git/refs/heads/${encodeURIComponent(ref)}`, { sha, force });
     },