@gitgov/core 2.7.1 → 2.8.0

package/dist/src/github.js

@@ -1,1860 +1,1858 @@
-import picomatch from 'picomatch';
 import path from 'path';
+import picomatch from 'picomatch';
 
-// src/file_lister/github/github_file_lister.ts
+// src/sync_state/sync_state.utils.ts
 
-// src/file_lister/file_lister.errors.ts
-var FileListerError = class extends Error {
-  constructor(message, code, filePath) {
-    super(message);
-    this.code = code;
-    this.filePath = filePath;
-    this.name = "FileListerError";
+// src/sync_state/sync_state.types.ts
+var SYNC_DIRECTORIES = [
+  "tasks",
+  "cycles",
+  "actors",
+  "agents",
+  "feedbacks",
+  "executions",
+  "workflows"
+];
+var SYNC_ROOT_FILES = [
+  "config.json"
+];
+var SYNC_ALLOWED_EXTENSIONS = [".json"];
+var SYNC_EXCLUDED_PATTERNS = [
+  /\.key$/,
+  // Private keys (e.g., keys/*.key)
+  /\.backup$/,
+  // Backup files from lint
+  /\.backup-\d+$/,
+  // Numbered backup files
+  /\.tmp$/,
+  // Temporary files
+  /\.bak$/
+  // Backup files
+];
+var LOCAL_ONLY_FILES = [
+  "index.json",
+  // Generated index, rebuilt on each machine
+  ".session.json",
+  // Local session state for current user/agent
+  "gitgov"
+  // Local binary/script
+];
+
+// src/sync_state/sync_state.utils.ts
+function shouldSyncFile(filePath) {
+  const fileName = path.basename(filePath);
+  const ext = path.extname(filePath);
+  if (!SYNC_ALLOWED_EXTENSIONS.includes(ext)) {
+    return false;
   }
-};
+  for (const pattern of SYNC_EXCLUDED_PATTERNS) {
+    if (pattern.test(fileName)) {
+      return false;
+    }
+  }
+  if (LOCAL_ONLY_FILES.includes(fileName)) {
+    return false;
+  }
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const parts = normalizedPath.split("/");
+  const gitgovIndex = parts.findIndex((p) => p === ".gitgov");
+  let relativeParts;
+  if (gitgovIndex !== -1) {
+    relativeParts = parts.slice(gitgovIndex + 1);
+  } else {
+    const syncDirIndex = parts.findIndex(
+      (p) => SYNC_DIRECTORIES.includes(p)
+    );
+    if (syncDirIndex !== -1) {
+      relativeParts = parts.slice(syncDirIndex);
+    } else if (SYNC_ROOT_FILES.includes(fileName)) {
+      return true;
+    } else {
+      return false;
+    }
+  }
+  if (relativeParts.length === 1) {
+    return SYNC_ROOT_FILES.includes(relativeParts[0]);
+  } else if (relativeParts.length >= 2) {
+    const dirName = relativeParts[0];
+    return SYNC_DIRECTORIES.includes(dirName);
+  }
+  return false;
+}
 
-// src/file_lister/github/github_file_lister.ts
-var GitHubFileLister = class {
-  owner;
-  repo;
-  ref;
-  basePath;
-  octokit;
-  /** Cached tree entries from the Trees API */
-  treeCache = null;
-  constructor(options, octokit) {
-    this.owner = options.owner;
-    this.repo = options.repo;
-    this.ref = options.ref ?? "gitgov-state";
-    this.basePath = options.basePath ?? "";
-    this.octokit = octokit;
+// src/sync_state/github_sync_state/github_sync_state.ts
+var GithubSyncStateModule = class {
+  deps;
+  lastKnownSha = null;
+  constructor(deps) {
+    this.deps = deps;
   }
-  // ═══════════════════════════════════════════════════════════════════════
-  // FileLister Interface
-  // ═══════════════════════════════════════════════════════════════════════
+  // ==================== Block A: Branch Management ====================
   /**
-   * [EARS-A1] Lists files matching glob patterns.
-   * [EARS-B1] Uses Trees API with recursive=1 and picomatch filter.
-   * [EARS-B3] Applies basePath prefix for tree entries, strips from results.
-   * [EARS-B6] Caches tree between list() calls.
+   * [EARS-GS-A3] Returns the configured state branch name.
    */
-  async list(patterns, options) {
-    const entries = await this.fetchTree();
-    const blobs = entries.filter((entry) => entry.type === "blob");
-    const prefix = this.basePath ? `${this.basePath}/` : "";
-    const relativePaths = [];
-    for (const blob of blobs) {
-      if (!blob.path) continue;
-      if (prefix && !blob.path.startsWith(prefix)) {
-        continue;
-      }
-      const relativePath = prefix ? blob.path.slice(prefix.length) : blob.path;
-      relativePaths.push(relativePath);
-    }
-    const isMatch = picomatch(patterns, {
-      ignore: options?.ignore
-    });
-    return relativePaths.filter((p) => isMatch(p)).sort();
+  async getStateBranchName() {
+    return "gitgov-state";
   }
   /**
-   * [EARS-A2] Checks if a file exists via Contents API.
-   * [EARS-B4] Returns false for 404 responses.
+   * [EARS-GS-A1] Creates gitgov-state branch if it does not exist.
+   * [EARS-GS-A2] Idempotent — no-op if branch already exists.
    */
-  async exists(filePath) {
-    const fullPath = this.buildFullPath(filePath);
+  async ensureStateBranch() {
+    const branchName = await this.getStateBranchName();
     try {
-      const { data } = await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: fullPath,
-        ref: this.ref
+      await this.deps.octokit.rest.repos.getBranch({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        branch: branchName
       });
-      if (Array.isArray(data) || data.type !== "file") {
-        return false;
-      }
-      return true;
+      return;
     } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) return false;
-        if (error.status === 401 || error.status === 403) {
-          throw new FileListerError(
-            `Permission denied: ${filePath}`,
-            "PERMISSION_DENIED",
-            filePath
-          );
-        }
-        if (error.status >= 500) {
-          throw new FileListerError(
-            `GitHub API server error (${error.status}): ${filePath}`,
-            "READ_ERROR",
-            filePath
-          );
-        }
-        throw new FileListerError(
-          `Unexpected GitHub API response (${error.status}): ${filePath}`,
-          "READ_ERROR",
-          filePath
-        );
+      if (!isOctokitRequestError(error) || error.status !== 404) {
+        throw error;
       }
-      throw new FileListerError(
-        `Network error checking file: ${filePath}`,
-        "NETWORK_ERROR",
-        filePath
-      );
     }
+    const { data: repoData } = await this.deps.octokit.rest.repos.get({
+      owner: this.deps.owner,
+      repo: this.deps.repo
+    });
+    const defaultBranch = repoData.default_branch;
+    const { data: refData } = await this.deps.octokit.rest.git.getRef({
+      owner: this.deps.owner,
+      repo: this.deps.repo,
+      ref: `heads/${defaultBranch}`
+    });
+    await this.deps.octokit.rest.git.createRef({
+      owner: this.deps.owner,
+      repo: this.deps.repo,
+      ref: `refs/heads/${branchName}`,
+      sha: refData.object.sha
+    });
   }
+  // ==================== Block B: Push State ====================
   /**
-   * [EARS-A3] Reads file content as string.
-   * [EARS-B2] Decodes base64 content from Contents API.
-   * [EARS-B7] Falls back to Blobs API for files >1MB (null content).
+   * [EARS-GS-B1..B5] Push local .gitgov/ state to gitgov-state branch via API.
+   *
+   * Uses the 6-step atomic commit pattern:
+   * getRef → getCommit → createBlob → createTree → createCommit → updateRef
+   *
+   * Optimistic concurrency: if remote ref advanced since our read, updateRef
+   * fails with 422 → return conflictDetected: true.
    */
-  async read(filePath) {
-    const fullPath = this.buildFullPath(filePath);
+  async pushState(options) {
+    const branchName = await this.getStateBranchName();
+    const sourceBranch = options.sourceBranch ?? "main";
     try {
-      const { data } = await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: fullPath,
-        ref: this.ref
+      const { data: stateRefData } = await this.deps.octokit.rest.git.getRef({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        ref: `heads/${branchName}`
       });
-      if (Array.isArray(data) || data.type !== "file") {
-        throw new FileListerError(
-          `Not a file: ${filePath}`,
-          "READ_ERROR",
-          filePath
-        );
-      }
-      if (data.content !== null && data.content !== void 0) {
-        return Buffer.from(data.content, "base64").toString("utf-8");
-      }
-      return this.readViaBlobs(data.sha, filePath);
-    } catch (error) {
-      if (error instanceof FileListerError) throw error;
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new FileListerError(
-            `File not found: ${filePath}`,
-            "FILE_NOT_FOUND",
-            filePath
-          );
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new FileListerError(
-            `Permission denied: ${filePath}`,
-            "PERMISSION_DENIED",
-            filePath
-          );
-        }
-        if (error.status >= 500) {
-          throw new FileListerError(
-            `GitHub API server error (${error.status}): ${filePath}`,
-            "READ_ERROR",
-            filePath
-          );
+      const currentSha = stateRefData.object.sha;
+      const { data: sourceTree } = await this.deps.octokit.rest.git.getTree({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        tree_sha: sourceBranch,
+        recursive: "true"
+      });
+      const sourceFiles = (sourceTree.tree ?? []).filter(
+        (item) => item.type === "blob" && item.path?.startsWith(".gitgov/") && shouldSyncFile(item.path)
+      );
+      const { data: targetCommit } = await this.deps.octokit.rest.git.getCommit({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        commit_sha: currentSha
+      });
+      const { data: targetTree } = await this.deps.octokit.rest.git.getTree({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        tree_sha: targetCommit.tree.sha,
+        recursive: "true"
+      });
+      const targetFileMap = /* @__PURE__ */ new Map();
+      for (const item of targetTree.tree ?? []) {
+        if (item.type === "blob" && item.path && item.sha) {
+          targetFileMap.set(item.path, item.sha);
         }
-        throw new FileListerError(
-          `Unexpected GitHub API response (${error.status}): ${filePath}`,
-          "READ_ERROR",
-          filePath
-        );
       }
-      throw new FileListerError(
-        `Network error reading file: ${filePath}`,
-        "NETWORK_ERROR",
-        filePath
-      );
-    }
-  }
-  /**
-   * [EARS-A4] Gets file statistics via Contents API.
-   * Returns size from API, mtime as 0 (not available via Contents API), isFile as true.
-   */
-  async stat(filePath) {
-    const fullPath = this.buildFullPath(filePath);
-    try {
-      const { data } = await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: fullPath,
-        ref: this.ref
+      const delta = [];
+      const treeEntries = [];
+      for (const sourceFile of sourceFiles) {
+        if (!sourceFile.path || !sourceFile.sha) continue;
+        const statePath = sourceFile.path.replace(/^\.gitgov\//, "");
+        const targetSha = targetFileMap.get(statePath);
+        if (targetSha !== sourceFile.sha) {
+          delta.push({
+            status: targetSha ? "M" : "A",
+            file: statePath
+          });
+          treeEntries.push({
+            path: statePath,
+            mode: "100644",
+            type: "blob",
+            sha: sourceFile.sha
+          });
+        }
+        targetFileMap.delete(statePath);
+      }
+      for (const [deletedPath] of targetFileMap) {
+        if (shouldSyncFile(deletedPath)) {
+          delta.push({ status: "D", file: deletedPath });
+          treeEntries.push({
+            path: deletedPath,
+            mode: "100644",
+            type: "blob",
+            sha: null
+          });
+        }
+      }
+      if (delta.length === 0) {
+        return {
+          success: true,
+          filesSynced: 0,
+          sourceBranch,
+          commitHash: null,
+          commitMessage: null,
+          conflictDetected: false
+        };
+      }
+      if (options.dryRun) {
+        return {
+          success: true,
+          filesSynced: delta.length,
+          sourceBranch,
+          commitHash: null,
+          commitMessage: `[dry-run] gitgov sync: ${delta.length} files`,
+          conflictDetected: false
+        };
+      }
+      const { data: newTreeData } = await this.deps.octokit.rest.git.createTree({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        base_tree: targetCommit.tree.sha,
+        tree: treeEntries
       });
-      if (Array.isArray(data) || data.type !== "file") {
-        throw new FileListerError(
-          `Not a file: ${filePath}`,
-          "READ_ERROR",
-          filePath
-        );
+      const commitMessage = `gitgov sync: ${delta.length} files from ${sourceBranch}`;
+      const { data: newCommitData } = await this.deps.octokit.rest.git.createCommit({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        message: commitMessage,
+        tree: newTreeData.sha,
+        parents: [currentSha]
+      });
+      try {
+        await this.deps.octokit.rest.git.updateRef({
+          owner: this.deps.owner,
+          repo: this.deps.repo,
+          ref: `heads/${branchName}`,
+          sha: newCommitData.sha
+        });
+      } catch (error) {
+        if (isOctokitRequestError(error) && (error.status === 422 || error.status === 409)) {
+          return {
+            success: false,
+            filesSynced: 0,
+            sourceBranch,
+            commitHash: null,
+            commitMessage: null,
+            conflictDetected: true,
+            conflictInfo: {
+              type: "rebase_conflict",
+              affectedFiles: delta.map((d) => d.file),
+              message: "Remote gitgov-state ref has advanced since last read. Pull and retry.",
+              resolutionSteps: [
+                "Call pullState() to fetch latest remote state",
+                "Retry pushState() with updated parent SHA"
+              ]
+            }
+          };
+        }
+        throw error;
       }
+      this.lastKnownSha = newCommitData.sha;
       return {
-        size: data.size,
-        mtime: 0,
-        isFile: true
+        success: true,
+        filesSynced: delta.length,
+        sourceBranch,
+        commitHash: newCommitData.sha,
+        commitMessage,
+        conflictDetected: false
       };
     } catch (error) {
-      if (error instanceof FileListerError) throw error;
       if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new FileListerError(
-            `File not found: ${filePath}`,
-            "FILE_NOT_FOUND",
-            filePath
-          );
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new FileListerError(
-            `Permission denied: ${filePath}`,
-            "PERMISSION_DENIED",
-            filePath
-          );
-        }
-        if (error.status >= 500) {
-          throw new FileListerError(
-            `GitHub API server error (${error.status}): ${filePath}`,
-            "READ_ERROR",
-            filePath
-          );
-        }
-        throw new FileListerError(
-          `Unexpected GitHub API response (${error.status}): ${filePath}`,
-          "READ_ERROR",
-          filePath
-        );
+        return {
+          success: false,
+          filesSynced: 0,
+          sourceBranch,
+          commitHash: null,
+          commitMessage: null,
+          conflictDetected: false,
+          error: `GitHub API error (${error.status}): ${error.message}`
+        };
       }
-      throw new FileListerError(
-        `Network error getting file stats: ${filePath}`,
-        "NETWORK_ERROR",
-        filePath
-      );
-    }
-  }
-  // ═══════════════════════════════════════════════════════════════════════
-  // Private Helpers
-  // ═══════════════════════════════════════════════════════════════════════
-  /**
-   * Builds the full file path including basePath prefix.
-   */
-  buildFullPath(filePath) {
-    if (this.basePath) {
-      return `${this.basePath}/${filePath}`;
+      const msg = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        filesSynced: 0,
+        sourceBranch,
+        commitHash: null,
+        commitMessage: null,
+        conflictDetected: false,
+        error: msg
+      };
     }
-    return filePath;
   }
+  // ==================== Block C: Pull State ====================
   /**
-   * [EARS-B6] Fetches and caches the full repository tree.
-   * [EARS-C3] Throws READ_ERROR if the tree response is truncated.
+   * [EARS-GS-C1..C4] Pull remote state from gitgov-state branch.
+   *
+   * Fetches tree + blobs, updates lastKnownSha, triggers re-indexing.
    */
-  async fetchTree() {
-    if (this.treeCache !== null) {
-      return this.treeCache;
-    }
+  async pullState(options) {
+    const branchName = await this.getStateBranchName();
+    let remoteSha;
     try {
-      const { data } = await this.octokit.rest.git.getTree({
-        owner: this.owner,
-        repo: this.repo,
-        tree_sha: this.ref,
-        recursive: "1"
+      const { data: refData } = await this.deps.octokit.rest.git.getRef({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        ref: `heads/${branchName}`
       });
-      if (data.truncated) {
-        throw new FileListerError(
-          "Repository tree is truncated; too many files to list via Trees API",
-          "READ_ERROR"
-        );
-      }
-      this.treeCache = data.tree;
-      return this.treeCache;
+      remoteSha = refData.object.sha;
     } catch (error) {
-      if (error instanceof FileListerError) throw error;
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new FileListerError(
-            "Repository or ref not found",
-            "FILE_NOT_FOUND"
-          );
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new FileListerError(
-            "Permission denied accessing repository tree",
-            "PERMISSION_DENIED"
-          );
-        }
-        if (error.status >= 500) {
-          throw new FileListerError(
-            `GitHub API server error (${error.status}) fetching tree`,
-            "READ_ERROR"
-          );
-        }
-        throw new FileListerError(
-          `Unexpected GitHub API response (${error.status}) fetching tree`,
-          "READ_ERROR"
-        );
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return {
+          success: true,
+          hasChanges: false,
+          filesUpdated: 0,
+          reindexed: false,
+          conflictDetected: false
+        };
+      }
+      throw error;
+    }
+    if (this.lastKnownSha === remoteSha && !options?.forceReindex) {
+      return {
+        success: true,
+        hasChanges: false,
+        filesUpdated: 0,
+        reindexed: false,
+        conflictDetected: false
+      };
+    }
+    const { data: commitData } = await this.deps.octokit.rest.git.getCommit({
+      owner: this.deps.owner,
+      repo: this.deps.repo,
+      commit_sha: remoteSha
+    });
+    const { data: treeData } = await this.deps.octokit.rest.git.getTree({
+      owner: this.deps.owner,
+      repo: this.deps.repo,
+      tree_sha: commitData.tree.sha,
+      recursive: "true"
+    });
+    const syncableFiles = (treeData.tree ?? []).filter(
+      (item) => item.type === "blob" && item.path && shouldSyncFile(item.path)
+    );
+    const filesUpdated = syncableFiles.length;
+    this.lastKnownSha = remoteSha;
+    let reindexed = false;
+    if (filesUpdated > 0 || options?.forceReindex) {
+      try {
+        await this.deps.indexer.computeProjection();
+        reindexed = true;
+      } catch {
+        reindexed = false;
       }
-      throw new FileListerError(
-        "Network error fetching repository tree",
-        "NETWORK_ERROR"
-      );
     }
+    return {
+      success: true,
+      hasChanges: filesUpdated > 0,
+      filesUpdated,
+      reindexed,
+      conflictDetected: false
+    };
   }
+  // ==================== Block D: Change Detection ====================
   /**
-   * [EARS-B7] Reads file content via the Blobs API (fallback for >1MB files).
+   * [EARS-GS-D1..D3] Calculate file delta between known state and current remote.
    */
-  async readViaBlobs(sha, filePath) {
+  async calculateStateDelta(_sourceBranch) {
+    const branchName = await this.getStateBranchName();
+    let currentSha;
     try {
-      const { data } = await this.octokit.rest.git.getBlob({
-        owner: this.owner,
-        repo: this.repo,
-        file_sha: sha
+      const { data: refData } = await this.deps.octokit.rest.git.getRef({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        ref: `heads/${branchName}`
       });
-      return Buffer.from(data.content, "base64").toString("utf-8");
+      currentSha = refData.object.sha;
     } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new FileListerError(
-            `File not found: ${filePath}`,
-            "FILE_NOT_FOUND",
-            filePath
-          );
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new FileListerError(
-            `Permission denied: ${filePath}`,
-            "PERMISSION_DENIED",
-            filePath
-          );
-        }
-        throw new FileListerError(
-          `GitHub API error (${error.status}): ${filePath}`,
-          "READ_ERROR",
-          filePath
-        );
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return [];
       }
-      throw new FileListerError(
-        `Network error reading blob for file: ${filePath}`,
-        "NETWORK_ERROR",
-        filePath
-      );
+      throw error;
     }
-  }
-};
-
-// src/record_store/github/github_record_store.ts
-var GitHubRecordStore = class {
-  owner;
-  repo;
-  ref;
-  basePath;
-  extension;
-  idEncoder;
-  octokit;
-  /** SHA cache keyed by full file path (basePath/encoded + extension) */
-  shaCache = /* @__PURE__ */ new Map();
-  /** IGitModule dependency for putMany() atomic commits. Optional — only needed for putMany(). */
-  gitModule;
-  constructor(options, octokit, gitModule) {
-    this.owner = options.owner;
-    this.repo = options.repo;
-    this.ref = options.ref ?? "gitgov-state";
-    this.basePath = options.basePath;
-    this.extension = options.extension ?? ".json";
-    this.idEncoder = options.idEncoder;
-    this.octokit = octokit;
-    this.gitModule = gitModule;
-  }
-  async get(id) {
-    this.validateId(id);
-    const filePath = this.buildFilePath(id);
-    try {
-      const { data } = await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: filePath,
-        ref: this.ref
-      });
-      if (Array.isArray(data) || data.type !== "file") {
-        throw new GitHubApiError(`Not a file: ${filePath}`, "INVALID_RESPONSE");
-      }
-      if (data.content === null || data.content === void 0) {
-        throw new GitHubApiError(
-          `File content is null (file may exceed 1MB): ${filePath}`,
-          "INVALID_RESPONSE"
-        );
-      }
-      this.shaCache.set(filePath, data.sha);
-      const decoded = Buffer.from(data.content, "base64").toString("utf-8");
-      return JSON.parse(decoded);
-    } catch (error) {
-      if (error instanceof GitHubApiError) throw error;
-      if (isOctokitRequestError(error) && error.status === 404) return null;
-      throw mapOctokitError(error, `GET ${filePath}`);
+    if (this.lastKnownSha === currentSha) {
+      return [];
     }
-  }
-  async put(id, value, opts) {
-    this.validateId(id);
-    const filePath = this.buildFilePath(id);
-    const content = Buffer.from(JSON.stringify(value, null, 2)).toString("base64");
-    const cachedSha = this.shaCache.get(filePath);
-    try {
-      const { data } = await this.octokit.rest.repos.createOrUpdateFileContents({
-        owner: this.owner,
-        repo: this.repo,
-        path: filePath,
-        message: opts?.commitMessage ?? `put ${id}`,
-        content,
-        branch: this.ref,
-        ...cachedSha ? { sha: cachedSha } : {}
+    if (this.lastKnownSha === null) {
+      const { data: commitData } = await this.deps.octokit.rest.git.getCommit({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        commit_sha: currentSha
       });
-      if (data.content?.sha) {
-        this.shaCache.set(filePath, data.content.sha);
-      }
-      return { commitSha: data.commit.sha };
-    } catch (error) {
-      throw mapOctokitError(error, `PUT ${filePath}`);
+      const { data: treeData } = await this.deps.octokit.rest.git.getTree({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        tree_sha: commitData.tree.sha,
+        recursive: "true"
+      });
+      return (treeData.tree ?? []).filter((item) => item.type === "blob" && item.path && shouldSyncFile(item.path)).map((item) => ({
+        status: "A",
+        file: item.path
+      }));
     }
+    const { data: comparison } = await this.deps.octokit.rest.repos.compareCommits({
+      owner: this.deps.owner,
+      repo: this.deps.repo,
+      base: this.lastKnownSha,
+      head: currentSha
+    });
+    return (comparison.files ?? []).filter((file) => shouldSyncFile(file.filename)).map((file) => ({
+      status: file.status === "added" ? "A" : file.status === "removed" ? "D" : "M",
+      file: file.filename
+    }));
   }
   /**
-   * [EARS-A11, EARS-A12, EARS-B8] Persists multiple records in a single atomic commit.
-   * Uses GitHubGitModule staging buffer: add() with contentMap, then commit().
-   * Empty entries array returns { commitSha: undefined } without API calls.
-   * Requires gitModule dependency — throws if not injected.
+   * Always empty — no local pending changes in API mode.
+   * In API mode there is no local filesystem; all state is remote.
    */
-  async putMany(entries, opts) {
-    if (entries.length === 0) {
-      return {};
-    }
-    if (!this.gitModule) {
-      throw new Error("putMany requires IGitModule dependency for atomic commits");
-    }
-    for (const { id } of entries) {
-      this.validateId(id);
-    }
-    const contentMap = {};
-    const filePaths = [];
-    for (const { id, value } of entries) {
-      const filePath = this.buildFilePath(id);
-      contentMap[filePath] = JSON.stringify(value, null, 2);
-      filePaths.push(filePath);
-    }
-    await this.gitModule.add(filePaths, { contentMap });
-    const message = opts?.commitMessage ?? `putMany ${entries.length} records`;
-    const commitSha = await this.gitModule.commit(message);
-    return { commitSha };
+  async getPendingChanges() {
+    return [];
   }
-  async delete(id, opts) {
-    this.validateId(id);
-    const filePath = this.buildFilePath(id);
-    let sha = this.shaCache.get(filePath);
-    if (sha === void 0) {
-      try {
-        const { data } = await this.octokit.rest.repos.getContent({
-          owner: this.owner,
-          repo: this.repo,
-          path: filePath,
-          ref: this.ref
-        });
-        if (Array.isArray(data) || data.type !== "file") {
-          return {};
-        }
-        sha = data.sha;
-      } catch (error) {
-        if (isOctokitRequestError(error) && error.status === 404) {
-          return {};
-        }
-        throw mapOctokitError(error, `GET ${filePath} (for delete)`);
-      }
-    }
-    try {
-      const { data } = await this.octokit.rest.repos.deleteFile({
-        owner: this.owner,
-        repo: this.repo,
-        path: filePath,
-        message: opts?.commitMessage ?? `delete ${id}`,
-        sha,
-        branch: this.ref
-      });
-      this.shaCache.delete(filePath);
-      return { commitSha: data.commit.sha };
-    } catch (error) {
-      if (isOctokitRequestError(error) && error.status === 404) {
-        this.shaCache.delete(filePath);
-        return {};
-      }
-      throw mapOctokitError(error, `DELETE ${filePath}`);
-    }
+  // ==================== Block E: Conflict Handling ====================
+  /**
+   * Always false — no rebase in API mode.
+   */
+  async isRebaseInProgress() {
+    return false;
   }
-  async list() {
-    try {
-      const { data } = await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: this.basePath,
-        ref: this.ref
-      });
-      if (!Array.isArray(data)) {
-        return [];
-      }
-      const ids = data.filter((entry) => entry.name.endsWith(this.extension)).map((entry) => entry.name.slice(0, -this.extension.length));
-      return this.idEncoder ? ids.map((encoded) => this.idEncoder.decode(encoded)) : ids;
-    } catch (error) {
-      if (isOctokitRequestError(error) && error.status === 404) {
-        return [];
-      }
-      throw mapOctokitError(error, `GET ${this.basePath} (list)`);
-    }
+  /**
+   * Always empty — no conflict markers in API mode.
+   */
+  async checkConflictMarkers(_filePaths) {
+    return [];
   }
-  async exists(id) {
-    this.validateId(id);
-    const filePath = this.buildFilePath(id);
-    try {
-      await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: filePath,
-        ref: this.ref
-      });
-      return true;
-    } catch (error) {
-      if (isOctokitRequestError(error) && error.status === 404) {
-        return false;
-      }
-      throw mapOctokitError(error, `GET ${filePath} (exists)`);
-    }
+  /**
+   * Empty diff — no git-level conflict markers in API mode.
+   */
+  async getConflictDiff(_filePaths) {
+    return {
+      files: [],
+      message: "No conflict markers in API mode. Conflicts are SHA-based.",
+      resolutionSteps: [
+        "Call pullState() to fetch latest remote state",
+        "Retry pushState() with updated records"
+      ]
+    };
   }
-  // ─────────────────────────────────────────────────────────
-  // Private helpers
-  // ─────────────────────────────────────────────────────────
-  validateId(id) {
-    if (!id || typeof id !== "string") {
-      throw new GitHubApiError("ID must be a non-empty string", "INVALID_ID");
+  /**
+   * [EARS-GS-E1..E2] Resolve conflict by pulling latest and retrying push.
+   */
+  async resolveConflict(options) {
+    const pullResult = await this.pullState({ forceReindex: false });
+    if (!pullResult.success) {
+      return {
+        success: false,
+        rebaseCommitHash: "",
+        resolutionCommitHash: "",
+        conflictsResolved: 0,
+        resolvedBy: options.actorId,
+        reason: options.reason,
+        error: `Pull failed during conflict resolution: ${pullResult.error}`
+      };
     }
-    if (id.includes("..") || /[\/\\]/.test(id)) {
-      throw new GitHubApiError(
-        `Invalid ID: "${id}". IDs cannot contain /, \\, or ..`,
-        "INVALID_ID"
-      );
+    const pushResult = await this.pushState({
+      actorId: options.actorId
+    });
+    if (!pushResult.success || pushResult.conflictDetected) {
+      const errorMsg = pushResult.conflictDetected ? "Content conflict: same file modified by both sides. Manual resolution required." : pushResult.error ?? "Unknown push error";
+      return {
+        success: false,
+        rebaseCommitHash: "",
+        resolutionCommitHash: "",
+        conflictsResolved: 0,
+        resolvedBy: options.actorId,
+        reason: options.reason,
+        error: errorMsg
+      };
     }
+    return {
+      success: true,
+      rebaseCommitHash: this.lastKnownSha ?? "",
+      resolutionCommitHash: pushResult.commitHash ?? "",
+      conflictsResolved: pushResult.filesSynced,
+      resolvedBy: options.actorId,
+      reason: options.reason
+    };
   }
-  buildFilePath(id) {
-    const encoded = this.idEncoder ? this.idEncoder.encode(id) : id;
-    return `${this.basePath}/${encoded}${this.extension}`;
-  }
-};
-
-// src/git/errors.ts
-var GitError = class _GitError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "GitError";
-    Object.setPrototypeOf(this, _GitError.prototype);
-  }
-};
-var BranchNotFoundError = class _BranchNotFoundError extends GitError {
-  branchName;
-  constructor(branchName) {
-    super(`Branch not found: ${branchName}`);
-    this.name = "BranchNotFoundError";
-    this.branchName = branchName;
-    Object.setPrototypeOf(this, _BranchNotFoundError.prototype);
-  }
-};
-var FileNotFoundError = class _FileNotFoundError extends GitError {
-  filePath;
-  commitHash;
-  constructor(filePath, commitHash) {
-    super(`File not found: ${filePath} in commit ${commitHash}`);
-    this.name = "FileNotFoundError";
-    this.filePath = filePath;
-    this.commitHash = commitHash;
-    Object.setPrototypeOf(this, _FileNotFoundError.prototype);
-  }
-};
-var BranchAlreadyExistsError = class _BranchAlreadyExistsError extends GitError {
-  branchName;
-  constructor(branchName) {
-    super(`Branch already exists: ${branchName}`);
-    this.name = "BranchAlreadyExistsError";
-    this.branchName = branchName;
-    Object.setPrototypeOf(this, _BranchAlreadyExistsError.prototype);
-  }
-};
-
-// src/git/github/github_git_module.ts
-var GitHubGitModule = class {
-  owner;
-  repo;
-  defaultBranch;
-  octokit;
-  /** Staging buffer: path → content (null = delete) */
-  stagingBuffer = /* @__PURE__ */ new Map();
-  /** Active ref for operations (can be changed via checkoutBranch) */
-  activeRef;
-  constructor(options, octokit) {
-    this.owner = options.owner;
-    this.repo = options.repo;
-    this.defaultBranch = options.defaultBranch ?? "gitgov-state";
-    this.octokit = octokit;
-    this.activeRef = this.defaultBranch;
-  }
-  // ═══════════════════════════════════════════════════════════════
-  // PRIVATE HELPERS
-  // ═══════════════════════════════════════════════════════════════
-  /** Category C: Not supported via GitHub API */
-  notSupported(method) {
-    throw new GitError(
-      `${method} is not supported via GitHub API`
-    );
-  }
-  // ═══════════════════════════════════════════════════════════════
-  // CATEGORY A: READ OPERATIONS (EARS-A1 to A6)
-  // ═══════════════════════════════════════════════════════════════
   /**
-   * [EARS-A1] Read file content via Contents API + base64 decode
-   * [EARS-A2] Fallback to Blobs API for files >1MB
+   * No integrity violations in API mode (no rebase commits).
    */
-  async getFileContent(commitHash, filePath) {
-    try {
-      const { data } = await this.octokit.rest.repos.getContent({
-        owner: this.owner,
-        repo: this.repo,
-        path: filePath,
-        ref: commitHash
-      });
-      if (Array.isArray(data) || data.type !== "file") {
-        throw new GitError(`Not a file: ${filePath}`);
-      }
-      if (data.content !== null && data.content !== void 0) {
-        return Buffer.from(data.content, "base64").toString("utf-8");
-      }
-      const { data: blobData } = await this.octokit.rest.git.getBlob({
-        owner: this.owner,
-        repo: this.repo,
-        file_sha: data.sha
-      });
-      return Buffer.from(blobData.content, "base64").toString("utf-8");
-    } catch (error) {
-      if (error instanceof GitError) throw error;
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new FileNotFoundError(filePath, commitHash);
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): getFileContent ${filePath}`);
-        }
-        if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): getFileContent ${filePath}`);
-        }
-        throw new GitError(`GitHub API error (${error.status}): getFileContent ${filePath}`);
-      }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
-    }
+  async verifyResolutionIntegrity() {
+    return [];
   }
+  // ==================== Block F: Audit ====================
   /**
-   * [EARS-A3] Get commit SHA from branch via Refs API
-   * [EARS-B4] Return SHA directly if already a 40-char hex
+   * [EARS-GS-F1..F2] Audit the remote gitgov-state branch.
    */
-  async getCommitHash(ref = this.activeRef) {
-    if (/^[0-9a-f]{40}$/i.test(ref)) {
-      return ref;
-    }
+  async auditState(options) {
+    const branchName = await this.getStateBranchName();
+    const scope = options?.scope ?? "all";
+    let totalCommits = 0;
     try {
-      const { data } = await this.octokit.rest.git.getRef({
-        owner: this.owner,
-        repo: this.repo,
-        ref: `heads/${ref}`
+      const { data: commits } = await this.deps.octokit.rest.repos.listCommits({
+        owner: this.deps.owner,
+        repo: this.deps.repo,
+        sha: branchName,
+        per_page: 100
       });
-      return data.object.sha;
+      totalCommits = commits.length;
     } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new BranchNotFoundError(ref);
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): getCommitHash ${ref}`);
-        }
-        if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): getCommitHash ${ref}`);
-        }
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return {
+          passed: true,
+          scope,
+          totalCommits: 0,
+          rebaseCommits: 0,
+          resolutionCommits: 0,
+          integrityViolations: [],
+          summary: "Branch gitgov-state does not exist. No audit needed."
+        };
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+      throw error;
     }
-  }
-  /**
-   * [EARS-A4] List changed files via Compare API
-   */
-  async getChangedFiles(fromCommit, toCommit, pathFilter) {
-    try {
-      const { data } = await this.octokit.rest.repos.compareCommits({
-        owner: this.owner,
-        repo: this.repo,
-        base: fromCommit,
-        head: toCommit
-      });
-      const statusMap = {
-        added: "A",
-        modified: "M",
-        removed: "D",
-        renamed: "M"
-      };
-      const files = (data.files ?? []).map((f) => ({
-        status: statusMap[f.status] ?? "M",
-        file: f.filename
-      })).filter((f) => !pathFilter || f.file.startsWith(pathFilter));
-      return files;
-    } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): getChangedFiles ${fromCommit}...${toCommit}`);
+    const rebaseCommits = 0;
+    const resolutionCommits = 0;
+    const integrityViolations = [];
+    let lintReport;
+    if (options?.verifySignatures !== false || options?.verifyChecksums !== false) {
+      try {
+        const { data: refData } = await this.deps.octokit.rest.git.getRef({
+          owner: this.deps.owner,
+          repo: this.deps.repo,
+          ref: `heads/${branchName}`
+        });
+        const { data: commitData } = await this.deps.octokit.rest.git.getCommit({
+          owner: this.deps.owner,
+          repo: this.deps.repo,
+          commit_sha: refData.object.sha
+        });
+        const { data: treeData } = await this.deps.octokit.rest.git.getTree({
+          owner: this.deps.owner,
+          repo: this.deps.repo,
+          tree_sha: commitData.tree.sha,
+          recursive: "true"
+        });
+        const treeItems = (treeData.tree ?? []).filter((item) => item.type === "blob" && item.path && item.sha && shouldSyncFile(item.path));
+        const startTime = Date.now();
+        const allResults = [];
+        let filesChecked = 0;
+        for (const item of treeItems) {
+          try {
+            const { data: blobData } = await this.deps.octokit.rest.git.getBlob({
+              owner: this.deps.owner,
+              repo: this.deps.repo,
+              file_sha: item.sha
+            });
+            const content = Buffer.from(blobData.content, "base64").toString("utf-8");
+            const record = JSON.parse(content);
+            const entityType = pathToEntityType(item.path);
+            if (entityType) {
+              const results = this.deps.lint.lintRecord(record, {
+                recordId: item.path.split("/").pop()?.replace(".json", "") ?? item.path,
+                entityType,
+                filePath: item.path
+              });
+              allResults.push(...results);
+            }
+            filesChecked++;
+          } catch {
+          }
         }
-        if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): getChangedFiles`);
+        if (filesChecked > 0) {
+          lintReport = {
+            summary: {
+              filesChecked,
+              errors: allResults.filter((r) => r.level === "error").length,
+              warnings: allResults.filter((r) => r.level === "warning").length,
+              fixable: allResults.filter((r) => r.fixable).length,
+              executionTime: Date.now() - startTime
+            },
+            results: allResults,
+            metadata: {
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              options: {},
+              version: "1.0.0"
+            }
+          };
         }
-        throw new GitError(`Failed to compare ${fromCommit}...${toCommit}: HTTP ${error.status}`);
+      } catch {
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
     }
-  }
-  /**
-   * [EARS-A5] Get commit history via Commits API
-   */
-  async getCommitHistory(branch, options) {
-    try {
-      const { data } = await this.octokit.rest.repos.listCommits({
-        owner: this.owner,
-        repo: this.repo,
-        sha: branch,
-        ...options?.maxCount !== void 0 && { per_page: options.maxCount },
-        ...options?.pathFilter !== void 0 && { path: options.pathFilter }
-      });
-      return data.map((c) => ({
-        hash: c.sha,
-        message: c.commit.message,
-        author: `${c.commit.author?.name ?? "unknown"} <${c.commit.author?.email ?? "unknown"}>`,
-        date: c.commit.author?.date ?? ""
-      }));
-    } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): getCommitHistory ${branch}`);
-        }
-        if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): getCommitHistory`);
-        }
-        throw new GitError(`Failed to get commit history: HTTP ${error.status}`);
-      }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+    const lintPassed = !lintReport || lintReport.summary.errors === 0;
+    const passed = integrityViolations.length === 0 && lintPassed;
+    const lintErrors = lintReport?.summary.errors ?? 0;
+    let summary;
+    if (passed) {
+      summary = `Audit passed. ${totalCommits} commits analyzed, 0 violations.`;
+    } else if (integrityViolations.length > 0 && lintErrors > 0) {
+      summary = `Audit failed. ${integrityViolations.length} integrity violations, ${lintErrors} lint errors.`;
+    } else if (lintErrors > 0) {
+      summary = `Audit failed. ${lintErrors} lint errors found.`;
+    } else {
+      summary = `Audit failed. ${integrityViolations.length} integrity violations found.`;
     }
