@ogygie/mcp 0.12.0 → 0.13.1

package/README.md

@@ -4,7 +4,9 @@ Serveur MCP du framework Ogygie : il donne à un espace de conception
 (claude.ai, Claude Desktop, Claude Code) un accès **en lecture** aux fichiers
 de gouvernance et aux features de N repos Ogygie — sans copie, sans recherche
 sémantique, sans connaître le produit. **Le manifeste est l'index** : une
-feature qu'il ne déclare pas n'existe pas.
+feature qu'il ne déclare pas n'existe pas. Depuis la 0.13, il sait aussi
+**proposer** : une spec ou un fichier de décisions devient une pull request,
+jamais un fichier écrit sur l'hôte (D17).
 
 ## Lancement
 
@@ -41,6 +43,8 @@ Sans `--config`, le serveur sert le projet courant sous l'id `local`.
 | `ogygie_read_decisions` | une décision `D<n>`, ou les deux fichiers entiers |
 | `ogygie_read_governance` | `AGENTS.md`, `AGENTS.product.md` ou `FAILURES.md` |
 | `ogygie_read_feature` | les fichiers d'une feature, ou l'un d'eux |
+| `ogygie_impact` | le rayon d'impact d'une feature ou d'un package |
+| `ogygie_propose_change` | (repos avec bloc `github` + jeton) une spec ou un fichier de décisions → commit sur une branche `mcp/…` + pull request |
 
 Chaque réponse porte sa provenance `{ repo, path, ref }` : ce qui a été lu, où,
 et à quel commit.
@@ -54,10 +58,30 @@ qu'un `--host` n'est pas écrit à la main. La synchronisation des clones
 (`git fetch`) est un problème d'hébergement : le serveur lit ce que le disque
 porte, et le date par `ref`.
 
+## Écriture par proposition
+
+Un repo devient écrivable quand son entrée de registre porte ses coordonnées
+GitHub et que l'hôte porte `OGYGIE_MCP_GITHUB_TOKEN` (jeton à portée minimale :
+contenus + pull requests sur les seuls repos servis) :
+
+```json
+{ "id": "mon-produit", "rootPath": "/srv/clones/mon-produit",
+  "github": { "owner": "mon-org", "repo": "mon-produit", "defaultBranch": "main" } }
+```
+
+Périmètre fermé : `specs/<id>.spec.md`, `DECISIONS.md`, `DECISIONS.product.md`.
+Le contenu est validé comme `verify-specs` le ferait (frontmatter, sections,
+références `D<n>`, numérotation des décisions), une spec ne passe jamais
+`implemented` par cette voie, un conflit avec la tête distante est refusé avec
+le contenu à jour, et une seconde proposition sur le même chemin met à jour la
+même pull request. `--write-rate-limit <n>` borne les propositions par repo et
+par heure (20 par défaut). Sans bloc `github` ni jeton, l'outil n'est pas
+listé : un serveur de lecture reste un serveur de lecture.
+
 ## Ce qu'il ne fait pas
 
-Aucune écriture — pas de spec créée ni amendée, pas de commit. Aucune exécution
-de code du repo servi. Aucun accès hors carte : `.env`, secrets et artefacts de
+Aucune écriture sur le disque de l'hôte, aucune écriture hors des specs et des
+décisions, aucun merge. Aucune exécution de code du repo servi. Aucun accès hors carte : `.env`, secrets et artefacts de
 build sont inatteignables par construction, pas par liste noire. Aucun cache :
 chaque lecture touche le disque, la fraîcheur est l'objectif.
 

package/dist/mcp.js

@@ -204,6 +204,104 @@ function createFilesystemRepoAdapter(rootDir) {
   };
 }
 
