@ogygie/core 0.19.0 → 0.21.0

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@ogygie/core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Ogygie framework core: manifest/spec/error schemas, generic tenancy and gate tooling. Ships TypeScript sources — Ogygie products run tsx/vitest by construction (D1).",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julienTeam/Ogygie.git",
+    "directory": "packages/ogygie-core"
+  },
   "type": "module",
   "files": [
     "src",
@@ -26,7 +31,9 @@
     "./impact": "./src/impact.ts",
     "./manifest": "./src/manifest.schema.ts",
     "./manifest-owners": "./src/manifest-owners.ts",
+    "./model": "./src/model.ts",
     "./module-purity": "./src/module-purity.ts",
+    "./proposal": "./src/proposal.ts",
     "./repo-adapter": "./src/repo-adapter.ts",
     "./scan": "./src/scan.ts",
     "./shared-tables": "./src/shared-tables.ts",

package/src/model.test.ts

@@ -0,0 +1,61 @@
+/**
+ * @intent Proves the shared model client against a fake `fetch`: the request
+ * carries the key, the version, the model, a cached system block, the
+ * messages and the effort; the text, the stop reason and the usage come back;
+ * a spent budget, an outage and a network failure each have their code and
+ * status.
+ */
+import { describe, expect, it } from "vitest";
+import { OgygieFailure } from "./error.schema.js";
+import { createMessagesClient } from "./model.js";
+
+function fakeApi(answer: { status?: number; body: unknown }) {
+  const calls: { url: string; headers: Record<string, string>; body: Record<string, unknown> }[] = [];
+  const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+    calls.push({ url: String(input), headers: init?.headers as Record<string, string>, body: JSON.parse(String(init?.body)) as Record<string, unknown> });
+    return new Response(typeof answer.body === "string" ? answer.body : JSON.stringify(answer.body), { status: answer.status ?? 200 });
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const OK = { content: [{ type: "text", text: "hello" }, { type: "thinking", thinking: "" }], stop_reason: "end_turn", model: "claude-opus-5-5", usage: { input_tokens: 12, output_tokens: 3 } };
+
+describe("createMessagesClient", () => {
+  it("ÉTANT DONNÉ une complétion ALORS la requête porte clé, version, modèle, bloc system mis en cache, messages, effort ; le texte, le stop et l'usage reviennent", async () => {
+    const api = fakeApi({ body: OK });
+    const client = createMessagesClient({ apiKey: "sk-test", fetchImpl: api.fetchImpl });
+    const answer = await client.complete({ model: "claude-opus-5-5", system: "rules", messages: [{ role: "user", content: "hi" }], maxTokens: 500, effort: "low" });
+    expect(answer).toEqual({ text: "hello", model: "claude-opus-5-5", stopReason: "end_turn", usage: { inputTokens: 12, outputTokens: 3 } });
+    expect(api.calls[0]?.url).toBe("https://api.anthropic.com/v1/messages");
+    expect(api.calls[0]?.headers["x-api-key"]).toBe("sk-test");
+    expect(api.calls[0]?.headers["anthropic-version"]).toBe("2023-06-01");
+    expect(api.calls[0]?.body).toEqual({
+      model: "claude-opus-5-5",
+      max_tokens: 500,
+      system: [{ type: "text", text: "rules", cache_control: { type: "ephemeral" } }],
+      messages: [{ role: "user", content: "hi" }],
+      output_config: { effort: "low" },
+    });
+  });
+
+  it.each([
+    ["plafond dépensé", { status: 400, body: { error: { message: "Your credit balance is too low" } } }, "MODEL_BUDGET_EXCEEDED", 429],
+    ["panne", { status: 529, body: "overloaded" }, "MODEL_UNAVAILABLE", 502],
+  ])("%s → %s", async (_label, answer, code, status) => {
+    const api = fakeApi(answer);
+    const client = createMessagesClient({ apiKey: "k", fetchImpl: api.fetchImpl, credentialHint: "OGYGIE_MODEL_API_KEY" });
+    try {
+      await client.complete({ model: "m", system: "s", messages: [{ role: "user", content: "u" }] });
+      expect.fail("expected a refusal");
+    } catch (thrown) {
+      expect(thrown).toBeInstanceOf(OgygieFailure);
+      expect((thrown as OgygieFailure).error.code).toBe(code);
+      expect((thrown as OgygieFailure).httpStatus).toBe(status);
+    }
+  });
+
+  it("un échec réseau → MODEL_UNAVAILABLE", async () => {
+    const client = createMessagesClient({ apiKey: "k", fetchImpl: (async () => { throw new Error("ECONNRESET"); }) as typeof fetch });
+    await expect(client.complete({ model: "m", system: "s", messages: [{ role: "user", content: "u" }] })).rejects.toMatchObject({ error: { code: "MODEL_UNAVAILABLE", cause: "ECONNRESET" } });
+  });
+});

package/src/model.ts

@@ -0,0 +1,123 @@
+/**
+ * @intent The ONE way the framework calls a model: the Messages API over an
+ * injected `fetch` — no SDK, no dependency (the core's contract, D1). Two
+ * consumers share it — the hosted studio (brief → spec, spec ogygie-hosted-mode
+ * B3) and the generator (the filling of holes, D24) — and a request shape
+ * fixed on one side and not the other would be a lockstep bug waiting to
+ * happen (the motive of D10, applied to models).
+ *
+ * What it knows: the endpoint, the headers, the cached system block, the
+ * usage an answer carries, and the two refusals every caller must tell apart
+ * — the API unreachable or failing (`MODEL_UNAVAILABLE`) and the client's
+ * workspace out of budget (`MODEL_BUDGET_EXCEEDED`, D50). What it does NOT
+ * decide: what a refusal or a truncated answer means for the caller — the
+ * stop reason is returned, each caller names its own outcome.
+ */
+import { throwOgygieError } from "./error.schema.js";
+
+export interface ModelMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface ModelCompletionInput {
+  model: string;
+  /** Stable instructions and context — marked for caching on the model side. */
+  system: string;
+  messages: ModelMessage[];
+  maxTokens?: number;
+  effort?: "low" | "medium" | "high" | "xhigh" | "max";
+}
+
+export interface ModelCompletion {
+  text: string;
+  model: string;
+  stopReason: string | null;
+  usage: { inputTokens: number; outputTokens: number };
+}
+
+export interface ModelClient {
+  complete(input: ModelCompletionInput): Promise<ModelCompletion>;
+}
+
+export interface MessagesClientDeps {
+  apiKey: string;
+  fetchImpl: typeof fetch;
+  apiBase?: string;
+  /** Named in a refusal so the operator knows which key to check. */
+  credentialHint?: string;
+}
+
+/** Shape of what the Messages API answers, reduced to what is read here. */
+interface MessagesAnswer {
+  content: { type: string; text?: string }[];
+  stop_reason: string | null;
+  model: string;
+  usage: { input_tokens: number; output_tokens: number };
+}
+
+export function createMessagesClient(deps: MessagesClientDeps): ModelClient {
+  const apiBase = deps.apiBase ?? "https://api.anthropic.com";
+  const credential = deps.credentialHint ?? "the model API key";
+  return {
+    async complete(input) {
+      let response: Response;
+      try {
+        response = await deps.fetchImpl(`${apiBase}/v1/messages`, {
+          method: "POST",
+          headers: {
+            "x-api-key": deps.apiKey,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({
+            model: input.model,
+            max_tokens: input.maxTokens ?? 16_000,
+            system: [{ type: "text", text: input.system, cache_control: { type: "ephemeral" } }],
+            messages: input.messages,
+            output_config: { effort: input.effort ?? "high" },
+          }),
+        });
+      } catch (thrown) {
+        return throwOgygieError(
+          {
+            code: "MODEL_UNAVAILABLE",
+            message: "The model API could not be reached.",
+            file: null,
+            cause: thrown instanceof Error ? thrown.message : String(thrown),
+            suggestedFix: "Retry once the network is back; nothing was written.",
+          },
+          502,
+        );
+      }
+      if (!response.ok) {
+        const body = await response.text();
+        const budget = response.status === 400 && /credit|billing|spend|budget/i.test(body);
+        return throwOgygieError(
+          {
+            code: budget ? "MODEL_BUDGET_EXCEEDED" : "MODEL_UNAVAILABLE",
+            message: budget
+              ? "The model workspace refused the call: its spending limit is reached."
+              : `The model API answered ${response.status}.`,
+            file: null,
+            cause: `status=${response.status} ${body.slice(0, 300)}`,
+            suggestedFix: budget
+              ? "The monthly budget of this workspace is spent; it resets with the month, or the operator raises it."
+              : `Check ${credential} and retry; nothing was written.`,
+          },
+          budget ? 429 : 502,
+        );
+      }
+      const answer = (await response.json()) as MessagesAnswer;
+      return {
+        text: answer.content
+          .filter((block) => block.type === "text" && typeof block.text === "string")
+          .map((block) => block.text ?? "")
+          .join(""),
+        model: answer.model,
+        stopReason: answer.stop_reason,
+        usage: { inputTokens: answer.usage.input_tokens, outputTokens: answer.usage.output_tokens },
+      };
+    },
+  };
+}

package/src/proposal.test.ts

@@ -0,0 +1,315 @@
+/**
+ * @intent Proves the proposal module of the core (D17, D51) on an in-memory
+ * repo and an in-memory GitHub: the client hits the documented endpoints over
+ * an injected `fetch`, the perimeter is refused before any call, the branch
+ * and the PR body are what the caller injects, and nothing touches a disk or
+ * the network. The full behavioral suite of the write path (every refusal of
+ * spec ogygie-mcp B10) runs in the MCP package, which consumes this module.
+ */
+import { describe, expect, it } from "vitest";
+import { OgygieFailure } from "./error.schema.js";
+import { createInMemoryRepoAdapter } from "./repo-adapter.js";
+import {
+  assertProposablePath,
+  createGithubWriteClient,
+  proposeChange,
+  type GithubWriteClient,
+  type ProposalDeps,
+  type ProposalTarget,
+} from "./proposal.js";
+
+const GITHUB = { owner: "acme", repo: "site", defaultBranch: "main" };
+
+// ------------------------------------------------------------- the client
+
+function fakeFetch(routes: Record<string, { status: number; body?: unknown }>) {
+  const calls: { method: string; url: string; headers: Record<string, string>; body: unknown }[] = [];
+  const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    const method = init?.method ?? "GET";
+    calls.push({
+      method,
+      url,
+      headers: init?.headers as Record<string, string>,
+      body: init?.body === undefined ? undefined : JSON.parse(String(init.body)),
+    });
+    const route = routes[`${method} ${url.replace("https://api.github.com", "")}`];
+    if (route === undefined) return new Response("not found", { status: 404 });
+    return new Response(route.body === undefined ? null : JSON.stringify(route.body), { status: route.status });
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+describe("GithubWriteClient", () => {
+  it("lit une tête de branche, et rend null quand elle n'existe pas", async () => {
+    const { fetchImpl, calls } = fakeFetch({
+      "GET /repos/acme/site/git/ref/heads/main": { status: 200, body: { object: { sha: "abc" } } },
+    });
+    const client = createGithubWriteClient({ token: "tkn", fetchImpl }, GITHUB);
+    expect(await client.getBranchHead("main")).toBe("abc");
+    expect(await client.getBranchHead("mcp/acme/x")).toBeNull();
+    expect(calls[0]?.headers["authorization"]).toBe("Bearer tkn");
+  });
+
+  it("décode le contenu base64 d'un fichier et porte son sha ; absent → null", async () => {
+    const { fetchImpl } = fakeFetch({
+      "GET /repos/acme/site/contents/DECISIONS.md?ref=abc": {
+        status: 200,
+        body: { content: Buffer.from("# Décisions\n", "utf8").toString("base64"), sha: "blob1" },
+      },
+    });
+    const client = createGithubWriteClient({ token: "tkn", fetchImpl }, GITHUB);
+    expect(await client.readFileAtRef("DECISIONS.md", "abc")).toEqual({ content: "# Décisions\n", sha: "blob1" });
+    expect(await client.readFileAtRef("specs/none.spec.md", "abc")).toBeNull();
+  });
+
+  it("commit un fichier en base64 sur la branche, avec le sha attendu quand il y en a un", async () => {
+    const { fetchImpl, calls } = fakeFetch({
+      "PUT /repos/acme/site/contents/specs/orders.spec.md": { status: 201, body: { commit: { sha: "c1" } } },
+    });
+    const client = createGithubWriteClient({ token: "tkn", fetchImpl }, GITHUB);
+    const result = await client.commitFile({ branch: "mcp/x", path: "specs/orders.spec.md", content: "é", message: "m", expectedSha: "blob1" });
+    expect(result.commitSha).toBe("c1");
+    expect(calls[0]?.body).toEqual({ message: "m", content: Buffer.from("é").toString("base64"), branch: "mcp/x", sha: "blob1" });
+  });
+
+  it("une réponse non 2xx hors 404 toléré → GITHUB_UNAVAILABLE avec le statut ; 401 nomme la crédential du consommateur", async () => {
+    const { fetchImpl } = fakeFetch({ "POST /repos/acme/site/git/refs": { status: 401 } });
+    const client = createGithubWriteClient({ token: "tkn", fetchImpl, credentialHint: "MY_TOKEN_VAR" }, GITHUB);
+    try {
+      await client.createBranch("mcp/x", "abc");
+      expect.fail("expected a refusal");
+    } catch (thrown) {
+      expect(thrown).toBeInstanceOf(OgygieFailure);
+      const error = (thrown as OgygieFailure).error;
+      expect(error.code).toBe("GITHUB_UNAVAILABLE");
+      expect(error.cause).toBe("status=401");
+      expect(error.suggestedFix).toContain("MY_TOKEN_VAR");
+    }
+  });
+
+  it("un échec réseau → GITHUB_UNAVAILABLE aussi", async () => {
+    const client = createGithubWriteClient(
+      { token: "tkn", fetchImpl: (async () => { throw new Error("ECONNRESET"); }) as typeof fetch },
+      GITHUB,
+    );
+    await expect(client.findOpenPullRequest("mcp/x")).rejects.toMatchObject({ error: { code: "GITHUB_UNAVAILABLE", cause: "ECONNRESET" } });
+  });
+
+  it("trouve la PR ouverte d'une branche par head owner:branch, et en ouvre une sinon", async () => {
+    const { fetchImpl, calls } = fakeFetch({
+      "GET /repos/acme/site/pulls?state=open&head=acme%3Amcp%2Fx": { status: 200, body: [{ number: 7, html_url: "https://g/7" }] },
+      "POST /repos/acme/site/pulls": { status: 201, body: { number: 8, html_url: "https://g/8" } },
+    });
+    const client = createGithubWriteClient({ token: "tkn", fetchImpl, userAgent: "ogygie-test" }, GITHUB);
+    expect(await client.findOpenPullRequest("mcp/x")).toEqual({ number: 7, url: "https://g/7" });
+    expect(await client.openPullRequest({ branch: "mcp/y", base: "main", title: "t", body: "b" })).toEqual({ number: 8, url: "https://g/8" });
+    expect(calls[1]?.body).toEqual({ title: "t", body: "b", head: "mcp/y", base: "main" });
+    expect(calls[0]?.headers["user-agent"]).toBe("ogygie-test");
+  });
+});
+
+// ------------------------------------------------------------ the proposal
+
+const ORDERS_SPEC = [
+  "---",
+  "id: orders",
+  "status: draft",
+  "depends_on: []",
+  "priority: P1",
+  "refs: []",
+  "---",
+  "",
+  "# @intent",
+  "Commander.",
+  "",
+  "# Comportements",
+  "- ÉTANT DONNÉ… QUAND… ALORS…",
+  "",
+  "# Contrats de données",
+  "- OrderSchema",
+  "",
+  "# États UI",
+  "- vide / nominal",
+  "",
+  "# Non-objectifs",
+  "- rien d'autre",
+  "",
+  "# Budget",
+  "- P95 < 100 ms",
+  "",
+].join("\n");
+
+const BASE_FILES: Record<string, string> = {
+  "DECISIONS.md": "# DECISIONS.md\n",
+  "DECISIONS.product.md": "# DECISIONS.product.md\n",
+  "specs/orders.spec.md": ORDERS_SPEC,
+};
+
+/** An in-memory GitHub, recording every call it receives. */
+function fakeGithub(files: Record<string, string>) {
+  let counter = 0;
+  const nextSha = (): string => `sha${(counter += 1)}`;
+  const mainSha = nextSha();
+  const snapshots = new Map<string, Map<string, { content: string; sha: string }>>([
+    [mainSha, new Map(Object.entries(files).map(([path, content]) => [path, { content, sha: nextSha() }]))],
+  ]);
+  const branches = new Map<string, string>([["main", mainSha]]);
+  const pulls: { number: number; url: string; branch: string; base: string; title: string; body: string }[] = [];
+  const calls: string[] = [];
+  const client: GithubWriteClient = {
+    async getBranchHead(branch) {
+      calls.push(`head ${branch}`);
+      return branches.get(branch) ?? null;
+    },
+    async readFileAtRef(path, ref) {
+      calls.push(`read ${path}@${ref}`);
+      return snapshots.get(ref)?.get(path) ?? null;
+    },
+    async createBranch(branch, fromSha) {
+      calls.push(`branch ${branch}`);
+      branches.set(branch, fromSha);
+    },
+    async commitFile(input) {
+      calls.push(`commit ${input.branch} ${input.path}`);
+      const head = branches.get(input.branch) ?? mainSha;
+      const next = new Map(snapshots.get(head));
+      next.set(input.path, { content: input.content, sha: nextSha() });
+      const commitSha = nextSha();
+      snapshots.set(commitSha, next);
+      branches.set(input.branch, commitSha);
+      return { commitSha };
+    },
+    async findOpenPullRequest(branch) {
+      calls.push(`pull? ${branch}`);
+      const found = pulls.find((pull) => pull.branch === branch);
+      return found === undefined ? null : { number: found.number, url: found.url };
+    },
+    async openPullRequest(input) {
+      const number = pulls.length + 1;
+      const pull = { number, url: `https://github.test/acme/site/pull/${number}`, ...input };
+      pulls.push(pull);
+      calls.push(`open ${input.branch}`);
+      return { number, url: pull.url };
+    },
+  };
+  return { client, calls, pulls, branches, mainSha };
+}
+
+function targetOn(files: Record<string, string>): ProposalTarget {
+  return { id: "acme", github: GITHUB, adapter: createInMemoryRepoAdapter(files) };
+}
+
+function depsFor(client: GithubWriteClient, overrides: Partial<ProposalDeps> = {}): ProposalDeps {
+  return {
+    clientFor: () => client,
+    originOf: (path) => `Proposé par le test (chemin ${path}).`,
+    now: () => 1_000_000,
+    rateLimitPerHour: 20,
+    recentProposals: new Map(),
+    ...overrides,
+  };
+}
+
+async function codeOf(action: () => Promise<unknown>): Promise<string> {
+  try {
+    await action();
+    return "<no refusal>";
+  } catch (thrown) {
+    return thrown instanceof OgygieFailure ? thrown.error.code : "<not an OgygieFailure>";
+  }
+}
+
+describe("proposeChange — le périmètre, avant tout", () => {
+  it.each(["AGENTS.md", "ogygie.manifest.json", "specs/_TEMPLATE.spec.md", "src/x.ts", "../DECISIONS.md"])(
+    "%s → WRITE_PATH_FORBIDDEN, sans aucun appel GitHub",
+    async (path) => {
+      const github = fakeGithub(BASE_FILES);
+      expect(await codeOf(() => proposeChange(targetOn(BASE_FILES), depsFor(github.client), { path, content: "x", message: "a long enough message" }))).toBe("WRITE_PATH_FORBIDDEN");
+      expect(github.calls).toEqual([]);
+      expect(() => assertProposablePath(path)).toThrow(OgygieFailure);
+    },
+  );
+
+  it("accepte les trois natures du périmètre", () => {
+    expect(assertProposablePath("specs/orders.spec.md")).toBe("specs/orders.spec.md");
+    expect(assertProposablePath("DECISIONS.md")).toBe("DECISIONS.md");
+    expect(assertProposablePath("DECISIONS.product.md")).toBe("DECISIONS.product.md");
+  });
+});
+
+describe("proposeChange — la branche et le corps de PR sont ceux que le consommateur injecte", () => {
+  it("ÉTANT DONNÉ aucun branchFor ALORS la branche est mcp/<id>/<slug> et le corps porte originOf (D17)", async () => {
+    const github = fakeGithub(BASE_FILES);
+    const proposal = await proposeChange(targetOn(BASE_FILES), depsFor(github.client), {
+      path: "specs/orders.spec.md",
+      content: ORDERS_SPEC.replace("status: draft", "status: validated"),
+      message: "spec(orders): validée",
+    });
+    expect(proposal).toMatchObject({ repo: "acme", branch: "mcp/acme/specs-orders-spec-md", baseSha: github.mainSha, created: true, pullRequestNumber: 1 });
+    expect(github.pulls[0]?.body).toContain("Proposé par le test (chemin specs/orders.spec.md).");
+    expect(github.pulls[0]?.title).toBe("spec(orders): validée");
+    expect(github.branches.get("main")).toBe(github.mainSha);
+  });
+
+  it("ÉTANT DONNÉ un branchFor ALORS la proposition atterrit sur cette branche — le chemin du mode hébergé (spec/<id>)", async () => {
+    const github = fakeGithub(BASE_FILES);
+    const deps = depsFor(github.client, { branchFor: (_target, path) => `spec/${path.replace(/^specs\//, "").replace(/\.spec\.md$/, "")}` });
+    const proposal = await proposeChange(targetOn(BASE_FILES), deps, {
+      path: "specs/orders.spec.md",
+      content: ORDERS_SPEC,
+      message: "spec(orders): amendement",
+    });
+    expect(proposal.branch).toBe("spec/orders");
+    expect(github.calls).toContain("branch spec/orders");
+    expect(github.calls).toContain("commit spec/orders specs/orders.spec.md");
+  });
+
+  it("le compteur de débit est tenu par id de cible, et une proposition refusée n'y entre pas", async () => {
+    const github = fakeGithub(BASE_FILES);
+    const deps = depsFor(github.client, { rateLimitPerHour: 1 });
+    await proposeChange(targetOn(BASE_FILES), deps, { path: "specs/orders.spec.md", content: ORDERS_SPEC, message: "spec(orders): un" });
+    expect(deps.recentProposals.get("acme")).toHaveLength(1);
+    expect(await codeOf(() => proposeChange(targetOn(BASE_FILES), deps, { path: "specs/orders.spec.md", content: ORDERS_SPEC, message: "spec(orders): deux" }))).toBe("WRITE_RATE_LIMITED");
+    expect(deps.recentProposals.get("acme")).toHaveLength(1);
+  });
+
+  it("ÉTANT DONNÉ authorOf ALORS le commit porte l'humain en author (D45) ; absent, rien n'est ajouté", async () => {
+    const github = fakeGithub(BASE_FILES);
+    const authors: unknown[] = [];
+    const client: GithubWriteClient = {
+      ...github.client,
+      async commitFile(input) {
+        authors.push(input.author);
+        return github.client.commitFile(input);
+      },
+    };
+    await proposeChange(targetOn(BASE_FILES), depsFor(client, { authorOf: () => ({ name: "Ada", email: "ada@acme.test" }) }), { path: "specs/orders.spec.md", content: ORDERS_SPEC, message: "spec(orders): par Ada" });
+    await proposeChange(targetOn(BASE_FILES), depsFor(client, { branchFor: () => "spec/other" }), { path: "specs/orders.spec.md", content: ORDERS_SPEC, message: "spec(orders): sans auteur" });
+    expect(authors).toEqual([{ name: "Ada", email: "ada@acme.test" }, undefined]);
+  });
+
+  it("ÉTANT DONNÉ readFrom: branch ALORS la page lue est comparée à la branche, pas à main — le second amendement passe, un amendement périmé est REMOTE_CONFLICT", async () => {
+    const github = fakeGithub(BASE_FILES);
+    const branchFor = () => "spec/orders";
+    const v2 = ORDERS_SPEC.replace("Commander.", "Commander v2.");
+    const v3 = ORDERS_SPEC.replace("Commander.", "Commander v3.");
+    // First amendment: the caller read main (no branch yet).
+    await proposeChange(targetOn(BASE_FILES), depsFor(github.client, { branchFor, readFrom: "branch" }), { path: "specs/orders.spec.md", content: v2, message: "spec(orders): v2" });
+    // Second: the caller read the BRANCH (v2) — passes, where defaultBranch mode would refuse.
+    const onBranch = { ...BASE_FILES, "specs/orders.spec.md": v2 };
+    const second = await proposeChange(targetOn(onBranch), depsFor(github.client, { branchFor, readFrom: "branch" }), { path: "specs/orders.spec.md", content: v3, message: "spec(orders): v3" });
+    expect(second.created).toBe(false);
+    // Stale: a caller still holding main's copy while the branch moved.
+    expect(await codeOf(() => proposeChange(targetOn(BASE_FILES), depsFor(github.client, { branchFor, readFrom: "branch" }), { path: "specs/orders.spec.md", content: v3, message: "spec(orders): périmé" }))).toBe("REMOTE_CONFLICT");
+    // The MCP semantics are untouched: reading main, a second proposal on the same path still passes.
+    expect(await codeOf(() => proposeChange(targetOn(BASE_FILES), depsFor(github.client, { branchFor }), { path: "specs/orders.spec.md", content: v3, message: "spec(orders): depuis main" }))).toBe("<no refusal>");
+  });
+
+  it("une spec invalide est refusée AVANT la lecture de la tête du fichier (SPEC_INVALID)", async () => {
+    const github = fakeGithub(BASE_FILES);
+    expect(await codeOf(() => proposeChange(targetOn(BASE_FILES), depsFor(github.client), { path: "specs/orders.spec.md", content: "pas une spec", message: "spec(orders): cassée" }))).toBe("SPEC_INVALID");
+    expect(github.calls.some((call) => call.startsWith("read specs/"))).toBe(false);
+    expect(github.calls.some((call) => call.startsWith("commit"))).toBe(false);
+  });
+});