-  }
-  /**
-   * [EARS-B3] Get commit history between two commits via Compare API
-   */
-  async getCommitHistoryRange(fromHash, toHash, options) {
-    try {
-      const { data } = await this.octokit.rest.repos.compareCommits({
-        owner: this.owner,
-        repo: this.repo,
-        base: fromHash,
-        head: toHash
-      });
-      let commits = data.commits.map((c) => ({
-        hash: c.sha,
-        message: c.commit.message,
-        author: `${c.commit.author?.name ?? "unknown"} <${c.commit.author?.email ?? "unknown"}>`,
-        date: c.commit.author?.date ?? ""
-      }));
-      if (options?.pathFilter) {
-        const changedPaths = new Set((data.files ?? []).map((f) => f.filename));
-        commits = commits.filter(
-          () => Array.from(changedPaths).some((f) => f.startsWith(options.pathFilter))
-        );
-      }
-      if (options?.maxCount) {
-        commits = commits.slice(0, options.maxCount);
-      }
-      return commits;
-    } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): getCommitHistoryRange ${fromHash}...${toHash}`);
-        }
-        if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): getCommitHistoryRange`);
-        }
-        throw new GitError(`Failed to get commit range: HTTP ${error.status}`);
-      }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+    const report = {
+      passed,
+      scope,
+      totalCommits,
+      rebaseCommits,
+      resolutionCommits,
+      integrityViolations,
+      summary
+    };
+    if (lintReport) {
+      report.lintReport = lintReport;
     }
