@ogygie/core 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygie/core",
-  "version": "0.7.0",
+  "version": "0.9.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",
   "type": "module",
@@ -20,6 +20,7 @@
     "./web-lint": "./src/web-lint.ts",
     "./bundle-budget": "./src/bundle-budget.ts",
     "./spec": "./src/spec.schema.ts",
+    "./repo-adapter": "./src/repo-adapter.ts",
     "./decision-refs": "./src/decision-refs.ts",
     "./design-brief": "./src/design-brief.ts",
     "./module-purity": "./src/module-purity.ts",

package/src/decision-refs.test.ts

@@ -7,6 +7,7 @@
  */
 import { describe, expect, it } from "vitest";
 import {
+  extractDecisionSection,
   findDecisionReferences,
   findDuplicateDecisionIds,
   findUnknownDecisionReferences,
@@ -112,3 +113,33 @@ describe("gate SPEC_UNKNOWN_DECISION_REFERENCE", () => {
     ]);
   });
 });
+
+describe("extraction d'UNE décision (spec ogygie-mcp)", () => {
+  it("ÉTANT DONNÉ une décision déclarée QUAND on l'extrait ALORS on reçoit sa section, titre compris", () => {
+    expect(extractDecisionSection(DECISIONS, "D11")).toBe(
+      [
+        "## D11 — 2026-07-30 — Anglais maximal dans le code",
+        "- **Décision** : les identifiants sont en anglais (voir aussi D99, jamais prise).",
+      ].join("\n"),
+    );
+  });
+
+  it("la DERNIÈRE décision du fichier va jusqu'à la fin, sans ligne vide traînante", () => {
+    expect(extractDecisionSection(`${DECISIONS}\n\n`, "D26")).toBe(
+      [
+        "## D26 — 2026-08 — Nomenclature partagée : codes normalisés",
+        "- **Décision** : le catalogue global s'appuie sur des codes normalisés.",
+      ].join("\n"),
+    );
+  });
+
+  it("MUTATION : une décision seulement CITÉE dans le corps d'une autre ne s'extrait pas", () => {
+    // D99 is mentioned inside D11. Cutting on a citation instead of a heading
+    // would serve half of D11 as if it were a decision of its own.
+    expect(extractDecisionSection(DECISIONS, "D99")).toBeNull();
+  });
+
+  it("MUTATION : un préfixe ne fait pas une décision — D1 n'est pas D11", () => {
+    expect(extractDecisionSection(DECISIONS, "D1")).toBeNull();
+  });
+});

package/src/decision-refs.ts

@@ -69,6 +69,39 @@ export function findDuplicateDecisionIds(
   return duplicated;
 }
 
+/**
+ * The section of ONE decision — its declaring heading and everything up to the
+ * next one — or null when no decisions file declares it.
+ *
+ * Serving a whole decisions file to answer a question about one decision is
+ * how a reader's context fills with rules nobody asked about (spec ogygie-mcp,
+ * `ogygie_read_decisions`). The cut is made on the DECLARING heading, the very
+ * one `parseKnownDecisionIds` counts, so what can be cited and what can be
+ * served never drift apart.
+ */
+export function extractDecisionSection(
+  decisionsMarkdown: string,
+  decisionId: string,
+): string | null {
+  const lines = decisionsMarkdown.split("\n");
+  const trimTrailingBlanks = (section: string[]): string => {
+    while (section.length > 0 && (section[section.length - 1] ?? "").trim() === "") section.pop();
+    return section.join("\n");
+  };
+  let start = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    const heading = DECISION_HEADING.exec(lines[index] ?? "");
+    if (heading === null) continue;
+    if (start === -1) {
+      if (`D${heading[1]}` === decisionId) start = index;
+      continue;
+    }
+    // The next declaration ends the one being cut.
+    return trimTrailingBlanks(lines.slice(start, index));
+  }
+  return start === -1 ? null : trimTrailingBlanks(lines.slice(start));
+}
+
 /** Every decision citation found in a text (frontmatter included), in order. */
 export function findDecisionReferences(text: string): DecisionReference[] {
   const references: DecisionReference[] = [];

package/src/manifest-owners.test.ts

@@ -77,3 +77,70 @@ describe("findSpecOwner — feature ou package, la carte confirme les deux", ()
     expect(findSpecOwner(manifestWith({}), "gadget-engine")).toBeUndefined();
   });
 });