+// src/github-client.ts
+function createGithubWriteClient(deps, github) {
+  const apiBase = deps.apiBase ?? "https://api.github.com";
+  const repoUrl = `${apiBase}/repos/${github.owner}/${github.repo}`;
+  async function request(method, url, body, allowNotFound) {
+    let response;
+    try {
+      response = await deps.fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${deps.token}`,
+          accept: "application/vnd.github+json",
+          "x-github-api-version": "2022-11-28",
+          "user-agent": "ogygie-mcp",
+          ...body === void 0 ? {} : { "content-type": "application/json" }
+        },
+        ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      });
+    } catch (thrown) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub could not be reached for ${github.owner}/${github.repo}.`,
+        file: null,
+        cause: thrown instanceof Error ? thrown.message : String(thrown),
+        suggestedFix: "Retry once the network is back \u2014 nothing was written, nothing is queued."
+      });
+    }
+    if (response.status === 404 && allowNotFound) return null;
+    if (!response.ok) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub answered ${response.status} for ${method} ${url.replace(apiBase, "")}.`,
+        file: null,
+        cause: `status=${response.status}`,
+        suggestedFix: response.status === 401 || response.status === 403 ? "Check OGYGIE_MCP_GITHUB_TOKEN: it must grant contents and pull requests on this repo." : "Retry later \u2014 nothing was written, nothing is queued."
+      });
+    }
+    return await response.json();
+  }
+  return {
+    async getBranchHead(branch) {
+      const ref = await request(
+        "GET",
+        `${repoUrl}/git/ref/heads/${encodeURIComponent(branch)}`,
+        void 0,
+        true
+      );
+      return ref?.object.sha ?? null;
+    },
+    async readFileAtRef(path, ref) {
+      const file = await request(
+        "GET",
+        `${repoUrl}/contents/${path}?ref=${encodeURIComponent(ref)}`,
+        void 0,
+        true
+      );
+      if (file === null) return null;
+      return { content: Buffer.from(file.content, "base64").toString("utf8"), sha: file.sha };
+    },
+    async createBranch(branch, fromSha) {
+      await request("POST", `${repoUrl}/git/refs`, { ref: `refs/heads/${branch}`, sha: fromSha }, false);
+    },
+    async commitFile(input) {
+      const result = await request(
+        "PUT",
+        `${repoUrl}/contents/${input.path}`,
+        {
+          message: input.message,
+          content: Buffer.from(input.content, "utf8").toString("base64"),
+          branch: input.branch,
+          ...input.expectedSha === null ? {} : { sha: input.expectedSha }
+        },
+        false
+      );
+      return { commitSha: result?.commit.sha ?? "" };
+    },
+    async findOpenPullRequest(branch) {
+      const pulls = await request(
+        "GET",
+        `${repoUrl}/pulls?state=open&head=${encodeURIComponent(`${github.owner}:${branch}`)}`,
+        void 0,
+        false
+      );
+      const first = pulls?.[0];
+      return first === void 0 ? null : { number: first.number, url: first.html_url };
+    },
+    async openPullRequest(input) {
+      const pull = await request(
+        "POST",
+        `${repoUrl}/pulls`,
+        { title: input.title, body: input.body, head: input.branch, base: input.base },
+        false
+      );
+      return { number: pull?.number ?? 0, url: pull?.html_url ?? "" };
+    }
+  };
+}
+
 // ../ogygie-core/src/manifest.schema.ts
 import { z as z3 } from "zod";
 var FeatureNameSchema = z3.string().regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "kebab-case required");
@@ -501,6 +599,14 @@ var SpecFrontmatterSchema = z4.object({
   refs: z4.array(z4.string()).default([]).describe("References to the domain model, e.g. 'modele-gally \xA74.2'"),
   deferred: z4.array(DeferredBehaviorSchema).default([]).describe("Behaviors deferred to a later feature, blocked by name")
 });
+var SECTIONS_SPEC_OBLIGATOIRES = [
+  "# @intent",
+  "# Comportements",
+  "# Contrats de donn\xE9es",
+  "# \xC9tats UI",
+  "# Non-objectifs",
+  "# Budget"
+];
 function splitInlineArrayElements(inner) {
   const elements = [];
   let current = "";
@@ -598,12 +704,19 @@ var GovernanceFileSchema = z5.enum([
   "AGENTS.product.md",
   "FAILURES.md"
 ]);
+var MAX_FILE_BYTES = 2e5;
 var DECISION_FILES = ["DECISIONS.md", "DECISIONS.product.md"];
+var GithubCoordinatesSchema = z5.object({
+  owner: z5.string().min(1),
+  repo: z5.string().min(1),
+  defaultBranch: z5.string().min(1).default("main")
+});
 var RepoRegistrySchema = z5.object({
   repos: z5.array(
     z5.object({
       id: RepoIdSchema,
-      rootPath: z5.string().min(1)
+      rootPath: z5.string().min(1),
+      github: GithubCoordinatesSchema.optional()
     })
   ).min(1)
 });
@@ -624,6 +737,29 @@ var ReadFeatureInput = {
   feature: FeatureNameSchema2,
   file: z5.string().optional()
 };
+var ProposablePathSchema = z5.union([
+  z5.string().regex(/^specs\/(?!_)[a-z][a-z0-9]*(-[a-z0-9]+)*\.spec\.md$/),
+  z5.literal("DECISIONS.md"),
+  z5.literal("DECISIONS.product.md")
+]);
+var ProposeChangeInput = {
+  repo: RepoIdSchema,
+  path: z5.string(),
+  content: z5.string().min(1).max(MAX_FILE_BYTES),
+  message: z5.string().min(10).max(2e3)
+};
+var ProposalSchema = z5.object({
+  repo: RepoIdSchema,
+  path: ProposablePathSchema,
+  branch: z5.string(),
+  baseSha: z5.string(),
+  commitSha: z5.string(),
+  pullRequestNumber: z5.number().int().positive(),
+  pullRequestUrl: z5.string().url(),
+  /** false when an open pull request was updated instead of created. */
+  created: z5.boolean()
+});
+var DEFAULT_WRITE_RATE_LIMIT = 20;
 var RepoInfoSchema = z5.object({
   id: RepoIdSchema,
   /** null when the manifest declares none — the framework's own repo does not. */
@@ -669,9 +805,19 @@ var McpErrorCodeSchema = z5.enum([
   "FILE_NOT_TEXT",
   "PATH_OUTSIDE_REPO",
   "UNAUTHORIZED",
-  "TOKEN_MISSING"
+  "TOKEN_MISSING",
+  // v2 — write by proposal (B10, D17)
+  "GITHUB_TOKEN_MISSING",
+  "WRITE_NOT_CONFIGURED",
+  "WRITE_PATH_FORBIDDEN",
+  "SPEC_INVALID",
+  "SPEC_STATUS_FORBIDDEN",
+  "DECISION_INVALID",
+  "UNKNOWN_DECISION_REFERENCE",
+  "REMOTE_CONFLICT",
+  "WRITE_RATE_LIMITED",
+  "GITHUB_UNAVAILABLE"
 ]);
-var MAX_FILE_BYTES = 2e5;
 var MIN_TOKEN_LENGTH = 32;
 
 // src/registry.ts
@@ -743,7 +889,8 @@ async function openRepos(registry, deps) {
       id: declared.id,
       rootPath: declared.rootPath,
       adapter,
-      ogygieVersion: null
+      ogygieVersion: null,
+      ...declared.github === void 0 ? {} : { github: declared.github }
     };
     const manifest = await readManifest(repo);
     repo.ogygieVersion = manifest.ogygieVersion ?? null;
@@ -778,6 +925,7 @@ function repoOf(repos, repoId) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // ../ogygie-core/src/decision-refs.ts
+var DECISION_REFERENCE = /(?<![A-Za-z0-9])D(\d+)(?![A-Za-z0-9])/g;
 var DECISION_HEADING = /^##\s+D(\d+)\b/;
 function parseKnownDecisionIds(decisionsMarkdown) {
   const ids = [];
@@ -805,6 +953,28 @@ function extractDecisionSection(decisionsMarkdown, decisionId) {
   }
   return start === -1 ? null : trimTrailingBlanks(lines.slice(start));
 }
+function findDecisionReferences(text) {
+  const references = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    for (const match of line.matchAll(DECISION_REFERENCE)) {
+      references.push({ decision: `D${match[1]}`, line: index + 1 });
+    }
+  }
+  return references;
+}
+function findUnknownDecisionReferences(text, knownDecisionIds) {
+  const known = new Set(knownDecisionIds);
+  const unknown = [];
+  const alreadyReported = /* @__PURE__ */ new Set();
+  for (const reference of findDecisionReferences(text)) {
+    if (known.has(reference.decision) || alreadyReported.has(reference.decision)) continue;
+    alreadyReported.add(reference.decision);
+    unknown.push(reference);
+  }
+  return unknown;
+}
 
 // ../ogygie-core/src/impact.ts
 import { z as z6 } from "zod";
@@ -1359,6 +1529,228 @@ async function readFeature(repo, input) {
   };
 }
 
+// src/proposals.ts
+var HOUR_MS = 36e5;
+var DECISION_HEADING2 = /^## D(\d+) — \d{4}-\d{2}-\d{2} — \S/;
+var DECISION_BULLETS = ["**D\xE9cision**", "**Motivation**", "**Exclut**"];
+function specIdOfPath(path) {
+  return path.replace(/^specs\//, "").replace(/\.spec\.md$/, "");
+}
+function validateSpec(path, content) {
+  const parsed = parseSpecFile(content);
+  const problems = [...parsed.problems];
+  if (parsed.frontmatter !== null && parsed.frontmatter.id !== specIdOfPath(path)) {
+    problems.push(`id "${parsed.frontmatter.id}" differs from the file name "${specIdOfPath(path)}"`);
+  }
+  let cursor = 0;
+  for (const section of SECTIONS_SPEC_OBLIGATOIRES) {
+    const position = parsed.body.indexOf(`
+${section}
+`, cursor);
+    if (position === -1) problems.push(`section "${section}" missing or out of order`);
+    else cursor = position + section.length;
+  }
+  if (problems.length > 0) {
+    throwOgygieError({
+      code: "SPEC_INVALID",
+      message: `The proposed spec would fail verify-specs (${problems.length} problem(s)).`,
+      file: path,
+      cause: problems.join(" ; "),
+      suggestedFix: "Fix the frontmatter (id, status, depends_on, priority, refs) and keep the six canonical sections in order."
+    });
+  }
+  if (parsed.frontmatter?.status === "implemented") {
+    throwOgygieError({
+      code: "SPEC_STATUS_FORBIDDEN",
+      message: "A proposal may not declare a spec implemented.",
+      file: path,
+      cause: "status=implemented",
+      suggestedFix: "Propose the spec as draft or validated \u2014 the repo's manifest and CI say when it is implemented."
+    });
+  }
+}
+function validateDecisions(path, content, baseSame, baseOther) {
+  const problems = [];
+  for (const line of content.split("\n")) {
+    if (line.startsWith("## ") && !DECISION_HEADING2.test(line)) {
+      problems.push(`heading "${line}" is not "## D<n> \u2014 AAAA-MM-JJ \u2014 <titre>"`);
+    }
+  }
+  const proposedIds = parseKnownDecisionIds(content);
+  const otherIds = parseKnownDecisionIds(baseOther ?? "");
+  const previousIds = parseKnownDecisionIds(baseSame ?? "");
+  for (const id of previousIds) {
+    if (!proposedIds.includes(id)) problems.push(`${id} was declared and is removed or renumbered`);
+  }
+  const all = [...proposedIds, ...otherIds];
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of all) {
+    if (seen.has(id)) problems.push(`${id} is declared twice across the decision files`);
+    seen.add(id);
+  }
+  const numbers = [...seen].map((id) => Number.parseInt(id.slice(1), 10)).sort((a, b) => a - b);
+  numbers.forEach((value, index) => {
+    if (value !== index + 1) problems.push(`numbering has a gap: expected D${index + 1}, found D${value}`);
+  });
+  for (const id of proposedIds.filter((candidate) => !previousIds.includes(candidate))) {
+    const section = extractDecisionSection(content, id) ?? "";
+    for (const bullet of DECISION_BULLETS) {
+      if (!section.includes(bullet)) problems.push(`${id} lacks its ${bullet} bullet`);
+    }
+  }
+  if (problems.length > 0) {
+    throwOgygieError({
+      code: "DECISION_INVALID",
+      message: `The proposed decisions file breaks the D<n> contract (${problems.length} problem(s)).`,
+      file: path,
+      cause: problems.join(" ; "),
+      suggestedFix: "Keep every existing decision, number the new one right after the last across both files, and give it its D\xE9cision / Motivation / Exclut bullets."
+    });
+  }
+}
+function checkDecisionReferences(path, content, known) {
+  const unknown = findUnknownDecisionReferences(content, known);
+  if (unknown.length > 0) {
+    throwOgygieError({
+      code: "UNKNOWN_DECISION_REFERENCE",
+      message: `The proposal cites ${unknown.length} decision(s) the repo does not declare.`,
+      file: path,
+      cause: unknown.map((reference) => `${reference.decision} (line ${reference.line})`).join(", "),
+      suggestedFix: `Cite only declared decisions (${known.join(", ") || "<none>"}), or propose the decision first.`
+    });
+  }
+}
+function branchSlug(path) {
+  return path.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+async function withGithub(action) {
+  try {
+    return await action();
+  } catch (thrown) {
+    if (thrown instanceof OgygieFailure) throw thrown;
+    return throwOgygieError({
+      code: "GITHUB_UNAVAILABLE",
+      message: "The GitHub client failed outside its contract.",
+      file: null,
+      cause: thrown instanceof Error ? thrown.message : String(thrown),
+      suggestedFix: "Retry \u2014 nothing was written, nothing is queued."
+    });
+  }
+}
+async function proposeChange(repo, deps, input) {
+  const path = ProposablePathSchema.safeParse(input.path);
+  if (!path.success) {
+    throwOgygieError({
+      code: "WRITE_PATH_FORBIDDEN",
+      message: `"${input.path}" is outside what a proposal may touch.`,
+      file: input.path,
+      cause: "the perimeter is specs/<id>.spec.md (not the template), DECISIONS.md, DECISIONS.product.md",
+      suggestedFix: "Propose a spec or a decisions file; code, manifest, governed files and FAILURES.md are out of reach (D17)."
+    });
+  }
+  const github = repo.github;
+  if (github === void 0) {
+    return throwOgygieError({
+      code: "WRITE_NOT_CONFIGURED",
+      message: `Repo "${repo.id}" declares no GitHub coordinates: it is read-only.`,
+      file: null,
+      cause: "registry entry without a `github` block",
+      suggestedFix: 'Add `"github": { "owner": "\u2026", "repo": "\u2026", "defaultBranch": "main" }` to that repo in the registry.'
+    });
+  }
+  const now = deps.now();
+  const recent = (deps.recentProposals.get(repo.id) ?? []).filter((at) => now - at < HOUR_MS);
+  if (recent.length >= deps.rateLimitPerHour) {
+    const retryAfterSeconds = Math.ceil(((recent[0] ?? now) + HOUR_MS - now) / 1e3);
+    throwOgygieError({
+      code: "WRITE_RATE_LIMITED",
+      message: `Repo "${repo.id}" already received ${recent.length} proposals this hour.`,
+      file: null,
+      cause: `limit=${deps.rateLimitPerHour}/hour`,
+      suggestedFix: `Retry in ${retryAfterSeconds} s, or merge or close the open proposals first.`
+    });
+  }
+  const client = deps.clientFor(github);
+  const baseSha = await withGithub(() => client.getBranchHead(github.defaultBranch));
+  if (baseSha === null) {
+    return throwOgygieError({
+      code: "GITHUB_UNAVAILABLE",
+      message: `Branch "${github.defaultBranch}" does not exist on ${github.owner}/${github.repo}.`,
+      file: null,
+      cause: "default branch head not found",
+      suggestedFix: "Fix `defaultBranch` in the registry entry of that repo."
+    });
+  }
+  const baseFiles = /* @__PURE__ */ new Map();
+  for (const decisionsPath of DECISION_FILES) {
+    const file = await withGithub(() => client.readFileAtRef(decisionsPath, baseSha));
+    baseFiles.set(decisionsPath, file?.content ?? null);
+  }
+  if (input.path.startsWith("specs/")) {
+    validateSpec(input.path, input.content);
+    const known = DECISION_FILES.flatMap((file) => parseKnownDecisionIds(baseFiles.get(file) ?? ""));
+    checkDecisionReferences(input.path, input.content, known);
+  } else {
+    const other = DECISION_FILES.find((file) => file !== input.path) ?? DECISION_FILES[1];
+    validateDecisions(input.path, input.content, baseFiles.get(input.path) ?? null, baseFiles.get(other) ?? null);
+    const known = [...parseKnownDecisionIds(input.content), ...parseKnownDecisionIds(baseFiles.get(other) ?? "")];
+    checkDecisionReferences(input.path, input.content, known);
+  }
+  const headFile = await withGithub(() => client.readFileAtRef(input.path, baseSha));
+  const local = await repo.adapter.exists(input.path) ? await repo.adapter.readFile(input.path) : null;
+  if ((headFile?.content ?? null) !== local) {
+    throwOgygieError({
+      code: "REMOTE_CONFLICT",
+      message: `"${input.path}" changed on ${github.defaultBranch} since the served clone was read.`,
+      file: input.path,
+      cause: `head sha=${headFile?.sha ?? "<absent>"}, served clone ${local === null ? "has no such file" : "differs"}`,
+      suggestedFix: "Re-read the file (details.headContent is the current head), reapply your change and propose again.",
+      details: { headSha: headFile?.sha ?? null, headContent: headFile?.content ?? null }
+    });
+  }
+  let branch = `mcp/${repo.id}/${branchSlug(input.path)}`;
+  let branchHead = await withGithub(() => client.getBranchHead(branch));
+  let openPull = branchHead === null ? null : await withGithub(() => client.findOpenPullRequest(branch));
+  if (branchHead !== null && openPull === null) {
+    branch = `${branch}-${baseSha.slice(0, 7)}`;
+    branchHead = await withGithub(() => client.getBranchHead(branch));
+    openPull = branchHead === null ? null : await withGithub(() => client.findOpenPullRequest(branch));
+  }
+  recent.push(now);
+  deps.recentProposals.set(repo.id, recent);
+  let expectedSha = headFile?.sha ?? null;
+  if (branchHead === null) {
+    await withGithub(() => client.createBranch(branch, baseSha));
+  } else {
+    const onBranch = await withGithub(() => client.readFileAtRef(input.path, branchHead ?? baseSha));
+    expectedSha = onBranch?.sha ?? null;
+  }
+  const commit = await withGithub(
+    () => client.commitFile({ branch, path: input.path, content: input.content, message: input.message, expectedSha })
+  );
+  const pull = openPull ?? await withGithub(
+    () => client.openPullRequest({
+      branch,
+      base: github.defaultBranch,
+      title: (input.message.split("\n")[0] ?? input.message).slice(0, 72),
+      body: `${input.message}
+
+---
+Propos\xE9 via @ogygie/mcp par ${deps.clientName()} (repo \`${repo.id}\`, chemin \`${input.path}\`).`
+    })
+  );
+  return {
+    repo: repo.id,
+    path: path.data,
+    branch,
+    baseSha,
+    commitSha: commit.commitSha,
+    pullRequestNumber: pull.number,
+    pullRequestUrl: pull.url,
+    created: openPull === null
+  };
+}
+
 // src/server.ts
 function asText(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
@@ -1385,26 +1777,25 @@ function createOgygieMcpServer(deps) {
       { description, inputSchema },
       (async (input) => {
         const startedAt = Date.now();
-        try {
-          const result = await run(input);
+        const audit = (outcome, result) => {
+          const prUrl = result?.pullRequestUrl;
           deps.log?.(
             JSON.stringify({
               tool: name,
               repo: input["repo"] ?? null,
-              outcome: "ok",
+              ...typeof input["path"] === "string" ? { path: input["path"] } : {},
+              outcome,
+              ...typeof prUrl === "string" ? { prUrl } : {},
               durationMs: Date.now() - startedAt
             })
           );
+        };
+        try {
+          const result = await run(input);
+          audit("ok", result);
           return asText(result);
         } catch (thrown) {
-          deps.log?.(
-            JSON.stringify({
-              tool: name,
-              repo: input["repo"] ?? null,
-              outcome: thrown instanceof OgygieFailure ? thrown.error.code : "UNEXPECTED",
-              durationMs: Date.now() - startedAt
-            })
-          );
+          audit(thrown instanceof OgygieFailure ? thrown.error.code : "UNEXPECTED");
           return asError(thrown);
         }
       })
@@ -1458,6 +1849,23 @@ function createOgygieMcpServer(deps) {
     ReadFeatureInput,
     async (input) => readFeature(repoOf(deps.repos, input.repo), input)
   );
+  const writable = deps.repos.some((repo) => repo.github !== void 0);
+  if (deps.write !== void 0 && writable) {
+    const write = deps.write;
+    register(
+      "ogygie_propose_change",
+      "Proposes a spec (specs/<id>.spec.md) or a decisions file (DECISIONS.md, DECISIONS.product.md) as a commit on a mcp/ branch plus a pull request \u2014 never a file on the host. Validated like verify-specs first; refuses status implemented.",
+      ProposeChangeInput,
+      async (input) => proposeChange(
+        repoOf(deps.repos, input.repo),
+        {
+          ...write,
+          clientName: () => server.server.getClientVersion()?.name ?? "unknown-client"
+        },
+        input
+      )
+    );
+  }
   return server;
 }
 
@@ -1573,13 +1981,21 @@ async function startHttpTransport(createServerInstance, options) {
 
 // src/main.ts
 function parseArguments(argv) {
-  const options = { configPath: null, http: false, port: 3010, host: void 0 };
+  const options = {
+    configPath: null,
+    http: false,
+    port: 3010,
+    host: void 0,
+    writeRateLimit: DEFAULT_WRITE_RATE_LIMIT
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--config") options.configPath = argv[++index] ?? null;
     else if (argument === "--http") options.http = true;
     else if (argument === "--port") options.port = Number.parseInt(argv[++index] ?? "", 10);
     else if (argument === "--host") options.host = argv[++index];
+    else if (argument === "--write-rate-limit")
+      options.writeRateLimit = Number.parseInt(argv[++index] ?? "", 10) || DEFAULT_WRITE_RATE_LIMIT;
   }
   return options;
 }
@@ -1624,11 +2040,29 @@ async function startOgygieMcp(options) {
     openRepo: (rootPath) => createFilesystemRepoAdapter(resolve2(options.cwd, rootPath)),
     serverVersion: options.version
   });
+  const writableRepos = repos.filter((repo) => repo.github !== void 0);
+  if (writableRepos.length > 0 && options.githubToken === void 0) {
+    throwOgygieError({
+      code: "GITHUB_TOKEN_MISSING",
+      message: `${writableRepos.length} repo(s) declare GitHub coordinates but OGYGIE_MCP_GITHUB_TOKEN is absent.`,
+      file: null,
+      cause: `writable repos: ${writableRepos.map((repo) => repo.id).join(", ")}`,
+      suggestedFix: "Set OGYGIE_MCP_GITHUB_TOKEN (a token scoped to contents + pull requests on those repos), or remove the `github` blocks to serve read-only."
+    });
+  }
+  const githubToken = options.githubToken;
+  const write = githubToken === void 0 ? void 0 : {
+    clientFor: (github) => createGithubWriteClient({ token: githubToken, fetchImpl: fetch }, github),
+    now: () => Date.now(),
+    rateLimitPerHour: parsed.writeRateLimit,
+    recentProposals: /* @__PURE__ */ new Map()
+  };
   const buildServer = () => createOgygieMcpServer({
     repos,
     version: options.version,
     log: (line) => process.stderr.write(`${line}
-`)
+`),
+    ...write === void 0 ? {} : { write }
   });
   if (!parsed.http) {
     const server = buildServer();
@@ -1641,7 +2075,7 @@ async function startOgygieMcp(options) {
     token: options.token
   });
   process.stderr.write(
-    `ogygie-mcp \u2014 HTTP sur ${parsed.host ?? "127.0.0.1"}:${running.port}, ${repos.length} repo(s).
+    `ogygie-mcp \u2014 HTTP sur ${parsed.host ?? "127.0.0.1"}:${running.port}, ${repos.length} repo(s), ${writableRepos.length} accepting proposals.
 `
   );
   return { close: () => running.close() };
@@ -1660,6 +2094,7 @@ try {
     cwd: process.cwd(),
     version: ownVersion(),
     token: process.env["OGYGIE_MCP_TOKEN"],
+    githubToken: process.env["OGYGIE_MCP_GITHUB_TOKEN"],
     // The one disk read that does not go through a RepoAdapter, injected from
     // here so no serving module has to import `node:fs` (B5).
     readConfigFile: (absolutePath) => readFileSync(absolutePath, "utf8")

package/dist/server.js

@@ -199,6 +199,104 @@ function createFilesystemRepoAdapter(rootDir) {
   };
 }
 
+// src/github-client.ts
+function createGithubWriteClient(deps, github) {
+  const apiBase = deps.apiBase ?? "https://api.github.com";
+  const repoUrl = `${apiBase}/repos/${github.owner}/${github.repo}`;
+  async function request(method, url, body, allowNotFound) {
+    let response;
+    try {
+      response = await deps.fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${deps.token}`,
+          accept: "application/vnd.github+json",
+          "x-github-api-version": "2022-11-28",
+          "user-agent": "ogygie-mcp",
+          ...body === void 0 ? {} : { "content-type": "application/json" }
+        },
+        ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      });
+    } catch (thrown) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub could not be reached for ${github.owner}/${github.repo}.`,
+        file: null,
+        cause: thrown instanceof Error ? thrown.message : String(thrown),
+        suggestedFix: "Retry once the network is back \u2014 nothing was written, nothing is queued."
+      });
+    }
+    if (response.status === 404 && allowNotFound) return null;
+    if (!response.ok) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub answered ${response.status} for ${method} ${url.replace(apiBase, "")}.`,
+        file: null,
+        cause: `status=${response.status}`,
+        suggestedFix: response.status === 401 || response.status === 403 ? "Check OGYGIE_MCP_GITHUB_TOKEN: it must grant contents and pull requests on this repo." : "Retry later \u2014 nothing was written, nothing is queued."
+      });
+    }
+    return await response.json();
+  }
+  return {
+    async getBranchHead(branch) {
+      const ref = await request(
+        "GET",
+        `${repoUrl}/git/ref/heads/${encodeURIComponent(branch)}`,
+        void 0,
+        true
+      );
+      return ref?.object.sha ?? null;
+    },
+    async readFileAtRef(path, ref) {
+      const file = await request(
+        "GET",
+        `${repoUrl}/contents/${path}?ref=${encodeURIComponent(ref)}`,
+        void 0,
+        true
+      );
+      if (file === null) return null;
+      return { content: Buffer.from(file.content, "base64").toString("utf8"), sha: file.sha };
+    },
+    async createBranch(branch, fromSha) {
+      await request("POST", `${repoUrl}/git/refs`, { ref: `refs/heads/${branch}`, sha: fromSha }, false);
+    },
+    async commitFile(input) {
+      const result = await request(
+        "PUT",
+        `${repoUrl}/contents/${input.path}`,
+        {
+          message: input.message,
+          content: Buffer.from(input.content, "utf8").toString("base64"),
+          branch: input.branch,
+          ...input.expectedSha === null ? {} : { sha: input.expectedSha }
+        },
+        false
+      );
+      return { commitSha: result?.commit.sha ?? "" };
+    },
+    async findOpenPullRequest(branch) {
+      const pulls = await request(
+        "GET",
+        `${repoUrl}/pulls?state=open&head=${encodeURIComponent(`${github.owner}:${branch}`)}`,
+        void 0,
+        false
+      );
+      const first = pulls?.[0];
+      return first === void 0 ? null : { number: first.number, url: first.html_url };
+    },
+    async openPullRequest(input) {
+      const pull = await request(
+        "POST",
+        `${repoUrl}/pulls`,
+        { title: input.title, body: input.body, head: input.branch, base: input.base },
+        false
+      );
+      return { number: pull?.number ?? 0, url: pull?.html_url ?? "" };
+    }
+  };
+}
+
 // ../ogygie-core/src/manifest.schema.ts
 import { z as z3 } from "zod";
 var FeatureNameSchema = z3.string().regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "kebab-case required");
@@ -496,6 +594,14 @@ var SpecFrontmatterSchema = z4.object({
   refs: z4.array(z4.string()).default([]).describe("References to the domain model, e.g. 'modele-gally \xA74.2'"),
   deferred: z4.array(DeferredBehaviorSchema).default([]).describe("Behaviors deferred to a later feature, blocked by name")
 });
+var SECTIONS_SPEC_OBLIGATOIRES = [
+  "# @intent",
+  "# Comportements",
+  "# Contrats de donn\xE9es",
+  "# \xC9tats UI",
+  "# Non-objectifs",
+  "# Budget"
+];
 function splitInlineArrayElements(inner) {
   const elements = [];
   let current = "";
@@ -593,12 +699,19 @@ var GovernanceFileSchema = z5.enum([
   "AGENTS.product.md",
   "FAILURES.md"
 ]);
+var MAX_FILE_BYTES = 2e5;
 var DECISION_FILES = ["DECISIONS.md", "DECISIONS.product.md"];
+var GithubCoordinatesSchema = z5.object({
+  owner: z5.string().min(1),
+  repo: z5.string().min(1),
+  defaultBranch: z5.string().min(1).default("main")
+});
 var RepoRegistrySchema = z5.object({
   repos: z5.array(
     z5.object({
       id: RepoIdSchema,
-      rootPath: z5.string().min(1)
+      rootPath: z5.string().min(1),
+      github: GithubCoordinatesSchema.optional()
     })
   ).min(1)
 });
@@ -619,6 +732,29 @@ var ReadFeatureInput = {
   feature: FeatureNameSchema2,
   file: z5.string().optional()
 };
+var ProposablePathSchema = z5.union([
+  z5.string().regex(/^specs\/(?!_)[a-z][a-z0-9]*(-[a-z0-9]+)*\.spec\.md$/),
+  z5.literal("DECISIONS.md"),
+  z5.literal("DECISIONS.product.md")
+]);
+var ProposeChangeInput = {
+  repo: RepoIdSchema,
+  path: z5.string(),
+  content: z5.string().min(1).max(MAX_FILE_BYTES),
+  message: z5.string().min(10).max(2e3)
+};
+var ProposalSchema = z5.object({
+  repo: RepoIdSchema,
+  path: ProposablePathSchema,
+  branch: z5.string(),
+  baseSha: z5.string(),
+  commitSha: z5.string(),
+  pullRequestNumber: z5.number().int().positive(),
+  pullRequestUrl: z5.string().url(),
+  /** false when an open pull request was updated instead of created. */
+  created: z5.boolean()
+});
+var DEFAULT_WRITE_RATE_LIMIT = 20;
 var RepoInfoSchema = z5.object({
   id: RepoIdSchema,
   /** null when the manifest declares none — the framework's own repo does not. */
@@ -664,9 +800,19 @@ var McpErrorCodeSchema = z5.enum([
   "FILE_NOT_TEXT",
   "PATH_OUTSIDE_REPO",
   "UNAUTHORIZED",
-  "TOKEN_MISSING"
+  "TOKEN_MISSING",
+  // v2 — write by proposal (B10, D17)
+  "GITHUB_TOKEN_MISSING",
+  "WRITE_NOT_CONFIGURED",
+  "WRITE_PATH_FORBIDDEN",
+  "SPEC_INVALID",
+  "SPEC_STATUS_FORBIDDEN",
+  "DECISION_INVALID",
+  "UNKNOWN_DECISION_REFERENCE",
+  "REMOTE_CONFLICT",
+  "WRITE_RATE_LIMITED",
+  "GITHUB_UNAVAILABLE"
 ]);
-var MAX_FILE_BYTES = 2e5;
 var MIN_TOKEN_LENGTH = 32;
 
 // src/registry.ts
@@ -738,7 +884,8 @@ async function openRepos(registry, deps) {
       id: declared.id,
       rootPath: declared.rootPath,
       adapter,
-      ogygieVersion: null
+      ogygieVersion: null,
+      ...declared.github === void 0 ? {} : { github: declared.github }
     };
     const manifest = await readManifest(repo);
     repo.ogygieVersion = manifest.ogygieVersion ?? null;
@@ -773,6 +920,7 @@ function repoOf(repos, repoId) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // ../ogygie-core/src/decision-refs.ts
+var DECISION_REFERENCE = /(?<![A-Za-z0-9])D(\d+)(?![A-Za-z0-9])/g;
 var DECISION_HEADING = /^##\s+D(\d+)\b/;
 function parseKnownDecisionIds(decisionsMarkdown) {
   const ids = [];
@@ -800,6 +948,28 @@ function extractDecisionSection(decisionsMarkdown, decisionId) {
   }
   return start === -1 ? null : trimTrailingBlanks(lines.slice(start));
 }
+function findDecisionReferences(text) {
+  const references = [];
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    for (const match of line.matchAll(DECISION_REFERENCE)) {
+      references.push({ decision: `D${match[1]}`, line: index + 1 });
+    }
+  }
+  return references;
+}
+function findUnknownDecisionReferences(text, knownDecisionIds) {
+  const known = new Set(knownDecisionIds);
+  const unknown = [];
+  const alreadyReported = /* @__PURE__ */ new Set();
+  for (const reference of findDecisionReferences(text)) {
+    if (known.has(reference.decision) || alreadyReported.has(reference.decision)) continue;
+    alreadyReported.add(reference.decision);
+    unknown.push(reference);
+  }
+  return unknown;
+}
 
 // ../ogygie-core/src/impact.ts
 import { z as z6 } from "zod";
@@ -1354,6 +1524,228 @@ async function readFeature(repo, input) {
   };
 }
 
+// src/proposals.ts
+var HOUR_MS = 36e5;
+var DECISION_HEADING2 = /^## D(\d+) — \d{4}-\d{2}-\d{2} — \S/;
+var DECISION_BULLETS = ["**D\xE9cision**", "**Motivation**", "**Exclut**"];
+function specIdOfPath(path) {
+  return path.replace(/^specs\//, "").replace(/\.spec\.md$/, "");
+}
+function validateSpec(path, content) {
+  const parsed = parseSpecFile(content);
+  const problems = [...parsed.problems];
+  if (parsed.frontmatter !== null && parsed.frontmatter.id !== specIdOfPath(path)) {
+    problems.push(`id "${parsed.frontmatter.id}" differs from the file name "${specIdOfPath(path)}"`);
+  }
+  let cursor = 0;
+  for (const section of SECTIONS_SPEC_OBLIGATOIRES) {
+    const position = parsed.body.indexOf(`
+${section}
+`, cursor);
+    if (position === -1) problems.push(`section "${section}" missing or out of order`);
+    else cursor = position + section.length;
+  }
+  if (problems.length > 0) {
+    throwOgygieError({
+      code: "SPEC_INVALID",
+      message: `The proposed spec would fail verify-specs (${problems.length} problem(s)).`,
+      file: path,
+      cause: problems.join(" ; "),
+      suggestedFix: "Fix the frontmatter (id, status, depends_on, priority, refs) and keep the six canonical sections in order."
+    });
+  }
+  if (parsed.frontmatter?.status === "implemented") {
+    throwOgygieError({
+      code: "SPEC_STATUS_FORBIDDEN",
+      message: "A proposal may not declare a spec implemented.",
+      file: path,
+      cause: "status=implemented",
+      suggestedFix: "Propose the spec as draft or validated \u2014 the repo's manifest and CI say when it is implemented."
+    });
+  }
+}
+function validateDecisions(path, content, baseSame, baseOther) {
+  const problems = [];
+  for (const line of content.split("\n")) {
+    if (line.startsWith("## ") && !DECISION_HEADING2.test(line)) {
+      problems.push(`heading "${line}" is not "## D<n> \u2014 AAAA-MM-JJ \u2014 <titre>"`);
+    }
+  }
+  const proposedIds = parseKnownDecisionIds(content);
+  const otherIds = parseKnownDecisionIds(baseOther ?? "");
+  const previousIds = parseKnownDecisionIds(baseSame ?? "");
+  for (const id of previousIds) {
+    if (!proposedIds.includes(id)) problems.push(`${id} was declared and is removed or renumbered`);
+  }
+  const all = [...proposedIds, ...otherIds];
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of all) {
+    if (seen.has(id)) problems.push(`${id} is declared twice across the decision files`);
+    seen.add(id);
+  }
+  const numbers = [...seen].map((id) => Number.parseInt(id.slice(1), 10)).sort((a, b) => a - b);
+  numbers.forEach((value, index) => {
+    if (value !== index + 1) problems.push(`numbering has a gap: expected D${index + 1}, found D${value}`);
+  });
+  for (const id of proposedIds.filter((candidate) => !previousIds.includes(candidate))) {
+    const section = extractDecisionSection(content, id) ?? "";
+    for (const bullet of DECISION_BULLETS) {
+      if (!section.includes(bullet)) problems.push(`${id} lacks its ${bullet} bullet`);
+    }
+  }
+  if (problems.length > 0) {
+    throwOgygieError({
+      code: "DECISION_INVALID",
+      message: `The proposed decisions file breaks the D<n> contract (${problems.length} problem(s)).`,
+      file: path,
+      cause: problems.join(" ; "),
+      suggestedFix: "Keep every existing decision, number the new one right after the last across both files, and give it its D\xE9cision / Motivation / Exclut bullets."
+    });
+  }
+}
+function checkDecisionReferences(path, content, known) {
+  const unknown = findUnknownDecisionReferences(content, known);
+  if (unknown.length > 0) {
+    throwOgygieError({
+      code: "UNKNOWN_DECISION_REFERENCE",
+      message: `The proposal cites ${unknown.length} decision(s) the repo does not declare.`,
+      file: path,
+      cause: unknown.map((reference) => `${reference.decision} (line ${reference.line})`).join(", "),
+      suggestedFix: `Cite only declared decisions (${known.join(", ") || "<none>"}), or propose the decision first.`
+    });
+  }
+}
+function branchSlug(path) {
+  return path.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+async function withGithub(action) {
+  try {
+    return await action();
+  } catch (thrown) {
+    if (thrown instanceof OgygieFailure) throw thrown;
+    return throwOgygieError({
+      code: "GITHUB_UNAVAILABLE",
+      message: "The GitHub client failed outside its contract.",
+      file: null,
+      cause: thrown instanceof Error ? thrown.message : String(thrown),
+      suggestedFix: "Retry \u2014 nothing was written, nothing is queued."
+    });
+  }
+}
+async function proposeChange(repo, deps, input) {
+  const path = ProposablePathSchema.safeParse(input.path);
+  if (!path.success) {
+    throwOgygieError({
+      code: "WRITE_PATH_FORBIDDEN",
+      message: `"${input.path}" is outside what a proposal may touch.`,
+      file: input.path,
+      cause: "the perimeter is specs/<id>.spec.md (not the template), DECISIONS.md, DECISIONS.product.md",
+      suggestedFix: "Propose a spec or a decisions file; code, manifest, governed files and FAILURES.md are out of reach (D17)."
+    });
+  }
+  const github = repo.github;
+  if (github === void 0) {
+    return throwOgygieError({
+      code: "WRITE_NOT_CONFIGURED",
+      message: `Repo "${repo.id}" declares no GitHub coordinates: it is read-only.`,
+      file: null,
+      cause: "registry entry without a `github` block",
+      suggestedFix: 'Add `"github": { "owner": "\u2026", "repo": "\u2026", "defaultBranch": "main" }` to that repo in the registry.'
+    });
+  }
+  const now = deps.now();
+  const recent = (deps.recentProposals.get(repo.id) ?? []).filter((at) => now - at < HOUR_MS);
+  if (recent.length >= deps.rateLimitPerHour) {
+    const retryAfterSeconds = Math.ceil(((recent[0] ?? now) + HOUR_MS - now) / 1e3);
+    throwOgygieError({
+      code: "WRITE_RATE_LIMITED",
+      message: `Repo "${repo.id}" already received ${recent.length} proposals this hour.`,
+      file: null,
+      cause: `limit=${deps.rateLimitPerHour}/hour`,
+      suggestedFix: `Retry in ${retryAfterSeconds} s, or merge or close the open proposals first.`
+    });
+  }
+  const client = deps.clientFor(github);
+  const baseSha = await withGithub(() => client.getBranchHead(github.defaultBranch));
+  if (baseSha === null) {
+    return throwOgygieError({
+      code: "GITHUB_UNAVAILABLE",
+      message: `Branch "${github.defaultBranch}" does not exist on ${github.owner}/${github.repo}.`,
+      file: null,
+      cause: "default branch head not found",
+      suggestedFix: "Fix `defaultBranch` in the registry entry of that repo."
+    });
+  }
+  const baseFiles = /* @__PURE__ */ new Map();
+  for (const decisionsPath of DECISION_FILES) {
+    const file = await withGithub(() => client.readFileAtRef(decisionsPath, baseSha));
+    baseFiles.set(decisionsPath, file?.content ?? null);
+  }
+  if (input.path.startsWith("specs/")) {
+    validateSpec(input.path, input.content);
+    const known = DECISION_FILES.flatMap((file) => parseKnownDecisionIds(baseFiles.get(file) ?? ""));
+    checkDecisionReferences(input.path, input.content, known);
+  } else {
+    const other = DECISION_FILES.find((file) => file !== input.path) ?? DECISION_FILES[1];
+    validateDecisions(input.path, input.content, baseFiles.get(input.path) ?? null, baseFiles.get(other) ?? null);
+    const known = [...parseKnownDecisionIds(input.content), ...parseKnownDecisionIds(baseFiles.get(other) ?? "")];
+    checkDecisionReferences(input.path, input.content, known);
+  }
+  const headFile = await withGithub(() => client.readFileAtRef(input.path, baseSha));
+  const local = await repo.adapter.exists(input.path) ? await repo.adapter.readFile(input.path) : null;
+  if ((headFile?.content ?? null) !== local) {
+    throwOgygieError({
+      code: "REMOTE_CONFLICT",
+      message: `"${input.path}" changed on ${github.defaultBranch} since the served clone was read.`,
+      file: input.path,
+      cause: `head sha=${headFile?.sha ?? "<absent>"}, served clone ${local === null ? "has no such file" : "differs"}`,
+      suggestedFix: "Re-read the file (details.headContent is the current head), reapply your change and propose again.",
+      details: { headSha: headFile?.sha ?? null, headContent: headFile?.content ?? null }
+    });
+  }
+  let branch = `mcp/${repo.id}/${branchSlug(input.path)}`;
+  let branchHead = await withGithub(() => client.getBranchHead(branch));
+  let openPull = branchHead === null ? null : await withGithub(() => client.findOpenPullRequest(branch));
+  if (branchHead !== null && openPull === null) {
+    branch = `${branch}-${baseSha.slice(0, 7)}`;
+    branchHead = await withGithub(() => client.getBranchHead(branch));
+    openPull = branchHead === null ? null : await withGithub(() => client.findOpenPullRequest(branch));
+  }
+  recent.push(now);
+  deps.recentProposals.set(repo.id, recent);
+  let expectedSha = headFile?.sha ?? null;
+  if (branchHead === null) {
+    await withGithub(() => client.createBranch(branch, baseSha));
+  } else {
+    const onBranch = await withGithub(() => client.readFileAtRef(input.path, branchHead ?? baseSha));
+    expectedSha = onBranch?.sha ?? null;
+  }
+  const commit = await withGithub(
+    () => client.commitFile({ branch, path: input.path, content: input.content, message: input.message, expectedSha })
+  );
+  const pull = openPull ?? await withGithub(
+    () => client.openPullRequest({
+      branch,
+      base: github.defaultBranch,
+      title: (input.message.split("\n")[0] ?? input.message).slice(0, 72),
+      body: `${input.message}
+
+---
+Propos\xE9 via @ogygie/mcp par ${deps.clientName()} (repo \`${repo.id}\`, chemin \`${input.path}\`).`
+    })
+  );
+  return {
+    repo: repo.id,
+    path: path.data,
+    branch,
+    baseSha,
+    commitSha: commit.commitSha,
+    pullRequestNumber: pull.number,
+    pullRequestUrl: pull.url,
+    created: openPull === null
+  };
+}
+
 // src/server.ts
 function asText(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
@@ -1380,26 +1772,25 @@ function createOgygieMcpServer(deps) {
       { description, inputSchema },
       (async (input) => {
         const startedAt = Date.now();
-        try {
-          const result = await run(input);
+        const audit = (outcome, result) => {
+          const prUrl = result?.pullRequestUrl;
           deps.log?.(
             JSON.stringify({
               tool: name,
               repo: input["repo"] ?? null,
-              outcome: "ok",
+              ...typeof input["path"] === "string" ? { path: input["path"] } : {},
+              outcome,
+              ...typeof prUrl === "string" ? { prUrl } : {},
               durationMs: Date.now() - startedAt
             })
           );
+        };
+        try {
+          const result = await run(input);
+          audit("ok", result);
           return asText(result);
         } catch (thrown) {
-          deps.log?.(
-            JSON.stringify({
-              tool: name,
-              repo: input["repo"] ?? null,
-              outcome: thrown instanceof OgygieFailure ? thrown.error.code : "UNEXPECTED",
-              durationMs: Date.now() - startedAt
-            })
-          );
+          audit(thrown instanceof OgygieFailure ? thrown.error.code : "UNEXPECTED");
           return asError(thrown);
         }
       })
@@ -1453,6 +1844,23 @@ function createOgygieMcpServer(deps) {
     ReadFeatureInput,
     async (input) => readFeature(repoOf(deps.repos, input.repo), input)
   );
+  const writable = deps.repos.some((repo) => repo.github !== void 0);
+  if (deps.write !== void 0 && writable) {
+    const write = deps.write;
+    register(
+      "ogygie_propose_change",
+      "Proposes a spec (specs/<id>.spec.md) or a decisions file (DECISIONS.md, DECISIONS.product.md) as a commit on a mcp/ branch plus a pull request \u2014 never a file on the host. Validated like verify-specs first; refuses status implemented.",
+      ProposeChangeInput,
+      async (input) => proposeChange(
+        repoOf(deps.repos, input.repo),
+        {
+          ...write,
+          clientName: () => server.server.getClientVersion()?.name ?? "unknown-client"
+        },
+        input
+      )
+    );
+  }
   return server;
 }
 
@@ -1568,13 +1976,21 @@ async function startHttpTransport(createServerInstance, options) {
 
 // src/main.ts
 function parseArguments(argv) {
-  const options = { configPath: null, http: false, port: 3010, host: void 0 };
+  const options = {
+    configPath: null,
+    http: false,
+    port: 3010,
+    host: void 0,
+    writeRateLimit: DEFAULT_WRITE_RATE_LIMIT
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === "--config") options.configPath = argv[++index] ?? null;
     else if (argument === "--http") options.http = true;
     else if (argument === "--port") options.port = Number.parseInt(argv[++index] ?? "", 10);
     else if (argument === "--host") options.host = argv[++index];
+    else if (argument === "--write-rate-limit")
+      options.writeRateLimit = Number.parseInt(argv[++index] ?? "", 10) || DEFAULT_WRITE_RATE_LIMIT;
   }
   return options;
 }
@@ -1619,11 +2035,29 @@ async function startOgygieMcp(options) {
     openRepo: (rootPath) => createFilesystemRepoAdapter(resolve2(options.cwd, rootPath)),
     serverVersion: options.version
   });
+  const writableRepos = repos.filter((repo) => repo.github !== void 0);
+  if (writableRepos.length > 0 && options.githubToken === void 0) {
+    throwOgygieError({
+      code: "GITHUB_TOKEN_MISSING",
+      message: `${writableRepos.length} repo(s) declare GitHub coordinates but OGYGIE_MCP_GITHUB_TOKEN is absent.`,
+      file: null,
+      cause: `writable repos: ${writableRepos.map((repo) => repo.id).join(", ")}`,
+      suggestedFix: "Set OGYGIE_MCP_GITHUB_TOKEN (a token scoped to contents + pull requests on those repos), or remove the `github` blocks to serve read-only."
+    });
+  }
+  const githubToken = options.githubToken;
+  const write = githubToken === void 0 ? void 0 : {
+    clientFor: (github) => createGithubWriteClient({ token: githubToken, fetchImpl: fetch }, github),
+    now: () => Date.now(),
+    rateLimitPerHour: parsed.writeRateLimit,
+    recentProposals: /* @__PURE__ */ new Map()
+  };
   const buildServer = () => createOgygieMcpServer({
     repos,
     version: options.version,
     log: (line) => process.stderr.write(`${line}
-`)
+`),
+    ...write === void 0 ? {} : { write }
   });
   if (!parsed.http) {
     const server = buildServer();
@@ -1636,7 +2070,7 @@ async function startOgygieMcp(options) {
     token: options.token
   });
   process.stderr.write(
-    `ogygie-mcp \u2014 HTTP sur ${parsed.host ?? "127.0.0.1"}:${running.port}, ${repos.length} repo(s).
+    `ogygie-mcp \u2014 HTTP sur ${parsed.host ?? "127.0.0.1"}:${running.port}, ${repos.length} repo(s), ${writableRepos.length} accepting proposals.
 `
   );
   return { close: () => running.close() };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/mcp",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Ogygie MCP server: read-only access to the governance files and features of any Ogygie repo, the manifest as index. Ships built; runnable standalone or through `ogygie mcp`.",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,7 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@ogygie/core": "0.12.0",
+    "@ogygie/core": "0.13.1",
     "@types/node": "^24.0.0",
     "esbuild": "^0.28.0",
     "tsx": "^4.20.0",