+    return report;
+  }
+};
+function pathToEntityType(filePath) {
+  const dirMap = {
+    tasks: "task",
+    cycles: "cycle",
+    actors: "actor",
+    agents: "agent",
+    feedbacks: "feedback",
+    executions: "execution"
+  };
+  const firstSegment = filePath.split("/")[0] ?? "";
+  return dirMap[firstSegment];
+}
+
+// src/file_lister/file_lister.errors.ts
+var FileListerError = class extends Error {
+  constructor(message, code, filePath) {
+    super(message);
+    this.code = code;
+    this.filePath = filePath;
+    this.name = "FileListerError";
+  }
+};
+
+// src/file_lister/github/github_file_lister.ts
+var GitHubFileLister = class {
+  owner;
+  repo;
+  ref;
+  basePath;
+  octokit;
+  /** Cached tree entries from the Trees API */
+  treeCache = null;
+  constructor(options, octokit) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.ref = options.ref ?? "gitgov-state";
+    this.basePath = options.basePath ?? "";
+    this.octokit = octokit;
   }
+  // ═══════════════════════════════════════════════════════════════════════
+  // FileLister Interface
+  // ═══════════════════════════════════════════════════════════════════════
   /**
-   * [EARS-A6] Get commit message via Commits API
+   * [EARS-A1] Lists files matching glob patterns.
+   * [EARS-B1] Uses Trees API with recursive=1 and picomatch filter.
+   * [EARS-B3] Applies basePath prefix for tree entries, strips from results.
+   * [EARS-B6] Caches tree between list() calls.
    */