+
+/**
+ * The nature added the day a framework spec could not be confirmed. The
+ * mutation these tests guard is the one that was there for months: the lookup
+ * IGNORING a nature the map declares, and answering "no owner" instead of
+ * "this owner, not delivered yet".
+ */
+const frameworkWith = (packages: unknown[]) => ({
+  framework: {
+    packages,
+    templates: { project: "templates/project", feature: "templates/feature" },
+    governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+  },
+});
+
+const mcpPackage = {
+  name: "@acme/mcp",
+  path: "packages/acme-mcp",
+  intent: "Serveur du protocole, publié à part parce qu'il porte sa propre dépendance.",
+  spec: "specs/acme-mcp.spec.md",
+  status: "delivered",
+};
+
+describe("findSpecOwner — le package d'un framework confirme aussi", () => {
+  it("ÉTANT DONNÉ une spec décrite par un package du framework ALORS la carte le confirme", () => {
+    const owner = findSpecOwner(manifestWith(frameworkWith([mcpPackage])), "acme-mcp");
+    expect(owner).toEqual({
+      kind: "framework-package",
+      name: "@acme/mcp",
+      status: "delivered",
+      folder: "packages/acme-mcp",
+    });
+  });
+
+  it("l'appariement se fait par le champ `spec`, JAMAIS par le nom npm publié", () => {
+    // The mutation this kills: matching `candidate.name === specId`, which
+    // silently finds nothing — "@acme/mcp" is not "acme-mcp".
+    expect(findSpecOwner(manifestWith(frameworkWith([mcpPackage])), "@acme/mcp")).toBeUndefined();
+    expect(findSpecOwner(manifestWith(frameworkWith([mcpPackage])), "acme-mcp")?.name).toBe(
+      "@acme/mcp",
+    );
+  });
+
+  it("une spec portée par PLUSIEURS packages vaut le MOINS avancé d'entre eux", () => {
+    const owner = findSpecOwner(
+      manifestWith(
+        frameworkWith([
+          { ...mcpPackage, name: "@acme/core", path: "packages/acme-core" },
+          { ...mcpPackage, name: "@acme/cli", path: "packages/acme-cli", status: "in-progress" },
+        ]),
+      ),
+      "acme-mcp",
+    );
+    expect(owner?.status).toBe("in-progress");
+    expect(owner?.name).toBe("@acme/cli");
+  });
+
+  // The "a feature and a framework package claim the same spec" case is not
+  // tested here: the manifest schema refuses it upstream (see
+  // manifest.schema.test.ts), so it cannot reach this lookup.
+  it("un package du framework SANS spec ne possède rien", () => {
+    expect(
+      findSpecOwner(manifestWith(frameworkWith([{ ...mcpPackage, spec: null }])), "acme-mcp"),
+    ).toBeUndefined();
+  });
+
+});

package/src/manifest-owners.ts

@@ -3,19 +3,42 @@
  * the map owns this spec, and how far along is it?
  *
  * The rule itself does not change — a spec only claims `implemented` when the
- * manifest confirms it. What changes is that the map now has two kinds of
- * entry able to confirm: a feature living under an app, and a PRODUCT PACKAGE
- * living outside every app (spec manifest-packages). Before that, a spec whose
- * code sat in `packages/` could never be marked finished, and nothing said why
- * — the gate answered `manifest status=absent` and suggested two fixes, both
- * impossible.
+ * manifest confirms it. What changes is WHICH entries are able to confirm.
+ * The map declares THREE natures, and this function knows all three:
+ * a feature living under an app, a PRODUCT PACKAGE living outside every app
+ * (spec manifest-packages), and a FRAMEWORK PACKAGE — the published packages a
+ * framework repo describes in its `framework` block.
+ *
+ * Each nature was added the day a spec of that nature could not be confirmed,
+ * and the failure mode is always the same silence: the gate answers "no entry
+ * of that name", suggests fixes that cannot be applied, and the spec stays
+ * `validated` for ever while its code ships (FAILURES.md 2026-08-25 — three
+ * framework specs were in that state, one of them for a delivered gate).
+ * Hence the standing convention: a spec verifier knows EVERY nature of owner
+ * the manifest declares, and a nature added to the map is added here in the
+ * same lot.
+ *
+ * A framework package matches by its `spec` field, not by its name: a
+ * published npm name (`@ogygie/mcp`) is not a spec id (`ogygie-mcp`). Several
+ * may point at the same spec — a framework spec often spans the core and the
+ * CLI — and the LEAST advanced one answers: a spec is delivered when all its
+ * code is, not when its first half is.
  *
  * Lives in the core, not in the gate script, so the rule travels with the
  * versioned package instead of with a copy each project keeps.
  */
 import type { OgygieManifest } from "./manifest.schema.js";
 
-export type SpecOwnerKind = "feature" | "package";
+/** Least advanced first — the order the "all its code" rule sorts on. */
+const ADVANCEMENT = ["skeleton", "in-progress", "delivered"] as const;
+
+/** `specs/ogygie-mcp.spec.md` -> `ogygie-mcp`. The manifest declares a PATH
+ * (as features do), the lifecycle rule reasons on ids. */
+function specIdOf(specPath: string): string {
+  return (specPath.split("/").pop() ?? specPath).replace(/\.spec\.md$/, "");
+}
+
+export type SpecOwnerKind = "feature" | "package" | "framework-package";
 
 export interface SpecOwner {
   kind: SpecOwnerKind;
@@ -64,9 +87,24 @@ export function findSpecOwner(
     };
   }
 
+  const frameworkPackages = (manifest.framework?.packages ?? []).filter(
+    (candidate) => candidate.spec !== null && specIdOf(candidate.spec) === specId,
+  );
+  const leastAdvanced = frameworkPackages
+    .slice()
+    .sort((a, b) => ADVANCEMENT.indexOf(a.status) - ADVANCEMENT.indexOf(b.status))[0];
+  if (leastAdvanced !== undefined) {
+    return {
+      kind: "framework-package",
+      name: leastAdvanced.name,
+      status: leastAdvanced.status,
+      folder: leastAdvanced.path,
+    };
+  }
+
   return undefined;
 }
 
 /** What a refusal should suggest — both natures, never one that cannot exist. */
 export const SPEC_OWNER_FIX =
-  "Set the owning entry to delivered in the manifest — a feature under `features`, or a library under `packages` — or keep the spec in validated.";
+  "Set the owning entry to delivered in the manifest — a feature under `features`, a library under `packages`, or a published package under `framework.packages` (which names its spec explicitly) — or keep the spec in validated.";

package/src/manifest.schema.test.ts

@@ -220,6 +220,78 @@ describe("manifest — ogygieVersion et bloc framework (spec ogygie-standalone-r
             name: "@ogygie/core",
             path: "packages/ogygie-core",
             intent: "Schémas, erreurs et outillage génériques du framework.",
+            spec: null,
+            status: "delivered",
+          },
+        ],
+        templates: { project: "templates/project", feature: "templates/feature" },
+        governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+      },
+    };
+    expect(OgygieManifestSchema.safeParse(manifest).success).toBe(true);
+  });
+
+  // A published package is an OWNER of specs like any other entry of the map.
+  // What follows guards the day that was discovered — a spec verifier that
+  // ignores a nature answers "no owner" and lets a delivered spec look unborn
+  // (FAILURES.md 2026-08-25).
+  it("MUTATION : un package du framework sans `status` est refusé (le cycle de vie ne devine pas)", () => {
+    const manifest = {
+      ...manifestWithFeature({}),
+      framework: {
+        packages: [
+          {
+            name: "@ogygie/core",
+            path: "packages/ogygie-core",
+            intent: "Schémas, erreurs et outillage génériques du framework.",
+            spec: null,
+          },
+        ],
+        templates: { project: "templates/project", feature: "templates/feature" },
+        governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+      },
+    };
+    expect(OgygieManifestSchema.safeParse(manifest).success).toBe(false);
+  });
+
+  it("MUTATION : un package du framework qui revendique la spec d'une FEATURE est refusé", () => {
+    const manifest = {
+      ...manifestWithFeature({}),
+      framework: {
+        packages: [
+          {
+            name: "@ogygie/shell",
+            path: "packages/ogygie-shell",
+            intent: "Package revendiquant la spec déjà possédée par la feature web-shell.",
+            spec: "specs/web-shell.spec.md",
+            status: "delivered",
+          },
+        ],
+        templates: { project: "templates/project", feature: "templates/feature" },
+        governedFiles: "packages/ogygie-cli/src/governed-files.ts",
+      },
+    };
+    expect(OgygieManifestSchema.safeParse(manifest).success).toBe(false);
+  });
+
+  it("DEUX packages du framework peuvent porter la MÊME spec : une spec du framework enjambe souvent core et cli", () => {
+    const manifest = {
+      ...manifestWithFeature({}),
+      framework: {
+        packages: [
+          {
+            name: "@ogygie/core",
+            path: "packages/ogygie-core",
+            intent: "Moitié jugement de la spec, sans aucune collecte disque.",
+            spec: "specs/outillage.spec.md",
+            status: "delivered",
+          },
+          {
+            name: "@ogygie/cli",
+            path: "packages/ogygie-cli",
+            intent: "Moitié collecte de la même spec, appelée par la CI gouvernée.",
+            spec: "specs/outillage.spec.md",
+            status: "in-progress",
           },
         ],
         templates: { project: "templates/project", feature: "templates/feature" },

package/src/manifest.schema.ts

@@ -64,9 +64,33 @@ export const HttpRouteSchema = z.object({
  * `shared` is a literal `true`: a table is either shared (and says so) or
  * tenant-scoped (and stays a plain string) — no `shared: false` third state.
  */
+/**
+ * WHICH hole in the tenancy rail, because the two do not carry the same risk
+ * (D8):
+ * - `reference` — universal knowledge loaded by an extraction script, READ
+ *   ONLY for the API. What an ABSENT key means, which is also what
+ *   `shared: true` historically meant — read it through `sharedKindOf()`
+ *   rather than defaulting in the schema, so the manifest a project wrote is
+ *   the manifest an agent reads.
+ * - `ownerless` — data the API itself produces, owned by nobody because it is
+ *   born before any account. Its feature WRITES it, and since no tenant guards
+ *   it, an unguessable secret must: its rows are read by token, never by an
+ *   enumerable id. No gate can check that, so the feature's spec must say
+ *   where the secret lives.
+ *
+ * A security fact belongs on the map, not in a comment — hence a declared key
+ * rather than a convention.
+ */
+export const SharedTableKindSchema = z.enum(["reference", "ownerless"]);
+export type SharedTableKind = z.infer<typeof SharedTableKindSchema>;
+
 export const DbTableDeclarationSchema = z.union([
   z.string(),
-  z.object({ name: z.string(), shared: z.literal(true) }),
+  z.object({
+    name: z.string(),
+    shared: z.literal(true),
+    sharedKind: SharedTableKindSchema.optional(),
+  }),
 ]);
 export type DbTableDeclaration = z.infer<typeof DbTableDeclarationSchema>;
 
@@ -121,6 +145,20 @@ export const FrameworkManifestSchema = z.object({
       name: z.string().describe("Published npm name, e.g. @ogygie/core"),
       path: z.string().describe("Folder relative to the repo root"),
       intent: z.string().min(20),
+      /**
+       * The spec describing this package, when one does. Named EXPLICITLY
+       * because a published npm name (`@ogygie/mcp`) is not a spec id
+       * (`ogygie-mcp`) — the other two natures of entry match by name, this
+       * one cannot. Several packages may point at the same spec: a spec of
+       * the framework often spans the core and the CLI.
+       */
+      spec: z.string().nullable(),
+      /**
+       * How far along, in the SAME words as the other natures. Required, and
+       * deliberately without default: a lifecycle gate that guesses a status
+       * confirms specs nobody delivered.
+       */
+      status: z.enum(["skeleton", "in-progress", "delivered"]),
     }),
   ),
   templates: z.object({
@@ -286,6 +324,27 @@ export const OgygieManifestSchema = z.object({
       packageNames.add(packageEntry.name);
     });
 
+    // One spec, one owner, ACROSS the three natures. A framework package
+    // pointing at a spec a feature or a product package already owns would
+    // give the lifecycle gate two answers, and it only ever reads the first.
+    const specIdOf = (specPath: string): string =>
+      (specPath.split("/").pop() ?? specPath).replace(/\.spec\.md$/, "");
+    const ownedSpecIds = new Set<string>([
+      ...manifest.features.map((feature) => feature.name),
+      ...packageNames,
+    ]);
+    (manifest.framework?.packages ?? []).forEach((packageEntry, index) => {
+      if (packageEntry.spec === null) return;
+      const specId = specIdOf(packageEntry.spec);
+      if (ownedSpecIds.has(specId)) {
+        context.addIssue({
+          code: "custom",
+          path: ["framework", "packages", index, "spec"],
+          message: `spec "${specId}" is already owned by a feature or a product package — one spec, one owner`,
+        });
+      }
+    });
+
     // Every `package:<name>` must designate a DECLARED package, wherever it is
     // written: a dangling dependency describes a map nobody can follow.
     const checkPackageDependencies = (

package/src/repo-adapter.test.ts

@@ -0,0 +1,192 @@
+/**
+ * @intent Proves the read-only repo access of DECISIONS.md D10, and guards the
+ * mutations that make such a module lie instead of fail: a traversal guard
+ * comparing prefixes without a separator, a symlink walking out of the repo, a
+ * `.git` that is a FILE (every worktree), a ref stored packed rather than
+ * loose. Each of those returns a plausible answer when it is wrong, which is
+ * why each has its test.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { OgygieFailure } from "./error.schema.js";
+import {
+  createFilesystemRepoAdapter,
+  createInMemoryRepoAdapter,
+  type RepoAdapter,
+} from "./repo-adapter.js";
+
+/** The stable code carried by a thrown OgygieFailure. */
+function codeOf(thrown: unknown): string {
+  return thrown instanceof OgygieFailure ? thrown.error.code : "<not an OgygieFailure>";
+}
+
+async function expectRefusal(action: () => Promise<unknown>, expectedCode: string): Promise<void> {
+  await expect(action()).rejects.toSatisfy(
+    (thrown: unknown) => codeOf(thrown) === expectedCode,
+    `expected an OgygieError with code ${expectedCode}`,
+  );
+}
+
+describe("repo-adapter — lecture du disque", () => {
+  let rootDir: string;
+  let outsideDir: string;
+  let adapter: RepoAdapter;
+
+  beforeAll(async () => {
+    const base = await mkdtemp(join(tmpdir(), "ogygie-repo-"));
+    rootDir = join(base, "repo");
+    outsideDir = join(base, "repo-evil");
+    await mkdir(join(rootDir, "src", "features", "orders"), { recursive: true });
+    await mkdir(outsideDir, { recursive: true });
+    await writeFile(join(rootDir, "AGENTS.md"), "règles", "utf8");
+    await writeFile(join(rootDir, "src", "features", "orders", "schemas.ts"), "export const a = 1;\n", "utf8");
+    await writeFile(join(rootDir, "src", "features", "orders", "service.ts"), "// service\n", "utf8");
+    await writeFile(join(outsideDir, "secrets.env"), "TOKEN=leaked", "utf8");
+    await mkdir(join(rootDir, "node_modules", "left-pad"), { recursive: true });
+    await writeFile(join(rootDir, "node_modules", "left-pad", "index.js"), "module.exports = 1;", "utf8");
+    await symlink(join(outsideDir, "secrets.env"), join(rootDir, "escape.env"));
+    adapter = createFilesystemRepoAdapter(rootDir);
+  });
+
+  afterAll(async () => {
+    await rm(join(rootDir, ".."), { recursive: true, force: true });
+  });
+
+  it("ÉTANT DONNÉ un fichier du repo QUAND on le lit ALORS son contenu revient tel quel", async () => {
+    expect(await adapter.readFile("AGENTS.md")).toBe("règles");
+  });
+
+  it("un listing est RÉCURSIF, trié, et porte la taille de chaque fichier", async () => {
+    const entries = await adapter.listDirectory("src/features/orders");
+    expect(entries.map((entry) => entry.path)).toEqual(["schemas.ts", "service.ts"]);
+    expect(entries[0]?.sizeBytes).toBe(20);
+  });
+
+  it("un dossier ABSENT liste vide — une feature en squelette est un état légitime", async () => {
+    expect(await adapter.listDirectory("src/features/inexistante")).toEqual([]);
+  });
+
+  it("node_modules et les dossiers cachés ne sont jamais listés", async () => {
+    const paths = (await adapter.listDirectory(".")).map((entry) => entry.path);
+    expect(paths).toContain("AGENTS.md");
+    expect(paths.some((path) => path.startsWith("node_modules/"))).toBe(false);
+  });
+
+  it("MUTATION : un chemin remontant vers un repo VOISIN est refusé, rien n'est lu", async () => {
+    // The neighbour is named "repo-evil" next to "repo" on purpose: a guard
+    // comparing prefixes without a separator lets it through, since
+    // "/…/repo-evil" does start with "/…/repo".
+    await expectRefusal(() => adapter.readFile("../repo-evil/secrets.env"), "PATH_OUTSIDE_REPO");
+  });
+
+  it("MUTATION : un chemin ABSOLU est refusé", async () => {
+    await expectRefusal(() => adapter.readFile(join(outsideDir, "secrets.env")), "PATH_OUTSIDE_REPO");
+  });
+
+  it("MUTATION : un lien symbolique sortant est refusé, bien que son chemin soit propre", async () => {
+    await expectRefusal(() => adapter.readFile("escape.env"), "PATH_OUTSIDE_REPO");
+  });
+
+  it("un fichier absent échoue avec un code stable, jamais un contenu vide", async () => {
+    await expectRefusal(() => adapter.readFile("jamais-ecrit.md"), "REPO_FILE_NOT_FOUND");
+  });
+
+  it("exists répond sans jamais lever pour un fichier absent", async () => {
+    expect(await adapter.exists("AGENTS.md")).toBe(true);
+    expect(await adapter.exists("jamais-ecrit.md")).toBe(false);
+  });
+
+  it("un dossier qui n'est PAS un clone git rend un ref null — jamais un identifiant inventé", async () => {
+    expect(await adapter.currentRef()).toBeNull();
+  });
+});
+
+describe("repo-adapter — le ref git, dans les trois formes que git donne à `.git`", () => {
+  let base: string;
+
+  const git = (cwd: string, ...args: string[]): string =>
+    execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        GIT_AUTHOR_NAME: "Fixture",
+        GIT_AUTHOR_EMAIL: "fixture@example.invalid",
+        GIT_COMMITTER_NAME: "Fixture",
+        GIT_COMMITTER_EMAIL: "fixture@example.invalid",
+      },
+    }).trim();
+
+  let clone: string;
+  let head: string;
+
+  beforeAll(async () => {
+    base = await mkdtemp(join(tmpdir(), "ogygie-git-"));
+    clone = join(base, "clone");
+    await mkdir(clone);
+    git(clone, "init", "--initial-branch=main");
+    await writeFile(join(clone, "AGENTS.md"), "règles", "utf8");
+    git(clone, "add", "AGENTS.md");
+    git(clone, "commit", "-m", "fixture");
+    head = git(clone, "rev-parse", "HEAD");
+  });
+
+  afterAll(async () => {
+    await rm(base, { recursive: true, force: true });
+  });
+
+  it("ÉTANT DONNÉ un clone ordinaire QUAND on demande le ref ALORS c'est le SHA de HEAD", async () => {
+    expect(await createFilesystemRepoAdapter(clone).currentRef()).toBe(head);
+  });
+
+  it("ÉTANT DONNÉ un WORKTREE, dont `.git` est un FICHIER, ALORS le ref est trouvé quand même", async () => {
+    // The form this repo itself works in. A reader that only knows the
+    // directory form answers null here — and null is a legitimate answer
+    // elsewhere, so nothing would ever protest.
+    const worktree = join(base, "wt");
+    git(clone, "worktree", "add", "-b", "essai", worktree);
+    const worktreeHead = git(worktree, "rev-parse", "HEAD");
+    expect(await createFilesystemRepoAdapter(worktree).currentRef()).toBe(worktreeHead);
+  });
+
+  it("ÉTANT DONNÉ des refs COMPACTÉES QUAND on demande le ref ALORS packed-refs répond", async () => {
+    git(clone, "pack-refs", "--all");
+    expect(await createFilesystemRepoAdapter(clone).currentRef()).toBe(head);
+  });
+
+  it("ÉTANT DONNÉ une HEAD DÉTACHÉE ALORS le SHA qu'elle porte est rendu directement", async () => {
+    const detached = join(base, "detached");
+    git(clone, "worktree", "add", "--detach", detached, head);
+    expect(await createFilesystemRepoAdapter(detached).currentRef()).toBe(head);
+  });
+});
+
+describe("repo-adapter — fixture en mémoire", () => {
+  const adapter = createInMemoryRepoAdapter({
+    "AGENTS.md": "règles",
+    "specs/notes.spec.md": "---\nid: notes\n---\n",
+    "src/features/notes/schemas.ts": "export const a = 1;\n",
+  });
+
+  it("lit, liste par préfixe et rend des tailles en OCTETS, pas en caractères", async () => {
+    expect(await adapter.readFile("AGENTS.md")).toBe("règles");
+    const entries = await adapter.listDirectory("specs");
+    expect(entries).toEqual([{ path: "notes.spec.md", sizeBytes: 18 }]);
+    // "règles" is 6 characters and 7 bytes: a size in characters would lie to
+    // every caller enforcing a byte budget.
+    const root = await adapter.listDirectory("");
+    expect(root.find((entry) => entry.path === "AGENTS.md")?.sizeBytes).toBe(7);
+  });
+
+  it("un fichier absent échoue du MÊME code que sur disque", async () => {
+    await expectRefusal(() => adapter.readFile("absent.md"), "REPO_FILE_NOT_FOUND");
+  });
+
+  it("le ref est fourni par la fixture, et peut modéliser un dossier sans git", async () => {
+    expect(await adapter.currentRef()).toBe("0".repeat(40));
+    expect(await createInMemoryRepoAdapter({}, { ref: null }).currentRef()).toBeNull();
+  });
+});

package/src/repo-adapter.ts

@@ -0,0 +1,307 @@
+/**
+ * @intent READ-ONLY access to an Ogygie repo, and the only place the framework
+ * touches a repo's disk (DECISIONS.md D10).
+ *
+ * Two tools already need it — the studio, which projects specs into a local
+ * UI, and the MCP server, which serves them to a design space (spec
+ * ogygie-mcp). Two filesystem adapters would be a lockstep bug waiting to
+ * happen: the traversal guard fixed on one side and not the other. So the
+ * interface and its implementations live here, once.
+ *
+ * Writing is NEVER declared in `RepoAdapter`. A tool that writes COMPOSES —
+ * the studio's `SpecStorage` extends this interface with its `write`. That way
+ * the read-only promise of a consumer is checkable by what it consumes, not by
+ * a comment.
+ *
+ * No dependency, on purpose: the git ref is read straight out of `.git`
+ * (D10 excludes a git library for it), so a project installing the core to
+ * validate its manifest drags nothing along.
+ */
+import { readFile as readFileFromDisk, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { z } from "zod";
+import { throwOgygieError } from "./error.schema.js";
+
+export const RepoFileEntrySchema = z.object({
+  /** Path relative to the LISTED directory, "/" separated, never absolute. */
+  path: z.string(),
+  sizeBytes: z.number().int().nonnegative(),
+});
+export type RepoFileEntry = z.infer<typeof RepoFileEntrySchema>;
+
+/**
+ * What a repo can be asked. Four methods, all reading — the shape a consumer
+ * declares when it promises to touch nothing.
+ */
+export interface RepoAdapter {
+  /** UTF-8 content of one file. Refuses a path escaping the repo. */
+  readFile(relativePath: string): Promise<string>;
+  /**
+   * Files under a directory, RECURSIVELY, sorted by path. An absent directory
+   * lists EMPTY rather than failing: a feature declared in the manifest but
+   * not yet written is a legitimate state the map already explains.
+   */
+  listDirectory(relativePath: string): Promise<RepoFileEntry[]>;
+  exists(relativePath: string): Promise<boolean>;
+  /** HEAD commit SHA, or null when the root is not a git clone. */
+  currentRef(): Promise<string | null>;
+}
+
+/**
+ * Directories a repo reader never descends into. Not a blocklist of "bad"
+ * paths — a reader that returned forty thousand `node_modules` entries would
+ * simply be unusable, and nothing under a dot-directory is repo source. The
+ * traversal guard below is what protects, this only keeps listings useful.
+ */
+const NEVER_LISTED = new Set(["node_modules"]);
+
+function isSkippedDirectory(name: string): boolean {
+  return name.startsWith(".") || NEVER_LISTED.has(name);
+}
+
+function refusePathOutsideRepo(relativePath: string, cause: string): never {
+  return throwOgygieError(
+    {
+      code: "PATH_OUTSIDE_REPO",
+      message: "The requested path resolves outside the repo root.",
+      file: relativePath,
+      cause,
+      suggestedFix:
+        "Address a path INSIDE the repo, written relative to its root and without `..`.",
+    },
+    400,
+  );
+}
+
+/**
+ * Textual guard: absolute paths and `..` never reach the disk.
+ *
+ * The prefix test carries a separator on purpose — `/srv/repo-evil` starts
+ * with `/srv/repo` as a string, and a guard that forgets it lets a sibling
+ * directory through (the form this check had while it lived in the studio).
+ */
+function resolveInsideRoot(rootDir: string, relativePath: string): string {
+  if (isAbsolute(relativePath)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" is an absolute path`);
+  }
+  const root = resolve(rootDir);
+  const absolute = resolve(root, relativePath);
+  if (absolute !== root && !absolute.startsWith(root + sep)) {
+    refusePathOutsideRepo(relativePath, `"${relativePath}" resolves to "${absolute}", outside "${root}"`);
+  }
+  return absolute;
+}
+
+/**
+ * Second guard, for what the first cannot see: a symlink INSIDE the repo
+ * pointing out of it resolves to a clean relative path and still reads someone
+ * else's file. Only checked when the target exists — when it does not, nothing
+ * is read anyway, and `exists` must be able to answer "no" without an error.
+ */
+async function assertRealPathInsideRoot(
+  rootDir: string,
+  absolute: string,
+  relativePath: string,
+): Promise<void> {
+  let realRoot: string;
+  let realTarget: string;
+  try {
+    realRoot = await realpath(rootDir);
+    realTarget = await realpath(absolute);
+  } catch {
+    return;
+  }
+  if (realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)) {
+    refusePathOutsideRepo(
+      relativePath,
+      `"${relativePath}" is a symbolic link leading to "${realTarget}", outside "${realRoot}"`,
+    );
+  }
+}
+
+async function listFilesRecursively(
+  absoluteDir: string,
+  prefix: string,
+): Promise<RepoFileEntry[]> {
+  let entries;
+  try {
+    entries = await readdir(absoluteDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files: RepoFileEntry[] = [];
+  for (const entry of entries) {
+    const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      if (isSkippedDirectory(entry.name)) continue;
+      files.push(...(await listFilesRecursively(join(absoluteDir, entry.name), relativePath)));
+    } else if (entry.isFile()) {
+      const stats = await stat(join(absoluteDir, entry.name));
+      files.push({ path: relativePath, sizeBytes: stats.size });
+    }
+  }
+  return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/**
+ * Where git really keeps its state for this root.
+ *
+ * `.git` is a directory in a plain clone and a FILE in a worktree, pointing at
+ * the real git dir; a reader that only knows the first form answers "not a git
+ * clone" for every worktree — silently, since a null ref is a legitimate
+ * answer elsewhere. Branch refs then live in the COMMON dir shared with the
+ * main clone, which `commondir` names.
+ */
+async function resolveGitDirs(rootDir: string): Promise<{ gitDir: string; commonDir: string } | null> {
+  const dotGit = join(rootDir, ".git");
+  let gitDir: string;
+  try {
+    const stats = await stat(dotGit);
+    if (stats.isDirectory()) {
+      gitDir = dotGit;
+    } else {
+      const pointer = (await readFileFromDisk(dotGit, "utf8")).trim();
+      const target = pointer.startsWith("gitdir:") ? pointer.slice("gitdir:".length).trim() : "";
+      if (target === "") return null;
+      gitDir = isAbsolute(target) ? target : resolve(rootDir, target);
+    }
+  } catch {
+    return null;
+  }
+  try {
+    const commonPointer = (await readFileFromDisk(join(gitDir, "commondir"), "utf8")).trim();
+    return { gitDir, commonDir: isAbsolute(commonPointer) ? commonPointer : resolve(gitDir, commonPointer) };
+  } catch {
+    return { gitDir, commonDir: gitDir };
+  }
+}
+
+/** A ref name resolved to its SHA — loose file first, then `packed-refs`. */
+async function readRefSha(
+  dirs: { gitDir: string; commonDir: string },
+  refName: string,
+): Promise<string | null> {
+  for (const base of [dirs.gitDir, dirs.commonDir]) {
+    try {
+      const sha = (await readFileFromDisk(join(base, refName), "utf8")).trim();
+      if (sha !== "") return sha;
+    } catch {
+      // Not stored loose here — try the next location, then packed-refs.
+    }
+  }
+  try {
+    const packed = await readFileFromDisk(join(dirs.commonDir, "packed-refs"), "utf8");
+    for (const line of packed.split("\n")) {
+      if (line.startsWith("#") || line.startsWith("^")) continue;
+      const [sha, name] = line.trim().split(" ");
+      if (name === refName && sha !== undefined && sha !== "") return sha;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * The repo as it sits on this disk, at this instant. Every path is relative to
+ * `rootDir` and guarded twice (textually, then through symlinks).
+ */
+export function createFilesystemRepoAdapter(rootDir: string): RepoAdapter {
+  return {
+    async readFile(relativePath: string): Promise<string> {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      try {
+        return await readFileFromDisk(absolute, "utf8");
+      } catch (thrown) {
+        return throwOgygieError({
+          code: "REPO_FILE_NOT_FOUND",
+          message: "The requested file cannot be read from the repo.",
+          file: relativePath,
+          cause: `reading "${absolute}" failed: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+          suggestedFix:
+            "Check the path against what the map declares — the manifest is the only chart of a repo.",
+        });
+      }
+    },
+
+    async listDirectory(relativePath: string): Promise<RepoFileEntry[]> {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      return listFilesRecursively(absolute, "");
+    },
+
+    async exists(relativePath: string): Promise<boolean> {
+      const absolute = resolveInsideRoot(rootDir, relativePath);
+      await assertRealPathInsideRoot(rootDir, absolute, relativePath);
+      try {
+        await stat(absolute);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    async currentRef(): Promise<string | null> {
+      const dirs = await resolveGitDirs(rootDir);
+      if (dirs === null) return null;
+      let head: string;
+      try {
+        head = (await readFileFromDisk(join(dirs.gitDir, "HEAD"), "utf8")).trim();
+      } catch {
+        return null;
+      }
+      // Detached HEAD holds the SHA itself; otherwise it names a ref.
+      if (!head.startsWith("ref:")) return head === "" ? null : head;
+      return readRefSha(dirs, head.slice("ref:".length).trim());
+    },
+  };
+}
+
+/** Fixture repo for the tests (principle 7: no disk, no network). */
+export interface InMemoryRepoAdapterOptions {
+  /** What `currentRef()` answers — null models a root that is not a clone. */
+  ref?: string | null;
+}
+
+export function createInMemoryRepoAdapter(
+  files: Record<string, string>,
+  options: InMemoryRepoAdapterOptions = {},
+): RepoAdapter {
+  const contents = new Map(Object.entries(files));
+  const ref = options.ref === undefined ? "0".repeat(40) : options.ref;
+  const sizeOf = (content: string): number => Buffer.byteLength(content, "utf8");
+  return {
+    async readFile(relativePath: string): Promise<string> {
+      const content = contents.get(relativePath);
+      if (content === undefined) {
+        return throwOgygieError({
+          code: "REPO_FILE_NOT_FOUND",
+          message: "The requested file does not exist in the in-memory repo.",
+          file: relativePath,
+          cause: `no entry for "${relativePath}"`,
+          suggestedFix: "Arrange the file in the fixture passed to createInMemoryRepoAdapter.",
+        });
+      }
+      return content;
+    },
+
+    async listDirectory(relativePath: string): Promise<RepoFileEntry[]> {
+      const prefix = relativePath === "" || relativePath === "." ? "" : `${relativePath.replace(/\/$/, "")}/`;
+      return [...contents.entries()]
+        .filter(([path]) => path.startsWith(prefix))
+        .map(([path, content]) => ({ path: path.slice(prefix.length), sizeBytes: sizeOf(content) }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    },
+
+    async exists(relativePath: string): Promise<boolean> {
+      if (contents.has(relativePath)) return true;
+      const prefix = `${relativePath.replace(/\/$/, "")}/`;
+      return [...contents.keys()].some((path) => path.startsWith(prefix));
+    },
+
+    async currentRef(): Promise<string | null> {
+      return ref;
+    },
+  };
+}

package/src/shared-tables.test.ts

@@ -7,15 +7,7 @@
 import { describe, expect, it } from "vitest";
 import type { FeatureManifest } from "./manifest.schema.js";
 import { FeatureManifestSchema } from "./manifest.schema.js";
-import {
-  dbTableNamesOf,
-  findTenantColumnsInSharedTables,
-  mayUseRawDb,
-  ownsOnlySharedTables,
-  sharedTableNamesOf,
-  splitDbSchemaByTable,
-  tenantTableNamesOf,
-} from "./shared-tables.js";
+import { dbTableNamesOf, findTenantColumnsInSharedTables, mayUseRawDb, ownsOnlySharedTables, sharedKindOf, sharedTableNamesOf, splitDbSchemaByTable, tenantTableNamesOf } from "./shared-tables.js";
 
 const SOCLE = new Set(["accounts"]);
 
@@ -134,3 +126,25 @@ export const labels = pgTable("labels", {
     ).toEqual([{ table: "labels", tenantColumn: "org_id" }]);
   });
 });
+
+describe("sharedKindOf — quelle brèche dans le rail tenant (D8)", () => {
+  it("une table tenant n'a AUCUNE nature : ce n'est pas une brèche", () => {
+    expect(sharedKindOf("orders")).toBeNull();
+  });
+
+  it("une table partagée sans `sharedKind` vaut `reference` — le sens historique", () => {
+    expect(sharedKindOf({ name: "currency_rates", shared: true })).toBe("reference");
+  });
+
+  it("une table `ownerless` est rendue telle quelle : sa feature l'écrit", () => {
+    expect(sharedKindOf({ name: "public_drafts", shared: true, sharedKind: "ownerless" })).toBe(
+      "ownerless",
+    );
+  });
+
+  it("une table `reference` explicite reste `reference`", () => {
+    expect(sharedKindOf({ name: "postal_codes", shared: true, sharedKind: "reference" })).toBe(
+      "reference",
+    );
+  });
+});

package/src/shared-tables.ts

@@ -19,7 +19,7 @@
  * they return. The module is GENERIC infrastructure (D10 amended): it speaks
  * "tenant", never a word of the product's domain.
  */
-import type { DbTableDeclaration, FeatureManifest } from "./manifest.schema.js";
+import type { SharedTableKind, DbTableDeclaration, FeatureManifest } from "./manifest.schema.js";
 
 /** Name of a table however it was declared (bare string or object form). */
 export function dbTableNameOf(declaration: DbTableDeclaration): string {
@@ -111,3 +111,14 @@ export function findTenantColumnsInSharedTables(
   }
   return findings;
 }
+
+/**
+ * The nature of a shared table: what the declaration says, or `reference` when
+ * it says nothing — the historical meaning of `shared: true`, kept so older
+ * manifests keep meaning what they meant (AGENTS.md §Multi-tenant rule 4).
+ * A tenant-scoped table has no nature: it is not a hole in the rail.
+ */
+export function sharedKindOf(declaration: DbTableDeclaration): SharedTableKind | null {
+  if (typeof declaration === "string") return null;
+  return declaration.sharedKind ?? "reference";
+}