-  async getCommitMessage(commitHash) {
-    try {
-      const { data } = await this.octokit.rest.repos.getCommit({
-        owner: this.owner,
-        repo: this.repo,
-        ref: commitHash
-      });
-      return data.commit.message;
-    } catch (error) {
-      if (isOctokitRequestError(error)) {
-        if (error.status === 404) {
-          throw new GitError(`Commit not found: ${commitHash}`);
-        }
-        if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): getCommitMessage ${commitHash}`);
-        }
-        if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): getCommitMessage`);
-        }
+  async list(patterns, options) {
+    const entries = await this.fetchTree();
+    const blobs = entries.filter((entry) => entry.type === "blob");
+    const prefix = this.basePath ? `${this.basePath}/` : "";
+    const relativePaths = [];
+    for (const blob of blobs) {
+      if (!blob.path) continue;
+      if (prefix && !blob.path.startsWith(prefix)) {
+        continue;
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+      const relativePath = prefix ? blob.path.slice(prefix.length) : blob.path;
+      relativePaths.push(relativePath);
     }
+    const isMatch = picomatch(patterns, {
+      ignore: options?.ignore
+    });
+    return relativePaths.filter((p) => isMatch(p)).sort();
   }
-  // ═══════════════════════════════════════════════════════════════
-  // CATEGORY A: BRANCH OPERATIONS (EARS-B1 to B2)
-  // ═══════════════════════════════════════════════════════════════
   /**
-   * [EARS-B1] Check if branch exists via Branches API
+   * [EARS-A2] Checks if a file exists via Contents API.
+   * [EARS-B4] Returns false for 404 responses.
    */
-  async branchExists(branchName) {
+  async exists(filePath) {
+    const fullPath = this.buildFullPath(filePath);
     try {
-      await this.octokit.rest.repos.getBranch({
+      const { data } = await this.octokit.rest.repos.getContent({
         owner: this.owner,
         repo: this.repo,
-        branch: branchName
+        path: fullPath,
+        ref: this.ref
       });
+      if (Array.isArray(data) || data.type !== "file") {
+        return false;
+      }
       return true;
     } catch (error) {
       if (isOctokitRequestError(error)) {
         if (error.status === 404) return false;
         if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): branchExists ${branchName}`);
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
         }
-        throw new GitError(`Failed to check branch: HTTP ${error.status}`);
+        if (error.status >= 500) {
+          throw new FileListerError(
+            `GitHub API server error (${error.status}): ${filePath}`,
+            "READ_ERROR",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+      throw new FileListerError(
+        `Network error checking file: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
     }
   }
   /**
-   * [EARS-B2] List remote branches via Branches API
-   * remoteName is ignored — repo itself is the implicit remote
+   * [EARS-A3] Reads file content as string.
+   * [EARS-B2] Decodes base64 content from Contents API.
+   * [EARS-B7] Falls back to Blobs API for files >1MB (null content).
    */
-  async listRemoteBranches(_remoteName) {
+  async read(filePath) {
+    const fullPath = this.buildFullPath(filePath);
     try {
-      const { data } = await this.octokit.rest.repos.listBranches({
+      const { data } = await this.octokit.rest.repos.getContent({
         owner: this.owner,
-        repo: this.repo
+        repo: this.repo,
+        path: fullPath,
+        ref: this.ref
       });
-      return data.map((b) => b.name);
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new FileListerError(
+          `Not a file: ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      if (data.content !== null && data.content !== void 0) {
+        return Buffer.from(data.content, "base64").toString("utf-8");
+      }
+      return this.readViaBlobs(data.sha, filePath);
     } catch (error) {
+      if (error instanceof FileListerError) throw error;
       if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            `File not found: ${filePath}`,
+            "FILE_NOT_FOUND",
+            filePath
+          );
+        }
         if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): listRemoteBranches`);
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
         }
         if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): listRemoteBranches`);
+          throw new FileListerError(
+            `GitHub API server error (${error.status}): ${filePath}`,
+            "READ_ERROR",
+            filePath
+          );
         }
-        throw new GitError(`Failed to list branches: HTTP ${error.status}`);
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
-    }
-  }
-  // ═══════════════════════════════════════════════════════════════
-  // CATEGORY A: WRITE OPERATIONS (EARS-C1 to C7)
-  // ═══════════════════════════════════════════════════════════════
-  /** [EARS-C1] Read file content and store in staging buffer */
-  async add(filePaths, options) {
-    for (const filePath of filePaths) {
-      const content = options?.contentMap?.[filePath] ?? await this.getFileContent(this.activeRef, filePath);
-      this.stagingBuffer.set(filePath, content);
-    }
-  }
-  /** [EARS-C2] Mark files as deleted in staging buffer */
-  async rm(filePaths) {
-    for (const filePath of filePaths) {
-      this.stagingBuffer.set(filePath, null);
+      throw new FileListerError(
+        `Network error reading file: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
     }
   }
-  /** [EARS-C7] Return staged file paths from buffer */
-  async getStagedFiles() {
-    return Array.from(this.stagingBuffer.keys());
-  }
   /**
-   * [EARS-C6] Create branch via Refs API POST
+   * [EARS-A4] Gets file statistics via Contents API.
+   * Returns size from API, mtime as 0 (not available via Contents API), isFile as true.
    */
-  async createBranch(branchName, startPoint) {
-    const sha = startPoint ? await this.getCommitHash(startPoint) : await this.getCommitHash(this.activeRef);
+  async stat(filePath) {
+    const fullPath = this.buildFullPath(filePath);
     try {
-      await this.octokit.rest.git.createRef({
+      const { data } = await this.octokit.rest.repos.getContent({
         owner: this.owner,
         repo: this.repo,
-        ref: `refs/heads/${branchName}`,
-        sha
+        path: fullPath,
+        ref: this.ref
       });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new FileListerError(
+          `Not a file: ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      return {
+        size: data.size,
+        mtime: 0,
+        isFile: true
+      };
     } catch (error) {
+      if (error instanceof FileListerError) throw error;
       if (isOctokitRequestError(error)) {
-        if (error.status === 422) {
-          throw new BranchAlreadyExistsError(branchName);
+        if (error.status === 404) {
+          throw new FileListerError(
+            `File not found: ${filePath}`,
+            "FILE_NOT_FOUND",
+            filePath
+          );
         }
         if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): createBranch ${branchName}`);
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
         }
-        throw new GitError(`Failed to create branch ${branchName}: HTTP ${error.status}`);
+        if (error.status >= 500) {
+          throw new FileListerError(
+            `GitHub API server error (${error.status}): ${filePath}`,
+            "READ_ERROR",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+      throw new FileListerError(
+        `Network error getting file stats: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
     }
   }
+  // ═══════════════════════════════════════════════════════════════════════
+  // Private Helpers
+  // ═══════════════════════════════════════════════════════════════════════
   /**
-   * Internal commit implementation shared by commit() and commitAllowEmpty().
-   *
-   * [EARS-C3] 6-step atomic transaction
-   * [EARS-C4] Clears staging buffer after successful commit
-   * [EARS-C5] Throws if staging buffer is empty (unless allowEmpty)
+   * Builds the full file path including basePath prefix.
    */
-  async commitInternal(message, author, allowEmpty = false) {
-    if (!allowEmpty && this.stagingBuffer.size === 0) {
-      throw new GitError("Nothing to commit: staging buffer is empty");
+  buildFullPath(filePath) {
+    if (this.basePath) {
+      return `${this.basePath}/${filePath}`;
+    }
+    return filePath;
+  }
+  /**
+   * [EARS-B6] Fetches and caches the full repository tree.
+   * [EARS-C3] Throws READ_ERROR if the tree response is truncated.
+   */
+  async fetchTree() {
+    if (this.treeCache !== null) {
+      return this.treeCache;
     }
     try {
-      const { data: refData } = await this.octokit.rest.git.getRef({
-        owner: this.owner,
-        repo: this.repo,
-        ref: `heads/${this.activeRef}`
-      });
-      const currentSha = refData.object.sha;
-      const { data: commitData } = await this.octokit.rest.git.getCommit({
-        owner: this.owner,
-        repo: this.repo,
-        commit_sha: currentSha
-      });
-      const treeSha = commitData.tree.sha;
-      const treeEntries = [];
-      for (const [path2, content] of this.stagingBuffer) {
-        if (content === null) {
-          treeEntries.push({
-            path: path2,
-            mode: "100644",
-            type: "blob",
-            sha: null
-          });
-        } else {
-          const { data: blobData } = await this.octokit.rest.git.createBlob({
-            owner: this.owner,
-            repo: this.repo,
-            content: Buffer.from(content).toString("base64"),
-            encoding: "base64"
-          });
-          treeEntries.push({
-            path: path2,
-            mode: "100644",
-            type: "blob",
-            sha: blobData.sha
-          });
-        }
-      }
-      const { data: treeData } = await this.octokit.rest.git.createTree({
+      const { data } = await this.octokit.rest.git.getTree({
         owner: this.owner,
         repo: this.repo,
-        base_tree: treeSha,
-        tree: treeEntries
+        tree_sha: this.ref,
+        recursive: "1"
       });
-      const newTreeSha = treeData.sha;
-      const commitParams = {
-        owner: this.owner,
-        repo: this.repo,
-        message,
-        tree: newTreeSha,
-        parents: [currentSha]
-      };
-      if (author) {
-        commitParams.author = {
-          name: author.name,
-          email: author.email,
-          date: (/* @__PURE__ */ new Date()).toISOString()
-        };
-      }
-      const { data: newCommitData } = await this.octokit.rest.git.createCommit(commitParams);
-      const newCommitSha = newCommitData.sha;
-      try {
-        await this.octokit.rest.git.updateRef({
-          owner: this.owner,
-          repo: this.repo,
-          ref: `heads/${this.activeRef}`,
-          sha: newCommitSha
-        });
-      } catch (error) {
-        if (isOctokitRequestError(error) && error.status === 422) {
-          throw new GitError("non-fast-forward update rejected");
-        }
-        throw error;
+      if (data.truncated) {
+        throw new FileListerError(
+          "Repository tree is truncated; too many files to list via Trees API",
+          "READ_ERROR"
+        );
       }
-      this.stagingBuffer.clear();
-      return newCommitSha;
+      this.treeCache = data.tree;
+      return this.treeCache;
     } catch (error) {
-      if (error instanceof GitError) throw error;
+      if (error instanceof FileListerError) throw error;
       if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            "Repository or ref not found",
+            "FILE_NOT_FOUND"
+          );
+        }
         if (error.status === 401 || error.status === 403) {
-          throw new GitError(`authentication/permission error (${error.status}): commit`);
+          throw new FileListerError(
+            "Permission denied accessing repository tree",
+            "PERMISSION_DENIED"
+          );
         }
         if (error.status >= 500) {
-          throw new GitError(`GitHub server error (${error.status}): commit`);
+          throw new FileListerError(
+            `GitHub API server error (${error.status}) fetching tree`,
+            "READ_ERROR"
+          );
         }
-        throw new GitError(`GitHub API error (${error.status}): commit`);
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}) fetching tree`,
+          "READ_ERROR"
+        );
       }
-      const msg = error instanceof Error ? error.message : String(error);
-      throw new GitError(`network error: ${msg}`);
+      throw new FileListerError(
+        "Network error fetching repository tree",
+        "NETWORK_ERROR"
+      );
     }
   }
   /**
-   * [EARS-C3] Commit staged changes via 6-step atomic transaction
-   * [EARS-C5] Throws if staging buffer is empty
+   * [EARS-B7] Reads file content via the Blobs API (fallback for >1MB files).
    */
-  async commit(message, author) {
-    return this.commitInternal(message, author, false);
-  }
-  // ═══════════════════════════════════════════════════════════════
-  // CATEGORY B: NO-OPS (sensible defaults)
-  // ═══════════════════════════════════════════════════════════════
-  /** [EARS-D5] exec not supported in API mode */
-  async exec(_command, _args, _options) {
-    return { exitCode: 1, stdout: "", stderr: "exec() not supported in GitHub API mode" };
-  }
-  /** No-op: repos are created via GitHub API, not initialized locally */
-  async init() {
-  }
-  /** [EARS-D1] Return virtual path representing the repo */
-  async getRepoRoot() {
-    return `github://${this.owner}/${this.repo}`;
-  }
-  /** [EARS-D1] Return active ref (starts as defaultBranch) */
-  async getCurrentBranch() {
-    return this.activeRef;
-  }
-  /** No-op: git config doesn't apply to GitHub API */
-  async setConfig(_key, _value, _scope) {
-  }
-  /** [EARS-D1] Return true if staging buffer has entries */
-  async hasUncommittedChanges(_pathFilter) {
-    return this.stagingBuffer.size > 0;
-  }
-  /** No-op: GitHub API doesn't have rebase-in-progress concept */
-  async isRebaseInProgress() {
-    return false;
-  }
-  /** [EARS-D1] GitHub repos always have 'origin' conceptually */
-  async isRemoteConfigured(_remoteName) {
-    return true;
-  }
-  /** No-op: always 'origin' */
-  async getBranchRemote(_branchName) {
-    return "origin";
-  }
-  /** No-op: GitHub API handles merges atomically */
-  async getConflictedFiles() {
-    return [];
-  }
-  /** [EARS-D2] Update activeRef for subsequent operations */
-  async checkoutBranch(branchName) {
-    this.activeRef = branchName;
-  }
-  /** No-op: GitHub API doesn't have stash concept */
-  async stash(_message) {
-    return null;
-  }
-  /** No-op */
-  async stashPop() {
-    return false;
-  }
-  /** No-op */
-  async stashDrop(_stashHash) {
-  }
-  /** No-op: API always fresh */
-  async fetch(_remote) {
-  }
-  /** No-op: API mode */
-  async pull(_remote, _branchName) {
-  }
-  /** No-op: API mode */
-  async pullRebase(_remote, _branchName) {
-  }
-  /** [EARS-D4] No-op: commits via API are already remote */
-  async push(_remote, _branchName) {
-  }
-  /** [EARS-D4] No-op: commits via API are already remote */
-  async pushWithUpstream(_remote, _branchName) {
-  }
-  /** No-op: API mode */
-  async setUpstream(_branchName, _remote, _remoteBranch) {
-  }
-  /** No-op */
-  async rebaseAbort() {
-  }
-  /** [EARS-D1] Delegates to commitInternal, allowing empty staging buffer */
-  async commitAllowEmpty(message, author) {
-    return this.commitInternal(message, author, true);
-  }
-  // ═══════════════════════════════════════════════════════════════
-  // CATEGORY C: NOT SUPPORTED (throw GitError)
-  // ═══════════════════════════════════════════════════════════════
-  /** [EARS-D3] Not supported via GitHub API */
-  async rebase(_targetBranch) {
-    this.notSupported("rebase");
-  }
-  /** [EARS-D3] Not supported via GitHub API */
-  async rebaseContinue() {
-    this.notSupported("rebaseContinue");
-  }
-  /** [EARS-D3] Not supported via GitHub API */
-  async resetHard(_target) {
-    this.notSupported("resetHard");
-  }
-  /** [EARS-D3] Not supported via GitHub API */
-  async checkoutOrphanBranch(_branchName) {
-    this.notSupported("checkoutOrphanBranch");
-  }
-  /** [EARS-D3] Not supported via GitHub API */
-  async checkoutFilesFromBranch(_sourceBranch, _filePaths) {
-    this.notSupported("checkoutFilesFromBranch");
-  }
-  /** [EARS-D3] Not supported via GitHub API */
-  async getMergeBase(_branchA, _branchB) {
-    this.notSupported("getMergeBase");
+  async readViaBlobs(sha, filePath) {
+    try {
+      const { data } = await this.octokit.rest.git.getBlob({
+        owner: this.owner,
+        repo: this.repo,
+        file_sha: sha
+      });
+      return Buffer.from(data.content, "base64").toString("utf-8");
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            `File not found: ${filePath}`,
+            "FILE_NOT_FOUND",
+            filePath
+          );
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `GitHub API error (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      throw new FileListerError(
+        `Network error reading blob for file: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
+    }
   }
 };
 
-// src/config_store/github/github_config_store.ts
-var GitHubConfigStore = class {
+// src/record_store/github/github_record_store.ts
+var GitHubRecordStore = class {
   owner;
   repo;
   ref;
   basePath;
+  extension;
+  idEncoder;
   octokit;
-  /** Cached blob SHA from the last loadConfig call, used for PUT updates */
-  cachedSha = null;
-  constructor(options, octokit) {
+  /** SHA cache keyed by full file path (basePath/encoded + extension) */
+  shaCache = /* @__PURE__ */ new Map();
+  /** IGitModule dependency for putMany() atomic commits. Optional — only needed for putMany(). */
+  gitModule;
+  constructor(options, octokit, gitModule) {
     this.owner = options.owner;
     this.repo = options.repo;
     this.ref = options.ref ?? "gitgov-state";
-    this.basePath = options.basePath ?? ".gitgov";
+    this.basePath = options.basePath;
+    this.extension = options.extension ?? ".json";
+    this.idEncoder = options.idEncoder;
     this.octokit = octokit;
+    this.gitModule = gitModule;
+  }
+  async get(id) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new GitHubApiError(`Not a file: ${filePath}`, "INVALID_RESPONSE");
+      }
+      if (data.content === null || data.content === void 0) {
+        throw new GitHubApiError(
+          `File content is null (file may exceed 1MB): ${filePath}`,
+          "INVALID_RESPONSE"
+        );
+      }
+      this.shaCache.set(filePath, data.sha);
+      const decoded = Buffer.from(data.content, "base64").toString("utf-8");
+      return JSON.parse(decoded);
+    } catch (error) {
+      if (error instanceof GitHubApiError) throw error;
+      if (isOctokitRequestError(error) && error.status === 404) return null;
+      throw mapOctokitError(error, `GET ${filePath}`);
+    }
+  }
+  async put(id, value, opts) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    const content = Buffer.from(JSON.stringify(value, null, 2)).toString("base64");
+    const cachedSha = this.shaCache.get(filePath);
+    try {
+      const { data } = await this.octokit.rest.repos.createOrUpdateFileContents({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        message: opts?.commitMessage ?? `put ${id}`,
+        content,
+        branch: this.ref,
+        ...cachedSha ? { sha: cachedSha } : {}
+      });
+      if (data.content?.sha) {
+        this.shaCache.set(filePath, data.content.sha);
+      }
+      return { commitSha: data.commit.sha };
+    } catch (error) {
+      throw mapOctokitError(error, `PUT ${filePath}`);
+    }
+  }
+  /**
+   * [EARS-A11, EARS-A12, EARS-B8] Persists multiple records in a single atomic commit.
+   * Uses GitHubGitModule staging buffer: add() with contentMap, then commit().
+   * Empty entries array returns { commitSha: undefined } without API calls.
+   * Requires gitModule dependency — throws if not injected.
+   */
+  async putMany(entries, opts) {
+    if (entries.length === 0) {
+      return {};
+    }
+    if (!this.gitModule) {
+      throw new Error("putMany requires IGitModule dependency for atomic commits");
+    }
+    for (const { id } of entries) {
+      this.validateId(id);
+    }
+    const contentMap = {};
+    const filePaths = [];
+    for (const { id, value } of entries) {
+      const filePath = this.buildFilePath(id);
+      contentMap[filePath] = JSON.stringify(value, null, 2);
+      filePaths.push(filePath);
+    }
+    await this.gitModule.add(filePaths, { contentMap });
+    const message = opts?.commitMessage ?? `putMany ${entries.length} records`;
+    const commitSha = await this.gitModule.commit(message);
+    return { commitSha };
   }
-  /**
-   * Load project configuration from GitHub Contents API.
-   *
-   * [EARS-A1] Returns GitGovConfig when valid JSON is found.
-   * [EARS-A2] Returns null on 404 (fail-safe).
-   * [EARS-A3] Returns null on invalid JSON (fail-safe).
-   * [EARS-B1] Fetches via Contents API with base64 decode.
-   * [EARS-B2] Caches SHA from response for subsequent saveConfig.
-   */
-  async loadConfig() {
-    const path2 = `${this.basePath}/config.json`;
+  async delete(id, opts) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    let sha = this.shaCache.get(filePath);
+    if (sha === void 0) {
+      try {
+        const { data } = await this.octokit.rest.repos.getContent({
+          owner: this.owner,
+          repo: this.repo,
+          path: filePath,
+          ref: this.ref
+        });
+        if (Array.isArray(data) || data.type !== "file") {
+          return {};
+        }
+        sha = data.sha;
+      } catch (error) {
+        if (isOctokitRequestError(error) && error.status === 404) {
+          return {};
+        }
+        throw mapOctokitError(error, `GET ${filePath} (for delete)`);
+      }
+    }
+    try {
+      const { data } = await this.octokit.rest.repos.deleteFile({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        message: opts?.commitMessage ?? `delete ${id}`,
+        sha,
+        branch: this.ref
+      });
+      this.shaCache.delete(filePath);
+      return { commitSha: data.commit.sha };
+    } catch (error) {
+      if (isOctokitRequestError(error) && error.status === 404) {
+        this.shaCache.delete(filePath);
+        return {};
+      }
+      throw mapOctokitError(error, `DELETE ${filePath}`);
+    }
+  }
+  async list() {
     try {
       const { data } = await this.octokit.rest.repos.getContent({
         owner: this.owner,
         repo: this.repo,
-        path: path2,
+        path: this.basePath,
         ref: this.ref
       });
-      if (Array.isArray(data) || data.type !== "file") {
-        return null;
-      }
-      if (!data.content) {
-        return null;
-      }
-      this.cachedSha = data.sha;
-      try {
-        const decoded = Buffer.from(data.content, "base64").toString("utf-8");
-        return JSON.parse(decoded);
-      } catch {
-        return null;
+      if (!Array.isArray(data)) {
+        return [];
       }
+      const ids = data.filter((entry) => entry.name.endsWith(this.extension)).map((entry) => entry.name.slice(0, -this.extension.length));
+      return this.idEncoder ? ids.map((encoded) => this.idEncoder.decode(encoded)) : ids;
     } catch (error) {
       if (isOctokitRequestError(error) && error.status === 404) {
-        return null;
+        return [];
       }
-      throw mapOctokitError(error, `loadConfig ${this.owner}/${this.repo}/${path2}`);
+      throw mapOctokitError(error, `GET ${this.basePath} (list)`);
     }
   }
-  /**
-   * Save project configuration to GitHub via Contents API PUT.
-   *
-   * [EARS-A4] Writes config via PUT to Contents API.
-   * [EARS-B3] Includes cached SHA for updates (optimistic concurrency).
-   * [EARS-B4] Omits SHA for initial creation.
-   * [EARS-C1] Throws PERMISSION_DENIED on 401/403.
-   * [EARS-C2] Throws CONFLICT on 409.
-   * [EARS-C3] Throws SERVER_ERROR on 5xx.
-   */
-  async saveConfig(config) {
-    const path2 = `${this.basePath}/config.json`;
-    const content = Buffer.from(JSON.stringify(config, null, 2)).toString("base64");
+  async exists(id) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
     try {
-      const { data } = await this.octokit.rest.repos.createOrUpdateFileContents({
+      await this.octokit.rest.repos.getContent({
         owner: this.owner,
         repo: this.repo,
-        path: path2,
-        message: "chore(config): update gitgov config.json",
-        content,
-        branch: this.ref,
-        ...this.cachedSha ? { sha: this.cachedSha } : {}
+        path: filePath,
+        ref: this.ref
       });
-      if (data.content?.sha) {
-        this.cachedSha = data.content.sha;
-      }
-      return { commitSha: data.commit.sha };
+      return true;
     } catch (error) {
-      throw mapOctokitError(error, `saveConfig ${this.owner}/${this.repo}/${path2}`);
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return false;
+      }
+      throw mapOctokitError(error, `GET ${filePath} (exists)`);
+    }
+  }
+  // ─────────────────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────────────────
+  validateId(id) {
+    if (!id || typeof id !== "string") {
+      throw new GitHubApiError("ID must be a non-empty string", "INVALID_ID");
+    }
+    if (id.includes("..") || /[\/\\]/.test(id)) {
+      throw new GitHubApiError(
+        `Invalid ID: "${id}". IDs cannot contain /, \\, or ..`,
+        "INVALID_ID"
+      );
     }
   }
+  buildFilePath(id) {
+    const encoded = this.idEncoder ? this.idEncoder.encode(id) : id;
+    return `${this.basePath}/${encoded}${this.extension}`;
+  }
 };
 
-// src/sync_state/sync_state.types.ts
-var SYNC_DIRECTORIES = [
-  "tasks",
-  "cycles",
-  "actors",
-  "agents",
-  "feedbacks",
-  "executions",
-  "changelogs",
-  "workflows"
-];
-var SYNC_ROOT_FILES = [
-  "config.json"
-];
-var SYNC_ALLOWED_EXTENSIONS = [".json"];
-var SYNC_EXCLUDED_PATTERNS = [
-  /\.key$/,
-  // Private keys (e.g., keys/*.key)
-  /\.backup$/,
-  // Backup files from lint
-  /\.backup-\d+$/,
-  // Numbered backup files
-  /\.tmp$/,
-  // Temporary files
-  /\.bak$/
-  // Backup files
-];
-var LOCAL_ONLY_FILES = [
-  "index.json",
-  // Generated index, rebuilt on each machine
-  ".session.json",
-  // Local session state for current user/agent
-  "gitgov"
-  // Local binary/script
-];
-
-// src/sync_state/sync_state.utils.ts
-function shouldSyncFile(filePath) {
-  const fileName = path.basename(filePath);
-  const ext = path.extname(filePath);
-  if (!SYNC_ALLOWED_EXTENSIONS.includes(ext)) {
-    return false;
-  }
-  for (const pattern of SYNC_EXCLUDED_PATTERNS) {
-    if (pattern.test(fileName)) {
-      return false;
-    }
+// src/git/errors.ts
+var GitError = class _GitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GitError";
+    Object.setPrototypeOf(this, _GitError.prototype);
   }
-  if (LOCAL_ONLY_FILES.includes(fileName)) {
-    return false;
+};
+var BranchNotFoundError = class _BranchNotFoundError extends GitError {
+  branchName;
+  constructor(branchName) {
+    super(`Branch not found: ${branchName}`);
+    this.name = "BranchNotFoundError";
+    this.branchName = branchName;
+    Object.setPrototypeOf(this, _BranchNotFoundError.prototype);
   }
-  const normalizedPath = filePath.replace(/\\/g, "/");
-  const parts = normalizedPath.split("/");
-  const gitgovIndex = parts.findIndex((p) => p === ".gitgov");
-  let relativeParts;
-  if (gitgovIndex !== -1) {
-    relativeParts = parts.slice(gitgovIndex + 1);
-  } else {
-    const syncDirIndex = parts.findIndex(
-      (p) => SYNC_DIRECTORIES.includes(p)
-    );
-    if (syncDirIndex !== -1) {
-      relativeParts = parts.slice(syncDirIndex);
-    } else if (SYNC_ROOT_FILES.includes(fileName)) {
-      return true;
-    } else {
-      return false;
-    }
+};
+var FileNotFoundError = class _FileNotFoundError extends GitError {
+  filePath;
+  commitHash;
+  constructor(filePath, commitHash) {
+    super(`File not found: ${filePath} in commit ${commitHash}`);
+    this.name = "FileNotFoundError";
+    this.filePath = filePath;
+    this.commitHash = commitHash;
+    Object.setPrototypeOf(this, _FileNotFoundError.prototype);
   }
-  if (relativeParts.length === 1) {
-    return SYNC_ROOT_FILES.includes(relativeParts[0]);
-  } else if (relativeParts.length >= 2) {
-    const dirName = relativeParts[0];
-    return SYNC_DIRECTORIES.includes(dirName);
+};
+var BranchAlreadyExistsError = class _BranchAlreadyExistsError extends GitError {
+  branchName;
+  constructor(branchName) {
+    super(`Branch already exists: ${branchName}`);
+    this.name = "BranchAlreadyExistsError";
+    this.branchName = branchName;
+    Object.setPrototypeOf(this, _BranchAlreadyExistsError.prototype);
   }
-  return false;
-}
+};
 
-// src/sync_state/github_sync_state/github_sync_state.ts
-var GithubSyncStateModule = class {
-  deps;
-  lastKnownSha = null;
-  constructor(deps) {
-    this.deps = deps;
+// src/git/github/github_git_module.ts
+var GitHubGitModule = class {
+  owner;
+  repo;
+  defaultBranch;
+  octokit;
+  /** Staging buffer: path → content (null = delete) */
+  stagingBuffer = /* @__PURE__ */ new Map();
+  /** Active ref for operations (can be changed via checkoutBranch) */
+  activeRef;
+  constructor(options, octokit) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.defaultBranch = options.defaultBranch ?? "gitgov-state";
+    this.octokit = octokit;
+    this.activeRef = this.defaultBranch;
   }
-  // ==================== Block A: Branch Management ====================
+  // ═══════════════════════════════════════════════════════════════
+  // PRIVATE HELPERS
+  // ═══════════════════════════════════════════════════════════════
+  /** Category C: Not supported via GitHub API */
+  notSupported(method) {
+    throw new GitError(
+      `${method} is not supported via GitHub API`
+    );
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY A: READ OPERATIONS (EARS-A1 to A6)
+  // ═══════════════════════════════════════════════════════════════
   /**
-   * [EARS-GS-A3] Returns the configured state branch name.
+   * [EARS-A1] Read file content via Contents API + base64 decode
+   * [EARS-A2] Fallback to Blobs API for files >1MB
    */
-  async getStateBranchName() {
-    return "gitgov-state";
+  async getFileContent(commitHash, filePath) {
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        ref: commitHash
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new GitError(`Not a file: ${filePath}`);
+      }
+      if (data.content !== null && data.content !== void 0) {
+        return Buffer.from(data.content, "base64").toString("utf-8");
+      }
+      const { data: blobData } = await this.octokit.rest.git.getBlob({
+        owner: this.owner,
+        repo: this.repo,
+        file_sha: data.sha
+      });
+      return Buffer.from(blobData.content, "base64").toString("utf-8");
+    } catch (error) {
+      if (error instanceof GitError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileNotFoundError(filePath, commitHash);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getFileContent ${filePath}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getFileContent ${filePath}`);
+        }
+        throw new GitError(`GitHub API error (${error.status}): getFileContent ${filePath}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
   }
   /**
-   * [EARS-GS-A1] Creates gitgov-state branch if it does not exist.
-   * [EARS-GS-A2] Idempotent — no-op if branch already exists.
+   * [EARS-A3] Get commit SHA from branch via Refs API
+   * [EARS-B4] Return SHA directly if already a 40-char hex
    */
-  async ensureStateBranch() {
-    const branchName = await this.getStateBranchName();
+  async getCommitHash(ref = this.activeRef) {
+    if (/^[0-9a-f]{40}$/i.test(ref)) {
+      return ref;
+    }
     try {
-      await this.deps.octokit.rest.repos.getBranch({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        branch: branchName
+      const { data } = await this.octokit.rest.git.getRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${ref}`
       });
-      return;
+      return data.object.sha;
     } catch (error) {
-      if (!isOctokitRequestError(error) || error.status !== 404) {
-        throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new BranchNotFoundError(ref);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitHash ${ref}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitHash ${ref}`);
+        }
       }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
     }
-    const { data: repoData } = await this.deps.octokit.rest.repos.get({
-      owner: this.deps.owner,
-      repo: this.deps.repo
-    });
-    const defaultBranch = repoData.default_branch;
-    const { data: refData } = await this.deps.octokit.rest.git.getRef({
-      owner: this.deps.owner,
-      repo: this.deps.repo,
-      ref: `heads/${defaultBranch}`
-    });
-    await this.deps.octokit.rest.git.createRef({
-      owner: this.deps.owner,
-      repo: this.deps.repo,
-      ref: `refs/heads/${branchName}`,
-      sha: refData.object.sha
-    });
   }
-  // ==================== Block B: Push State ====================
   /**
-   * [EARS-GS-B1..B5] Push local .gitgov/ state to gitgov-state branch via API.
-   *
-   * Uses the 6-step atomic commit pattern:
-   * getRef → getCommit → createBlob → createTree → createCommit → updateRef
-   *
-   * Optimistic concurrency: if remote ref advanced since our read, updateRef
-   * fails with 422 → return conflictDetected: true.
+   * [EARS-A4] List changed files via Compare API
    */
-  async pushState(options) {
-    const branchName = await this.getStateBranchName();
-    const sourceBranch = options.sourceBranch ?? "main";
+  async getChangedFiles(fromCommit, toCommit, pathFilter) {
     try {
-      const { data: stateRefData } = await this.deps.octokit.rest.git.getRef({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        ref: `heads/${branchName}`
-      });
-      const currentSha = stateRefData.object.sha;
-      const { data: sourceTree } = await this.deps.octokit.rest.git.getTree({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        tree_sha: sourceBranch,
-        recursive: "true"
-      });
-      const sourceFiles = (sourceTree.tree ?? []).filter(
-        (item) => item.type === "blob" && item.path?.startsWith(".gitgov/") && shouldSyncFile(item.path)
-      );
-      const { data: targetCommit } = await this.deps.octokit.rest.git.getCommit({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        commit_sha: currentSha
-      });
-      const { data: targetTree } = await this.deps.octokit.rest.git.getTree({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        tree_sha: targetCommit.tree.sha,
-        recursive: "true"
+      const { data } = await this.octokit.rest.repos.compareCommits({
+        owner: this.owner,
+        repo: this.repo,
+        base: fromCommit,
+        head: toCommit
       });
-      const targetFileMap = /* @__PURE__ */ new Map();
-      for (const item of targetTree.tree ?? []) {
-        if (item.type === "blob" && item.path && item.sha) {
-          targetFileMap.set(item.path, item.sha);
+      const statusMap = {
+        added: "A",
+        modified: "M",
+        removed: "D",
+        renamed: "M"
+      };
+      const files = (data.files ?? []).map((f) => ({
+        status: statusMap[f.status] ?? "M",
+        file: f.filename
+      })).filter((f) => !pathFilter || f.file.startsWith(pathFilter));
+      return files;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getChangedFiles ${fromCommit}...${toCommit}`);
         }
-      }
-      const delta = [];
-      const treeEntries = [];
-      for (const sourceFile of sourceFiles) {
-        if (!sourceFile.path || !sourceFile.sha) continue;
-        const statePath = sourceFile.path.replace(/^\.gitgov\//, "");
-        const targetSha = targetFileMap.get(statePath);
-        if (targetSha !== sourceFile.sha) {
-          delta.push({
-            status: targetSha ? "M" : "A",
-            file: statePath
-          });
-          treeEntries.push({
-            path: statePath,
-            mode: "100644",
-            type: "blob",
-            sha: sourceFile.sha
-          });
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getChangedFiles`);
         }
-        targetFileMap.delete(statePath);
+        throw new GitError(`Failed to compare ${fromCommit}...${toCommit}: HTTP ${error.status}`);
       }
-      for (const [deletedPath] of targetFileMap) {
-        if (shouldSyncFile(deletedPath)) {
-          delta.push({ status: "D", file: deletedPath });
-          treeEntries.push({
-            path: deletedPath,
-            mode: "100644",
-            type: "blob",
-            sha: null
-          });
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-A5] Get commit history via Commits API
+   */
+  async getCommitHistory(branch, options) {
+    try {
+      const { data } = await this.octokit.rest.repos.listCommits({
+        owner: this.owner,
+        repo: this.repo,
+        sha: branch,
+        ...options?.maxCount !== void 0 && { per_page: options.maxCount },
+        ...options?.pathFilter !== void 0 && { path: options.pathFilter }
+      });
+      return data.map((c) => ({
+        hash: c.sha,
+        message: c.commit.message,
+        author: `${c.commit.author?.name ?? "unknown"} <${c.commit.author?.email ?? "unknown"}>`,
+        date: c.commit.author?.date ?? ""
+      }));
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitHistory ${branch}`);
         }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitHistory`);
+        }
+        throw new GitError(`Failed to get commit history: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-B3] Get commit history between two commits via Compare API
+   */
+  async getCommitHistoryRange(fromHash, toHash, options) {
+    try {
+      const { data } = await this.octokit.rest.repos.compareCommits({
+        owner: this.owner,
+        repo: this.repo,
+        base: fromHash,
+        head: toHash
+      });
+      let commits = data.commits.map((c) => ({
+        hash: c.sha,
+        message: c.commit.message,
+        author: `${c.commit.author?.name ?? "unknown"} <${c.commit.author?.email ?? "unknown"}>`,
+        date: c.commit.author?.date ?? ""
+      }));
+      if (options?.pathFilter) {
+        const changedPaths = new Set((data.files ?? []).map((f) => f.filename));
+        commits = commits.filter(
+          () => Array.from(changedPaths).some((f) => f.startsWith(options.pathFilter))
+        );
       }
-      if (delta.length === 0) {
-        return {
-          success: true,
-          filesSynced: 0,
-          sourceBranch,
-          commitHash: null,
-          commitMessage: null,
-          conflictDetected: false
-        };
+      if (options?.maxCount) {
+        commits = commits.slice(0, options.maxCount);
       }
-      if (options.dryRun) {
-        return {
-          success: true,
-          filesSynced: delta.length,
-          sourceBranch,
-          commitHash: null,
-          commitMessage: `[dry-run] gitgov sync: ${delta.length} files`,
-          conflictDetected: false
-        };
+      return commits;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitHistoryRange ${fromHash}...${toHash}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitHistoryRange`);
+        }
+        throw new GitError(`Failed to get commit range: HTTP ${error.status}`);
       }
-      const { data: newTreeData } = await this.deps.octokit.rest.git.createTree({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        base_tree: targetCommit.tree.sha,
-        tree: treeEntries
-      });
-      const commitMessage = `gitgov sync: ${delta.length} files from ${sourceBranch}`;
-      const { data: newCommitData } = await this.deps.octokit.rest.git.createCommit({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        message: commitMessage,
-        tree: newTreeData.sha,
-        parents: [currentSha]
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-A6] Get commit message via Commits API
+   */
+  async getCommitMessage(commitHash) {
+    try {
+      const { data } = await this.octokit.rest.repos.getCommit({
+        owner: this.owner,
+        repo: this.repo,
+        ref: commitHash
       });
-      try {
-        await this.deps.octokit.rest.git.updateRef({
-          owner: this.deps.owner,
-          repo: this.deps.repo,
-          ref: `heads/${branchName}`,
-          sha: newCommitData.sha
-        });
-      } catch (error) {
-        if (isOctokitRequestError(error) && (error.status === 422 || error.status === 409)) {
-          return {
-            success: false,
-            filesSynced: 0,
-            sourceBranch,
-            commitHash: null,
-            commitMessage: null,
-            conflictDetected: true,
-            conflictInfo: {
-              type: "rebase_conflict",
-              affectedFiles: delta.map((d) => d.file),
-              message: "Remote gitgov-state ref has advanced since last read. Pull and retry.",
-              resolutionSteps: [
-                "Call pullState() to fetch latest remote state",
-                "Retry pushState() with updated parent SHA"
-              ]
-            }
-          };
+      return data.commit.message;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new GitError(`Commit not found: ${commitHash}`);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitMessage ${commitHash}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitMessage`);
         }
-        throw error;
       }
-      this.lastKnownSha = newCommitData.sha;
-      return {
-        success: true,
-        filesSynced: delta.length,
-        sourceBranch,
-        commitHash: newCommitData.sha,
-        commitMessage,
-        conflictDetected: false
-      };
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY A: BRANCH OPERATIONS (EARS-B1 to B2)
+  // ═══════════════════════════════════════════════════════════════
+  /**
+   * [EARS-B1] Check if branch exists via Branches API
+   */
+  async branchExists(branchName) {
+    try {
+      await this.octokit.rest.repos.getBranch({
+        owner: this.owner,
+        repo: this.repo,
+        branch: branchName
+      });
+      return true;
     } catch (error) {
       if (isOctokitRequestError(error)) {
-        return {
-          success: false,
-          filesSynced: 0,
-          sourceBranch,
-          commitHash: null,
-          commitMessage: null,
-          conflictDetected: false,
-          error: `GitHub API error (${error.status}): ${error.message}`
-        };
+        if (error.status === 404) return false;
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): branchExists ${branchName}`);
+        }
+        throw new GitError(`Failed to check branch: HTTP ${error.status}`);
       }
       const msg = error instanceof Error ? error.message : String(error);
-      return {
-        success: false,
-        filesSynced: 0,
-        sourceBranch,
-        commitHash: null,
-        commitMessage: null,
-        conflictDetected: false,
-        error: msg
-      };
+      throw new GitError(`network error: ${msg}`);
     }
   }
-  // ==================== Block C: Pull State ====================
   /**
-   * [EARS-GS-C1..C4] Pull remote state from gitgov-state branch.
-   *
-   * Fetches tree + blobs, updates lastKnownSha, triggers re-indexing.
+   * [EARS-B2] List remote branches via Branches API
+   * remoteName is ignored — repo itself is the implicit remote
    */
-  async pullState(options) {
-    const branchName = await this.getStateBranchName();
-    let remoteSha;
+  async listRemoteBranches(_remoteName) {
     try {
-      const { data: refData } = await this.deps.octokit.rest.git.getRef({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        ref: `heads/${branchName}`
+      const { data } = await this.octokit.rest.repos.listBranches({
+        owner: this.owner,
+        repo: this.repo
       });
-      remoteSha = refData.object.sha;
+      return data.map((b) => b.name);
     } catch (error) {
-      if (isOctokitRequestError(error) && error.status === 404) {
-        return {
-          success: true,
-          hasChanges: false,
-          filesUpdated: 0,
-          reindexed: false,
-          conflictDetected: false
-        };
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): listRemoteBranches`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): listRemoteBranches`);
+        }
+        throw new GitError(`Failed to list branches: HTTP ${error.status}`);
       }
-      throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
     }
-    if (this.lastKnownSha === remoteSha && !options?.forceReindex) {
-      return {
-        success: true,
-        hasChanges: false,
-        filesUpdated: 0,
-        reindexed: false,
-        conflictDetected: false
-      };
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY A: WRITE OPERATIONS (EARS-C1 to C7)
+  // ═══════════════════════════════════════════════════════════════
+  /** [EARS-C1] Read file content and store in staging buffer */
+  async add(filePaths, options) {
+    for (const filePath of filePaths) {
+      const content = options?.contentMap?.[filePath] ?? await this.getFileContent(this.activeRef, filePath);
+      this.stagingBuffer.set(filePath, content);
     }
-    const { data: commitData } = await this.deps.octokit.rest.git.getCommit({
-      owner: this.deps.owner,
-      repo: this.deps.repo,
-      commit_sha: remoteSha
-    });
-    const { data: treeData } = await this.deps.octokit.rest.git.getTree({
-      owner: this.deps.owner,
-      repo: this.deps.repo,
-      tree_sha: commitData.tree.sha,
-      recursive: "true"
-    });
-    const syncableFiles = (treeData.tree ?? []).filter(
-      (item) => item.type === "blob" && item.path && shouldSyncFile(item.path)
-    );
-    const filesUpdated = syncableFiles.length;
-    this.lastKnownSha = remoteSha;
-    let reindexed = false;
-    if (filesUpdated > 0 || options?.forceReindex) {
-      try {
-        await this.deps.indexer.computeProjection();
-        reindexed = true;
-      } catch {
-        reindexed = false;
-      }
+  }
+  /** [EARS-C2] Mark files as deleted in staging buffer */
+  async rm(filePaths) {
+    for (const filePath of filePaths) {
+      this.stagingBuffer.set(filePath, null);
     }
-    return {
-      success: true,
-      hasChanges: filesUpdated > 0,
-      filesUpdated,
-      reindexed,
-      conflictDetected: false
-    };
   }
-  // ==================== Block D: Change Detection ====================
+  /** [EARS-C7] Return staged file paths from buffer */
+  async getStagedFiles() {
+    return Array.from(this.stagingBuffer.keys());
+  }
   /**
-   * [EARS-GS-D1..D3] Calculate file delta between known state and current remote.
+   * [EARS-C6] Create branch via Refs API POST
    */
-  async calculateStateDelta(_sourceBranch) {
-    const branchName = await this.getStateBranchName();
-    let currentSha;
+  async createBranch(branchName, startPoint) {
+    const sha = startPoint ? await this.getCommitHash(startPoint) : await this.getCommitHash(this.activeRef);
     try {
-      const { data: refData } = await this.deps.octokit.rest.git.getRef({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        ref: `heads/${branchName}`
+      await this.octokit.rest.git.createRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `refs/heads/${branchName}`,
+        sha
       });
-      currentSha = refData.object.sha;
     } catch (error) {
-      if (isOctokitRequestError(error) && error.status === 404) {
-        return [];
+      if (isOctokitRequestError(error)) {
+        if (error.status === 422) {
+          throw new BranchAlreadyExistsError(branchName);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): createBranch ${branchName}`);
+        }
+        throw new GitError(`Failed to create branch ${branchName}: HTTP ${error.status}`);
       }
-      throw error;
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
     }
-    if (this.lastKnownSha === currentSha) {
-      return [];
+  }
+  /**
+   * Internal commit implementation shared by commit() and commitAllowEmpty().
+   *
+   * [EARS-C3] 6-step atomic transaction
+   * [EARS-C4] Clears staging buffer after successful commit
+   * [EARS-C5] Throws if staging buffer is empty (unless allowEmpty)
+   */
+  async commitInternal(message, author, allowEmpty = false) {
+    if (!allowEmpty && this.stagingBuffer.size === 0) {
+      throw new GitError("Nothing to commit: staging buffer is empty");
     }
-    if (this.lastKnownSha === null) {
-      const { data: commitData } = await this.deps.octokit.rest.git.getCommit({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
+    try {
+      const { data: refData } = await this.octokit.rest.git.getRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${this.activeRef}`
+      });
+      const currentSha = refData.object.sha;
+      const { data: commitData } = await this.octokit.rest.git.getCommit({
+        owner: this.owner,
+        repo: this.repo,
         commit_sha: currentSha
       });
-      const { data: treeData } = await this.deps.octokit.rest.git.getTree({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        tree_sha: commitData.tree.sha,
-        recursive: "true"
+      const treeSha = commitData.tree.sha;
+      const treeEntries = [];
+      for (const [path2, content] of this.stagingBuffer) {
+        if (content === null) {
+          treeEntries.push({
+            path: path2,
+            mode: "100644",
+            type: "blob",
+            sha: null
+          });
+        } else {
+          const { data: blobData } = await this.octokit.rest.git.createBlob({
+            owner: this.owner,
+            repo: this.repo,
+            content: Buffer.from(content).toString("base64"),
+            encoding: "base64"
+          });
+          treeEntries.push({
+            path: path2,
+            mode: "100644",
+            type: "blob",
+            sha: blobData.sha
+          });
+        }
+      }
+      const { data: treeData } = await this.octokit.rest.git.createTree({
+        owner: this.owner,
+        repo: this.repo,
+        base_tree: treeSha,
+        tree: treeEntries
       });
-      return (treeData.tree ?? []).filter((item) => item.type === "blob" && item.path && shouldSyncFile(item.path)).map((item) => ({
-        status: "A",
-        file: item.path
-      }));
+      const newTreeSha = treeData.sha;
+      const commitParams = {
+        owner: this.owner,
+        repo: this.repo,
+        message,
+        tree: newTreeSha,
+        parents: [currentSha]
+      };
+      if (author) {
+        commitParams.author = {
+          name: author.name,
+          email: author.email,
+          date: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+      const { data: newCommitData } = await this.octokit.rest.git.createCommit(commitParams);
+      const newCommitSha = newCommitData.sha;
+      try {
+        await this.octokit.rest.git.updateRef({
+          owner: this.owner,
+          repo: this.repo,
+          ref: `heads/${this.activeRef}`,
+          sha: newCommitSha
+        });
+      } catch (error) {
+        if (isOctokitRequestError(error) && error.status === 422) {
+          throw new GitError("non-fast-forward update rejected");
+        }
+        throw error;
+      }
+      this.stagingBuffer.clear();
+      return newCommitSha;
+    } catch (error) {
+      if (error instanceof GitError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): commit`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): commit`);
+        }
+        throw new GitError(`GitHub API error (${error.status}): commit`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
     }
-    const { data: comparison } = await this.deps.octokit.rest.repos.compareCommits({
-      owner: this.deps.owner,
-      repo: this.deps.repo,
-      base: this.lastKnownSha,
-      head: currentSha
-    });
-    return (comparison.files ?? []).filter((file) => shouldSyncFile(file.filename)).map((file) => ({
-      status: file.status === "added" ? "A" : file.status === "removed" ? "D" : "M",
-      file: file.filename
-    }));
   }
   /**
-   * Always empty — no local pending changes in API mode.
-   * In API mode there is no local filesystem; all state is remote.
+   * [EARS-C3] Commit staged changes via 6-step atomic transaction
+   * [EARS-C5] Throws if staging buffer is empty
    */
-  async getPendingChanges() {
-    return [];
+  async commit(message, author) {
+    return this.commitInternal(message, author, false);
   }
-  // ==================== Block E: Conflict Handling ====================
-  /**
-   * Always false — no rebase in API mode.
-   */
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY B: NO-OPS (sensible defaults)
+  // ═══════════════════════════════════════════════════════════════
+  /** [EARS-D5] exec not supported in API mode */
+  async exec(_command, _args, _options) {
+    return { exitCode: 1, stdout: "", stderr: "exec() not supported in GitHub API mode" };
+  }
+  /** No-op: repos are created via GitHub API, not initialized locally */
+  async init() {
+  }
+  /** [EARS-D1] Return virtual path representing the repo */
+  async getRepoRoot() {
+    return `github://${this.owner}/${this.repo}`;
+  }
+  /** [EARS-D1] Return active ref (starts as defaultBranch) */
+  async getCurrentBranch() {
+    return this.activeRef;
+  }
+  /** No-op: git config doesn't apply to GitHub API */
+  async setConfig(_key, _value, _scope) {
+  }
+  /** [EARS-D1] Return true if staging buffer has entries */
+  async hasUncommittedChanges(_pathFilter) {
+    return this.stagingBuffer.size > 0;
+  }
+  /** No-op: GitHub API doesn't have rebase-in-progress concept */
   async isRebaseInProgress() {
     return false;
   }
-  /**
-   * Always empty — no conflict markers in API mode.
-   */
-  async checkConflictMarkers(_filePaths) {
+  /** [EARS-D1] GitHub repos always have 'origin' conceptually */
+  async isRemoteConfigured(_remoteName) {
+    return true;
+  }
+  /** No-op: always 'origin' */
+  async getBranchRemote(_branchName) {
+    return "origin";
+  }
+  /** No-op: GitHub API handles merges atomically */
+  async getConflictedFiles() {
     return [];
   }
-  /**
-   * Empty diff — no git-level conflict markers in API mode.
-   */
-  async getConflictDiff(_filePaths) {
-    return {
-      files: [],
-      message: "No conflict markers in API mode. Conflicts are SHA-based.",
-      resolutionSteps: [
-        "Call pullState() to fetch latest remote state",
-        "Retry pushState() with updated records"
-      ]
-    };
+  /** [EARS-D2] Update activeRef for subsequent operations */
+  async checkoutBranch(branchName) {
+    this.activeRef = branchName;
+  }
+  /** No-op: GitHub API doesn't have stash concept */
+  async stash(_message) {
+    return null;
+  }
+  /** No-op */
+  async stashPop() {
+    return false;
+  }
+  /** No-op */
+  async stashDrop(_stashHash) {
+  }
+  /** No-op: API always fresh */
+  async fetch(_remote) {
+  }
+  /** No-op: API mode */
+  async pull(_remote, _branchName) {
+  }
+  /** No-op: API mode */
+  async pullRebase(_remote, _branchName) {
+  }
+  /** [EARS-D4] No-op: commits via API are already remote */
+  async push(_remote, _branchName) {
+  }
+  /** [EARS-D4] No-op: commits via API are already remote */
+  async pushWithUpstream(_remote, _branchName) {
+  }
+  /** No-op: API mode */
+  async setUpstream(_branchName, _remote, _remoteBranch) {
+  }
+  /** No-op */
+  async rebaseAbort() {
+  }
+  /** [EARS-D1] Delegates to commitInternal, allowing empty staging buffer */
+  async commitAllowEmpty(message, author) {
+    return this.commitInternal(message, author, true);
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY C: NOT SUPPORTED (throw GitError)
+  // ═══════════════════════════════════════════════════════════════
+  /** [EARS-D3] Not supported via GitHub API */
+  async rebase(_targetBranch) {
+    this.notSupported("rebase");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async rebaseContinue() {
+    this.notSupported("rebaseContinue");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async resetHard(_target) {
+    this.notSupported("resetHard");
   }
-  /**
-   * [EARS-GS-E1..E2] Resolve conflict by pulling latest and retrying push.
-   */
-  async resolveConflict(options) {
-    const pullResult = await this.pullState({ forceReindex: false });
-    if (!pullResult.success) {
-      return {
-        success: false,
-        rebaseCommitHash: "",
-        resolutionCommitHash: "",
-        conflictsResolved: 0,
-        resolvedBy: options.actorId,
-        reason: options.reason,
-        error: `Pull failed during conflict resolution: ${pullResult.error}`
-      };
-    }
-    const pushResult = await this.pushState({
-      actorId: options.actorId
-    });
-    if (!pushResult.success || pushResult.conflictDetected) {
-      const errorMsg = pushResult.conflictDetected ? "Content conflict: same file modified by both sides. Manual resolution required." : pushResult.error ?? "Unknown push error";
-      return {
-        success: false,
-        rebaseCommitHash: "",
-        resolutionCommitHash: "",
-        conflictsResolved: 0,
-        resolvedBy: options.actorId,
-        reason: options.reason,
-        error: errorMsg
-      };
-    }
-    return {
-      success: true,
-      rebaseCommitHash: this.lastKnownSha ?? "",
-      resolutionCommitHash: pushResult.commitHash ?? "",
-      conflictsResolved: pushResult.filesSynced,
-      resolvedBy: options.actorId,
-      reason: options.reason
-    };
+  /** [EARS-D3] Not supported via GitHub API */
+  async checkoutOrphanBranch(_branchName) {
+    this.notSupported("checkoutOrphanBranch");
   }
-  /**
-   * No integrity violations in API mode (no rebase commits).
-   */
-  async verifyResolutionIntegrity() {
-    return [];
+  /** [EARS-D3] Not supported via GitHub API */
+  async checkoutFilesFromBranch(_sourceBranch, _filePaths) {
+    this.notSupported("checkoutFilesFromBranch");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async getMergeBase(_branchA, _branchB) {
+    this.notSupported("getMergeBase");
+  }
+};
+
+// src/config_store/github/github_config_store.ts
+var GitHubConfigStore = class {
+  owner;
+  repo;
+  ref;
+  basePath;
+  octokit;
+  /** Cached blob SHA from the last loadConfig call, used for PUT updates */
+  cachedSha = null;
+  constructor(options, octokit) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.ref = options.ref ?? "gitgov-state";
+    this.basePath = options.basePath ?? ".gitgov";
+    this.octokit = octokit;
   }
-  // ==================== Block F: Audit ====================
   /**
-   * [EARS-GS-F1..F2] Audit the remote gitgov-state branch.
+   * Load project configuration from GitHub Contents API.
+   *
+   * [EARS-A1] Returns GitGovConfig when valid JSON is found.
+   * [EARS-A2] Returns null on 404 (fail-safe).
+   * [EARS-A3] Returns null on invalid JSON (fail-safe).
+   * [EARS-B1] Fetches via Contents API with base64 decode.
+   * [EARS-B2] Caches SHA from response for subsequent saveConfig.
    */
-  async auditState(options) {
-    const branchName = await this.getStateBranchName();
-    const scope = options?.scope ?? "all";
-    let totalCommits = 0;
+  async loadConfig() {
+    const path2 = `${this.basePath}/config.json`;
     try {
-      const { data: commits } = await this.deps.octokit.rest.repos.listCommits({
-        owner: this.deps.owner,
-        repo: this.deps.repo,
-        sha: branchName,
-        per_page: 100
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: path2,
+        ref: this.ref
       });
-      totalCommits = commits.length;
-    } catch (error) {
-      if (isOctokitRequestError(error) && error.status === 404) {
-        return {
-          passed: true,
-          scope,
-          totalCommits: 0,
-          rebaseCommits: 0,
-          resolutionCommits: 0,
-          integrityViolations: [],
-          summary: "Branch gitgov-state does not exist. No audit needed."
-        };
+      if (Array.isArray(data) || data.type !== "file") {
+        return null;
       }
-      throw error;
-    }
-    const rebaseCommits = 0;
-    const resolutionCommits = 0;
-    const integrityViolations = [];
-    let lintReport;
-    if (options?.verifySignatures !== false || options?.verifyChecksums !== false) {
+      if (!data.content) {
+        return null;
+      }
+      this.cachedSha = data.sha;
       try {
-        const { data: refData } = await this.deps.octokit.rest.git.getRef({
-          owner: this.deps.owner,
-          repo: this.deps.repo,
-          ref: `heads/${branchName}`
-        });
-        const { data: commitData } = await this.deps.octokit.rest.git.getCommit({
-          owner: this.deps.owner,
-          repo: this.deps.repo,
-          commit_sha: refData.object.sha
-        });
-        const { data: treeData } = await this.deps.octokit.rest.git.getTree({
-          owner: this.deps.owner,
-          repo: this.deps.repo,
-          tree_sha: commitData.tree.sha,
-          recursive: "true"
-        });
-        const treeItems = (treeData.tree ?? []).filter((item) => item.type === "blob" && item.path && item.sha && shouldSyncFile(item.path));
-        const startTime = Date.now();
-        const allResults = [];
-        let filesChecked = 0;
-        for (const item of treeItems) {
-          try {
-            const { data: blobData } = await this.deps.octokit.rest.git.getBlob({
-              owner: this.deps.owner,
-              repo: this.deps.repo,
-              file_sha: item.sha
-            });
-            const content = Buffer.from(blobData.content, "base64").toString("utf-8");
-            const record = JSON.parse(content);
-            const entityType = pathToEntityType(item.path);
-            if (entityType) {
-              const results = this.deps.lint.lintRecord(record, {
-                recordId: item.path.split("/").pop()?.replace(".json", "") ?? item.path,
-                entityType,
-                filePath: item.path
-              });
-              allResults.push(...results);
-            }
-            filesChecked++;
-          } catch {
-          }
-        }
-        if (filesChecked > 0) {
-          lintReport = {
-            summary: {
-              filesChecked,
-              errors: allResults.filter((r) => r.level === "error").length,
-              warnings: allResults.filter((r) => r.level === "warning").length,
-              fixable: allResults.filter((r) => r.fixable).length,
-              executionTime: Date.now() - startTime
-            },
-            results: allResults,
-            metadata: {
-              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-              options: {},
-              version: "1.0.0"
-            }
-          };
-        }
+        const decoded = Buffer.from(data.content, "base64").toString("utf-8");
+        return JSON.parse(decoded);
       } catch {
+        return null;
       }
+    } catch (error) {
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return null;
+      }
+      throw mapOctokitError(error, `loadConfig ${this.owner}/${this.repo}/${path2}`);
     }
-    const lintPassed = !lintReport || lintReport.summary.errors === 0;
-    const passed = integrityViolations.length === 0 && lintPassed;
-    const lintErrors = lintReport?.summary.errors ?? 0;
-    let summary;
-    if (passed) {
-      summary = `Audit passed. ${totalCommits} commits analyzed, 0 violations.`;
-    } else if (integrityViolations.length > 0 && lintErrors > 0) {
-      summary = `Audit failed. ${integrityViolations.length} integrity violations, ${lintErrors} lint errors.`;
-    } else if (lintErrors > 0) {
-      summary = `Audit failed. ${lintErrors} lint errors found.`;
-    } else {
-      summary = `Audit failed. ${integrityViolations.length} integrity violations found.`;
-    }
-    const report = {
-      passed,
-      scope,
-      totalCommits,
-      rebaseCommits,
-      resolutionCommits,
-      integrityViolations,
-      summary
-    };
-    if (lintReport) {
-      report.lintReport = lintReport;
+  }
+  /**
+   * Save project configuration to GitHub via Contents API PUT.
+   *
+   * [EARS-A4] Writes config via PUT to Contents API.
+   * [EARS-B3] Includes cached SHA for updates (optimistic concurrency).
+   * [EARS-B4] Omits SHA for initial creation.
+   * [EARS-C1] Throws PERMISSION_DENIED on 401/403.
+   * [EARS-C2] Throws CONFLICT on 409.
+   * [EARS-C3] Throws SERVER_ERROR on 5xx.
+   */
+  async saveConfig(config) {
+    const path2 = `${this.basePath}/config.json`;
+    const content = Buffer.from(JSON.stringify(config, null, 2)).toString("base64");
+    try {
+      const { data } = await this.octokit.rest.repos.createOrUpdateFileContents({
+        owner: this.owner,
+        repo: this.repo,
+        path: path2,
+        message: "chore(config): update gitgov config.json",
+        content,
+        branch: this.ref,
+        ...this.cachedSha ? { sha: this.cachedSha } : {}
+      });
+      if (data.content?.sha) {
+        this.cachedSha = data.content.sha;
+      }
+      return { commitSha: data.commit.sha };
+    } catch (error) {
+      throw mapOctokitError(error, `saveConfig ${this.owner}/${this.repo}/${path2}`);
     }
-    return report;
   }
 };
-function pathToEntityType(filePath) {
-  const dirMap = {
-    tasks: "task",
-    cycles: "cycle",
-    actors: "actor",
-    agents: "agent",
-    feedbacks: "feedback",
-    executions: "execution",
-    changelogs: "changelog"
-  };
-  const firstSegment = filePath.split("/")[0] ?? "";
-  return dirMap[firstSegment];
-}
 
 // src/github.ts
 var GitHubApiError = class _GitHubApiError extends Error {