@gitgov/core 1.13.0 → 2.1.0

package/dist/src/fs.d.ts

@@ -0,0 +1,1369 @@
+import { R as RecordStore, C as ConfigStore, G as GitGovConfig, S as SessionStore, a as GitGovSession, I as IGitModule, b as GitModuleDependencies, E as ExecOptions, c as ExecResult, d as ChangedFile, e as GetCommitHistoryOptions, f as CommitInfo, g as CommitAuthor } from './index--ahcnsG3.js';
+export { F as FsFileListerOptions } from './index--ahcnsG3.js';
+import { C as ConfigManager, S as SessionManager, I as ILintModule, L as LintOptions, a as LintReport, F as FixRecordOptions, b as FixReport, R as RecordStores, c as IIndexerAdapter, G as GitGovRecord, d as LintRecordContext, e as LintResult, f as IProjectInitializer, E as EnvironmentValidation, g as ISyncStateModule, h as SyncStateModuleDependencies, i as StateDeltaFile, j as ConflictDiff, k as IntegrityViolation, A as AuditStateOptions, l as AuditStateReport, m as SyncStatePushOptions, n as SyncStatePushResult, o as SyncStatePullOptions, p as SyncStatePullResult, q as SyncStateResolveOptions, r as SyncStateResolveResult, s as IEventStream, t as IAgentRunner, P as ProtocolHandlerRegistry, u as AgentRunnerDependencies, v as RunOptions, w as AgentResponse } from './agent_runner-ByOUWOt6.js';
+export { z as FsFileLister, x as FsKeyProvider, y as FsKeyProviderOptions } from './agent_runner-ByOUWOt6.js';
+
+/**
+ * Serializer for FsRecordStore - allows custom serialization
+ */
+interface Serializer {
+    stringify: (value: unknown) => string;
+    parse: <T>(text: string) => T;
+}
+/**
+ * IdEncoder for transforming IDs to filesystem-safe filenames
+ * Useful for characters not allowed in filesystem (e.g., `:` on Windows)
+ */
+interface IdEncoder {
+    /** Transform ID to filename-safe string */
+    encode: (id: string) => string;
+    /** Recover original ID from filename */
+    decode: (encoded: string) => string;
+}
+/**
+ * Default encoder: `:` → `_` (for IDs like "human:camilo")
+ * Reversible because IDs cannot contain `_` (see id_generator.ts)
+ */
+declare const DEFAULT_ID_ENCODER: IdEncoder;
+/**
+ * Options for FsRecordStore
+ */
+interface FsRecordStoreOptions {
+    /** Base directory for files */
+    basePath: string;
+    /** File extension (default: ".json") */
+    extension?: string;
+    /** Custom serializer (default: JSON with indent 2) */
+    serializer?: Serializer;
+    /** Create directory if it doesn't exist (default: true) */
+    createIfMissing?: boolean;
+    /** ID encoder for filesystem-safe filenames (default: undefined = no encoding) */
+    idEncoder?: IdEncoder;
+}
+/**
+ * FsRecordStore<T> - Filesystem implementation of Store<T>
+ *
+ * Persists records as JSON files on disk.
+ *
+ * @example
+ * const store = new FsRecordStore<TaskRecord>({
+ *   basePath: '.gitgov/tasks',
+ * });
+ *
+ * await store.put('123-task-foo', task);
+ * const task = await store.get('123-task-foo');
+ */
+declare class FsRecordStore<T> implements RecordStore<T> {
+    private readonly basePath;
+    private readonly extension;
+    private readonly serializer;
+    private readonly createIfMissing;
+    private readonly idEncoder;
+    constructor(options: FsRecordStoreOptions);
+    private getFilePath;
+    get(id: string): Promise<T | null>;
+    put(id: string, value: T): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(): Promise<string[]>;
+    exists(id: string): Promise<boolean>;
+}
+
+/**
+ * FsConfigStore - Filesystem implementation of ConfigStore
+ *
+ * Handles persistence of config.json to the local filesystem.
+ *
+ * NOTE: Session state (.session.json) is handled by FsSessionStore.
+ * NOTE: Project discovery utilities are in src/utils/project_discovery.ts
+ */
+
+/**
+ * Filesystem-based ConfigStore implementation.
+ *
+ * Stores configuration in .gitgov/config.json.
+ * Implements fail-safe pattern: returns null instead of throwing for missing files.
+ *
+ * @example
+ * ```typescript
+ * const store = new FsConfigStore('/path/to/project');
+ * const config = await store.loadConfig();
+ * if (config) {
+ *   console.log(config.projectName);
+ * }
+ * ```
+ */
+declare class FsConfigStore implements ConfigStore {
+    private readonly configPath;
+    constructor(projectRootPath: string);
+    /**
+     * Load project configuration from .gitgov/config.json
+     *
+     * [EARS-A1] Returns complete GitGovConfig for valid files
+     * [EARS-A2] Returns null for non-existent files (fail-safe)
+     * [EARS-A3] Returns null for invalid JSON (graceful degradation)
+     */
+    loadConfig(): Promise<GitGovConfig | null>;
+    /**
+     * Save project configuration to .gitgov/config.json
+     *
+     * [EARS-A4] Writes config with JSON indentation
+     */
+    saveConfig(config: GitGovConfig): Promise<void>;
+}
+/**
+ * Create a ConfigManager instance for a project.
+ *
+ * [EARS-B1] Factory function that creates a ConfigManager with FsConfigStore backend.
+ * Use this when you already have the projectRoot (e.g., from DI container).
+ *
+ * @param projectRoot - Absolute path to project root (REQUIRED)
+ * @returns ConfigManager instance with FsConfigStore backend
+ */
+declare function createConfigManager(projectRoot: string): ConfigManager;
+
+/**
+ * FsSessionStore - Filesystem implementation of SessionStore
+ *
+ * Handles persistence of .session.json to the local filesystem.
+ * Session files are machine-local and NOT versioned in Git.
+ */
+
+/**
+ * Filesystem-based SessionStore implementation.
+ *
+ * Stores session state in .gitgov/.session.json.
+ * Implements fail-safe pattern: returns null instead of throwing for missing files.
+ *
+ * @example
+ * ```typescript
+ * const store = new FsSessionStore('/path/to/project');
+ * const session = await store.loadSession();
+ * if (session) {
+ *   console.log(session.lastSession?.actorId);
+ * }
+ * ```
+ */
+declare class FsSessionStore implements SessionStore {
+    private readonly sessionPath;
+    private readonly actorsPath;
+    constructor(projectRootPath: string);
+    /**
+     * Load local session from .gitgov/.session.json
+     *
+     * [EARS-A1] Returns complete GitGovSession for valid files
+     * [EARS-A2] Returns null for non-existent files (fail-safe)
+     * [EARS-A3] Returns null for invalid JSON (graceful degradation)
+     * [EARS-A4] Returns cloud token if present
+     * [EARS-A5] Returns syncPreferences if present
+     */
+    loadSession(): Promise<GitGovSession | null>;
+    /**
+     * Save local session to .gitgov/.session.json
+     *
+     * [EARS-B1] Writes session to .gitgov/.session.json with JSON indentation
+     * [EARS-B2] Preserves all fields (cloud, actorState, syncPreferences)
+     */
+    saveSession(session: GitGovSession): Promise<void>;
+    /**
+     * Detect actor from .key files in .gitgov/actors/
+     *
+     * [EARS-C1] Returns actor ID from first .key file
+     * [EARS-C2] Returns first .key file alphabetically if multiple exist
+     * [EARS-C3] Returns null if no .key files exist
+     * [EARS-C4] Returns null if actors directory doesn't exist
+     * [EARS-C5] Ignores non-.key files
+     * [EARS-C6] Returns null for empty directory
+     *
+     * @returns Actor ID (e.g., "human:camilo-v2") or null
+     */
+    detectActorFromKeyFiles(): Promise<string | null>;
+}
+/**
+ * Create a SessionManager instance for a project.
+ *
+ * [EARS-D1] Factory function that creates a SessionManager with FsSessionStore backend.
+ * Use this when you already have the projectRoot (e.g., from DI container).
+ *
+ * @param projectRoot - Absolute path to project root (REQUIRED)
+ * @returns SessionManager instance with FsSessionStore backend
+ */
+declare function createSessionManager(projectRoot: string): SessionManager;
+
+/**
+ * Filesystem-specific types for FsLintModule.
+ *
+ * These types are exported via @gitgov/core/fs subpath.
+ * For pure validation types, use @gitgov/core.
+ */
+
+/**
+ * Public interface for FsLintModule operations (with I/O).
+ *
+ * This interface wraps LintModule and adds filesystem operations:
+ * - Directory scanning for record discovery
+ * - File reading and parsing
+ * - Backup creation and restoration
+ * - File writing for fixes
+ *
+ * @example
+ * ```typescript
+ * const fsLintModule: IFsLintModule = new FsLintModule({
+ *   lintModule,
+ *   stores
+ * });
+ *
+ * // Scan directory and validate all records
+ * const report = await fsLintModule.lint({ path: '.gitgov/' });
+ *
+ * // Validate specific file
+ * const fileReport = await fsLintModule.lintFile(filePath);
+ *
+ * // Fix with backups
+ * const fixReport = await fsLintModule.fix(report, { createBackups: true });
+ * ```
+ */
+interface IFsLintModule extends ILintModule {
+    /**
+     * Scans directories and validates all records.
+     * Overrides ILintModule.lint() to accept filesystem-specific options.
+     */
+    lint(options?: Partial<FsLintOptions>): Promise<LintReport>;
+    /**
+     * Validates a specific file.
+     */
+    lintFile(filePath: string, options?: Partial<FsLintOptions>): Promise<LintReport>;
+    /**
+     * Applies automatic repairs to files, creating backups.
+     */
+    fix(lintReport: LintReport, fixOptions?: Partial<FsFixOptions>): Promise<FixReport>;
+}
+/**
+ * Dependencies for FsLintModule.
+ */
+interface FsLintModuleDependencies {
+    /** Absolute path to project root (REQUIRED, injected from DI/CLI bootstrap) */
+    projectRoot: string;
+    /** Core LintModule for pure validation (REQUIRED) */
+    lintModule: ILintModule;
+    /** Record stores for reference lookups (OPTIONAL) */
+    stores?: RecordStores;
+    /** Indexer adapter for reference resolution (OPTIONAL) */
+    indexerAdapter?: IIndexerAdapter;
+    /** FileSystem abstraction for I/O (OPTIONAL, default: Node.js fs) */
+    fileSystem?: FileSystem;
+}
+/**
+ * Options for FsLintModule operations.
+ * Extends LintOptions with filesystem-specific settings.
+ */
+interface FsLintOptions extends LintOptions {
+    /** Directory or file to validate (default: '.gitgov/') */
+    path?: string;
+    /** Validate file naming conventions (default: true) */
+    validateFileNaming?: boolean;
+}
+/**
+ * Options for FsLintModule fix operation.
+ * Extends FixRecordOptions with filesystem-specific settings.
+ */
+interface FsFixOptions extends FixRecordOptions {
+    /** Create backups before modifying files (default: true) */
+    createBackups?: boolean;
+    /** Dry-run mode that reports without applying changes (default: false) */
+    dryRun?: boolean;
+}
+/**
+ * FileSystem interface for I/O operations.
+ * Can be mocked for testing.
+ */
+interface FileSystem {
+    readFile(path: string, encoding: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    unlink(path: string): Promise<void>;
+    readdir?(path: string): Promise<string[]>;
+}
+
+/**
+ * FsLintModule - Filesystem-aware Validation
+ *
+ * This module wraps the pure LintModule and adds filesystem operations:
+ * - Directory scanning for record discovery (EARS-A1)
+ * - File naming validation (EARS-B1, EARS-B2)
+ * - Backup creation and restoration (EARS-C1, EARS-C2)
+ * - Delegation to LintModule core (EARS-D1)
+ * - Schema version detection (EARS-E1)
+ * - Error filtering (EARS-F1)
+ *
+ * @see fs_lint_module.md for EARS specifications
+ * @module lint/fs
+ */
+
+/**
+ * Filesystem-aware lint module.
+ * Wraps LintModule (pure) and adds I/O operations.
+ *
+ * @implements {IFsLintModule}
+ */
+declare class FsLintModule implements IFsLintModule {
+    private readonly projectRoot;
+    private readonly lintModule;
+    private readonly fileSystem;
+    private lastBackupPath;
+    /**
+     * Constructor for FsLintModule.
+     *
+     * @param dependencies - Module dependencies
+     */
+    constructor(dependencies: FsLintModuleDependencies);
+    /**
+     * Delegates to LintModule.lintRecord() for pure validation.
+     */
+    lintRecord(record: GitGovRecord, context: LintRecordContext): LintResult[];
+    /**
+     * Delegates to LintModule.fixRecord() for pure fix.
+     */
+    fixRecord(record: GitGovRecord, results: LintResult[], options: FixRecordOptions): GitGovRecord;
+    /**
+     * [EARS-A1] Scans directories and validates all records.
+     *
+     * @param options - Configuration options
+     * @returns Consolidated lint report
+     */
+    lint(options?: Partial<FsLintOptions>): Promise<LintReport>;
+    /**
+     * Validates a specific file.
+     *
+     * @param filePath - Path to the file to validate
+     * @param options - Configuration options
+     * @returns Lint report for this single file
+     */
+    lintFile(filePath: string, options?: Partial<FsLintOptions>): Promise<LintReport>;
+    /**
+     * Applies automatic repairs to files, creating backups.
+     *
+     * @param lintReport - Lint report with detected problems
+     * @param fixOptions - Options for the fix operation
+     * @returns Report of applied repairs
+     */
+    fix(lintReport: LintReport, fixOptions?: Partial<FsFixOptions>): Promise<FixReport>;
+    /**
+     * Validates a single record by reading from filesystem.
+     * @private
+     */
+    private lintSingleRecord;
+    /**
+     * [EARS-B1, EARS-B2] Validates file naming conventions.
+     * @private
+     */
+    private validateFileNaming;
+    /**
+     * [EARS-A1] Discovers all records with their types by scanning filesystem.
+     * @private
+     */
+    private discoverAllRecordsWithTypes;
+    /**
+     * Gets file path for a record.
+     * @private
+     */
+    private getFilePath;
+    /**
+     * [EARS-C1] Creates a backup of a file before modification.
+     * @private
+     */
+    private createBackup;
+    /**
+     * [EARS-C2] Restores file from backup if fix fails.
+     * @private
+     */
+    private restoreBackup;
+    /**
+     * Applies a fix to a file.
+     * @private
+     */
+    private applyFix;
+    /**
+     * Fixes legacy record with embedded metadata issues.
+     * @private
+     */
+    private fixLegacyRecord;
+    /**
+     * Fixes bidirectional reference inconsistencies.
+     * @private
+     */
+    private fixBidirectionalReference;
+    /**
+     * Recalculates checksum for a record.
+     * @private
+     */
+    private recalculateChecksum;
+    /**
+     * Fixes signature structure issues.
+     * @private
+     */
+    private fixSignatureStructure;
+    /**
+     * [EARS-E1] Detects validator type from error message.
+     * Includes detection of SCHEMA_VERSION_MISMATCH for outdated schemas.
+     * @private
+     */
+    private detectValidatorType;
+    /**
+     * Determines if an error is fixable.
+     * @private
+     */
+    private isFixable;
+}
+
+/**
+ * FsProjectInitializer - Filesystem implementation of IProjectInitializer.
+ *
+ * Initializes GitGovernance projects on the local filesystem,
+ * creating the .gitgov/ directory structure and configuration files.
+ *
+ * The projectRoot is injected at construction time (DI from CLI/bootstrap).
+ *
+ * @example
+ * ```typescript
+ * const initializer = new FsProjectInitializer('/path/to/project');
+ *
+ * const validation = await initializer.validateEnvironment();
+ * if (!validation.isValid) {
+ *   console.log(validation.warnings);
+ *   return;
+ * }
+ *
+ * await initializer.createProjectStructure();
+ * await initializer.writeConfig(config);
+ * await initializer.initializeSession(actorId);
+ * await initializer.copyAgentPrompt();
+ * await initializer.setupGitIntegration();
+ * ```
+ */
+declare class FsProjectInitializer implements IProjectInitializer {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    /**
+     * Creates the .gitgov/ directory structure.
+     */
+    createProjectStructure(): Promise<void>;
+    /**
+     * Checks if .gitgov/config.json exists.
+     */
+    isInitialized(): Promise<boolean>;
+    /**
+     * Writes config.json to .gitgov/
+     */
+    writeConfig(config: GitGovConfig): Promise<void>;
+    /**
+     * Creates .session.json with initial actor state.
+     */
+    initializeSession(actorId: string): Promise<void>;
+    /**
+     * Reads a file from the filesystem.
+     */
+    readFile(filePath: string): Promise<string>;
+    /**
+     * Gets the path for an actor record.
+     */
+    getActorPath(actorId: string): string;
+    /**
+     * Validates environment for GitGovernance initialization.
+     * Checks: Git repo exists, write permissions, not already initialized.
+     */
+    validateEnvironment(): Promise<EnvironmentValidation>;
+    /**
+     * Copies the @gitgov agent prompt to project root for IDE access.
+     */
+    copyAgentPrompt(): Promise<void>;
+    /**
+     * Sets up .gitignore for GitGovernance files.
+     */
+    setupGitIntegration(): Promise<void>;
+    /**
+     * Removes .gitgov/ directory (for rollback on failed init).
+     */
+    rollback(): Promise<void>;
+}
+
+/**
+ * LocalGitModule - Local Git Operations via CLI
+ *
+ * This module provides a business-agnostic abstraction layer for interacting
+ * with the local Git repository. It exposes semantic methods instead of raw
+ * Git commands, with comprehensive error handling and type safety.
+ *
+ * Uses execCommand (injected) to run git CLI commands.
+ *
+ * @module git/local
+ */
+
+/**
+ * LocalGitModule - CLI-based implementation of IGitModule
+ *
+ * All operations are async and use dependency injection for testability.
+ * Errors are transformed into typed exceptions for better handling.
+ *
+ * For unit tests without git, use MemoryGitModule instead.
+ */
+declare class LocalGitModule implements IGitModule {
+    private repoRoot;
+    private execCommand;
+    /**
+     * Creates a new LocalGitModule instance
+     *
+     * @param dependencies - Required dependencies (execCommand) and optional config (repoRoot)
+     * @throws Error if execCommand is not provided
+     */
+    constructor(dependencies: GitModuleDependencies);
+    /**
+     * Ensures that repoRoot is set, auto-detecting it if necessary
+     *
+     * @returns Path to repository root
+     * @throws GitCommandError if not in a Git repository
+     */
+    private ensureRepoRoot;
+    /**
+     * Executes a Git command with standardized error handling
+     *
+     * @param args - Git command arguments
+     * @param options - Execution options
+     * @returns Command result
+     * @throws GitCommandError if command fails
+     */
+    private execGit;
+    /**
+     * Executes an arbitrary shell command with the repository as working directory.
+     *
+     * This method is intended for advanced use cases where the existing
+     * semantic methods don't cover the needed functionality. Use with caution.
+     *
+     * @param command - The command to execute (e.g., 'git')
+     * @param args - Command arguments
+     * @param options - Optional execution options
+     * @returns Command execution result with exitCode, stdout, stderr
+     *
+     * @example
+     * const result = await gitModule.exec('git', ['diff', '--name-only', 'HEAD~1..HEAD']);
+     * if (result.exitCode === 0) {
+     *   const files = result.stdout.split('\n');
+     * }
+     */
+    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Initializes a new Git repository in the current directory
+     *
+     * Creates the `.git/` directory structure and sets up initial configuration.
+     * Useful for testing and for commands that require a fresh repository.
+     *
+     * @throws GitCommandError if directory is already a Git repository
+     *
+     * @example
+     * await gitModule.init();
+     * // Repository initialized with default branch (main or master)
+     */
+    init(): Promise<void>;
+    /**
+     * Returns the absolute path to the current Git repository root
+     *
+     * @returns Repository root path
+     * @throws GitCommandError if not in a Git repository
+     *
+     * @example
+     * const repoRoot = await gitModule.getRepoRoot();
+     * // => "/home/user/my-project"
+     */
+    getRepoRoot(): Promise<string>;
+    /**
+     * Returns the name of the current branch (HEAD)
+     *
+     * @returns Current branch name
+     * @throws GitCommandError if in detached HEAD state or other error
+     *
+     * @example
+     * const branch = await gitModule.getCurrentBranch();
+     * // => "main"
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Get commit hash for a given reference (branch, tag, HEAD, etc.)
+     *
+     * Used by test helpers and sync operations to get commit SHAs.
+     * Returns the full 40-character SHA-1 hash of the commit.
+     *
+     * @param ref Git reference (default: "HEAD"). Can be:
+     *            - "HEAD" for current commit
+     *            - Branch name (e.g., "main", "gitgov-state")
+     *            - Tag name (e.g., "v1.0.0")
+     *            - Commit hash (returns the same hash)
+     *            - Relative refs (e.g., "HEAD~1", "main^")
+     * @returns Commit SHA hash (full 40-character hash)
+     * @throws GitCommandError if ref does not exist
+     *
+     * @example
+     * const headHash = await git.getCommitHash("HEAD");
+     * // => "a1b2c3d4e5f6..."
+     *
+     * const mainHash = await git.getCommitHash("main");
+     * // => "f6e5d4c3b2a1..."
+     *
+     * const parentHash = await git.getCommitHash("HEAD~1");
+     * // => "9876543210ab..."
+     */
+    getCommitHash(ref?: string): Promise<string>;
+    /**
+     * Set a Git configuration value.
+     * Used for configuring repository settings like user.name, core.editor, etc.
+     *
+     * [EARS-F1, EARS-F2]
+     *
+     * @param key - Configuration key (e.g., "user.name", "core.editor")
+     * @param value - Configuration value
+     * @param scope - Configuration scope: "local" (default), "global", or "system"
+     * @throws GitCommandError if configuration fails
+     *
+     * @example
+     * ```typescript
+     * // Set local config (repository-specific)
+     * await git.setConfig('core.editor', 'vim');
+     *
+     * // Set global config (user-wide)
+     * await git.setConfig('user.name', 'John Doe', 'global');
+     *
+     * // Set system config (machine-wide, requires permissions)
+     * await git.setConfig('credential.helper', 'cache', 'system');
+     * ```
+     */
+    setConfig(key: string, value: string, scope?: 'local' | 'global' | 'system'): Promise<void>;
+    /**
+     * Finds the most recent common ancestor between two branches
+     *
+     * @param branchA - First branch name
+     * @param branchB - Second branch name
+     * @returns Commit hash of the merge base
+     * @throws BranchNotFoundError if either branch does not exist
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const mergeBase = await gitModule.getMergeBase("main", "feature");
+     * // => "a1b2c3d4e5f6..."
+     */
+    getMergeBase(branchA: string, branchB: string): Promise<string>;
+    /**
+     * Returns a list of files changed between two commits
+     *
+     * @param fromCommit - Source commit or reference
+     * @param toCommit - Target commit or reference
+     * @param pathFilter - Optional path filter (e.g., ".gitgov/")
+     * @returns Array of changed files with their status
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const changes = await gitModule.getChangedFiles("HEAD~1", "HEAD", ".gitgov/");
+     * // => [{ status: "M", file: ".gitgov/tasks/123.json" }]
+     */
+    getChangedFiles(fromCommit: string, toCommit: string, pathFilter: string): Promise<ChangedFile[]>;
+    /**
+     * Get list of staged files (in staging area / index)
+     *
+     * Used during conflict resolution to identify which files the user resolved and staged.
+     *
+     * @returns Array of file paths that are currently staged
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * // After user resolves conflict and does: git add .gitgov/tasks/123.json
+     * const staged = await gitModule.getStagedFiles();
+     * // => [".gitgov/tasks/123.json"]
+     */
+    getStagedFiles(): Promise<string[]>;
+    /**
+     * Retrieves the content of a file at a specific point in history
+     *
+     * @param commitHash - Commit hash
+     * @param filePath - File path relative to repository root
+     * @returns File content as string
+     * @throws FileNotFoundError if file doesn't exist in that commit
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const content = await gitModule.getFileContent("abc123", ".gitgov/config.json");
+     * // => '{"version": "1.0.0"}'
+     */
+    getFileContent(commitHash: string, filePath: string): Promise<string>;
+    /**
+     * Retrieves the commit history for a branch
+     *
+     * @param branch - Branch name
+     * @param options - Filtering and formatting options
+     * @returns Array of commits ordered from newest to oldest
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const history = await gitModule.getCommitHistory("main", { maxCount: 10 });
+     * // => [{ hash: "abc123", message: "Initial commit", author: "User <email>", date: "2025-01-01T00:00:00Z" }]
+     */
+    getCommitHistory(branch: string, options?: GetCommitHistoryOptions): Promise<CommitInfo[]>;
+    /**
+     * Retrieves commit history in a specific range
+     *
+     * @param fromHash - Starting commit hash (exclusive)
+     * @param toHash - Ending commit hash (inclusive)
+     * @param options - Filtering and formatting options
+     * @returns Array of commits in the specified range
+     * @throws GitCommandError if either commit doesn't exist
+     *
+     * @example
+     * const commits = await gitModule.getCommitHistoryRange("abc123", "def456");
+     * // => [{ hash: "def456", ... }, { hash: "cba321", ... }]
+     */
+    getCommitHistoryRange(fromHash: string, toHash: string, options?: GetCommitHistoryOptions): Promise<CommitInfo[]>;
+    /**
+     * Retrieves the full commit message for a specific commit
+     *
+     * @param commitHash - Commit hash
+     * @returns Full commit message as string
+     * @throws GitCommandError if commit doesn't exist
+     *
+     * @example
+     * const message = await gitModule.getCommitMessage("abc123");
+     * // => "feat: add new feature\n\nDetailed description..."
+     */
+    getCommitMessage(commitHash: string): Promise<string>;
+    /**
+     * Checks if there are uncommitted changes in the working directory
+     *
+     * @param pathFilter - Optional path filter (e.g., ".gitgov/")
+     * @returns true if there are uncommitted changes, false otherwise
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const hasChanges = await gitModule.hasUncommittedChanges(".gitgov/");
+     * // => true
+     */
+    hasUncommittedChanges(pathFilter?: string): Promise<boolean>;
+    /**
+     * Checks if a rebase operation is currently in progress
+     *
+     * @returns true if rebase is in progress, false otherwise
+     *
+     * @example
+     * const inRebase = await gitModule.isRebaseInProgress();
+     * // => false
+     */
+    isRebaseInProgress(): Promise<boolean>;
+    /**
+     * Checks if a branch exists locally
+     *
+     * @param branchName - Branch name to check
+     * @returns true if branch exists, false otherwise
+     *
+     * @example
+     * const exists = await gitModule.branchExists("feature-branch");
+     * // => true
+     */
+    branchExists(branchName: string): Promise<boolean>;
+    /**
+     * Lists all remote branches for a given remote
+     *
+     * @param remoteName - Name of the remote (e.g., "origin")
+     * @returns Array of remote branch names without the remote prefix
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const branches = await gitModule.listRemoteBranches("origin");
+     * // => ["main", "develop", "gitgov-state"]
+     *
+     * @note This method only returns the branch names, not the full "origin/branch" format
+     */
+    listRemoteBranches(remoteName: string): Promise<string[]>;
+    /**
+     * Checks if a remote is configured in the git repository.
+     *
+     * @param remoteName - Name of the remote to check (e.g., "origin")
+     * @returns true if the remote is configured, false otherwise
+     *
+     * @example
+     * const hasOrigin = await gitModule.isRemoteConfigured("origin");
+     * // => true
+     */
+    isRemoteConfigured(remoteName: string): Promise<boolean>;
+    /**
+     * Retrieves the tracking remote for a branch
+     *
+     * @param branchName - Branch name
+     * @returns Remote name or null if not configured
+     * @throws BranchNotFoundError if branch doesn't exist
+     *
+     * @example
+     * const remote = await gitModule.getBranchRemote("main");
+     * // => "origin"
+     */
+    getBranchRemote(branchName: string): Promise<string | null>;
+    /**
+     * Retrieves the list of conflicted files during a rebase or merge
+     *
+     * @returns Array of file paths in conflict
+     * @throws GitCommandError if no rebase/merge in progress
+     *
+     * @example
+     * const conflicts = await gitModule.getConflictedFiles();
+     * // => [".gitgov/tasks/123.json", ".gitgov/tasks/456.json"]
+     */
+    getConflictedFiles(): Promise<string[]>;
+    /**
+     * Switches to the specified branch
+     *
+     * @param branchName - Branch name to checkout
+     * @throws BranchNotFoundError if branch doesn't exist
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.checkoutBranch("feature-branch");
+     */
+    checkoutBranch(branchName: string): Promise<void>;
+    /**
+     * Stash uncommitted changes
+     *
+     * @param message - Optional message for the stash
+     * @returns Stash hash if changes were stashed, null if nothing to stash
+     */
+    stash(message?: string): Promise<string | null>;
+    /**
+     * Pop the most recent stash
+     *
+     * @returns true if stash was popped successfully, false if no stash exists
+     */
+    stashPop(): Promise<boolean>;
+    /**
+     * Drop a specific stash or the most recent one
+     *
+     * @param stashHash - Optional stash hash to drop, defaults to most recent
+     */
+    stashDrop(stashHash?: string): Promise<void>;
+    /**
+     * Creates an orphan branch (no history) and switches to it
+     *
+     * @param branchName - Orphan branch name to create
+     * @throws GitCommandError if branch already exists or operation fails
+     *
+     * @example
+     * await gitModule.checkoutOrphanBranch("gitgov-state");
+     */
+    checkoutOrphanBranch(branchName: string): Promise<void>;
+    /**
+     * Fetches the latest changes from a remote repository
+     *
+     * @param remote - Remote name (e.g., "origin")
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.fetch("origin");
+     */
+    fetch(remote: string): Promise<void>;
+    /**
+     * Pulls and merges a remote branch
+     *
+     * @param remote - Remote name
+     * @param branchName - Branch name
+     * @throws MergeConflictError if merge conflicts occur
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.pull("origin", "main");
+     */
+    pull(remote: string, branchName: string): Promise<void>;
+    /**
+     * Pulls and rebases a remote branch
+     *
+     * @param remote - Remote name
+     * @param branchName - Branch name
+     * @throws RebaseConflictError if rebase conflicts occur
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.pullRebase("origin", "main");
+     */
+    pullRebase(remote: string, branchName: string): Promise<void>;
+    /**
+     * Resets the current branch to a specific commit, discarding all local changes
+     *
+     * @param target - Commit hash or branch name
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.resetHard("HEAD~1");
+     */
+    resetHard(target: string): Promise<void>;
+    /**
+     * Checks out specific files from another branch into the current staging area
+     *
+     * @param sourceBranch - Source branch name
+     * @param filePaths - Array of file paths to checkout
+     * @throws BranchNotFoundError if source branch doesn't exist
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.checkoutFilesFromBranch("main", [".gitgov/tasks/123.json"]);
+     */
+    checkoutFilesFromBranch(sourceBranch: string, filePaths: string[]): Promise<void>;
+    /**
+     * Adds files to the staging area
+     *
+     * @param filePaths - Array of file paths to add
+     * @param options - Optional settings (force: add ignored files)
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.add([".gitgov/tasks/123.json"]);
+     * await gitModule.add([".gitgov"], { force: true }); // Add ignored files
+     */
+    add(filePaths: string[], options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Removes files from both working directory and staging area
+     *
+     * @param filePaths - Array of file paths to remove
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.rm([".gitgov/tasks/123.json"]);
+     */
+    rm(filePaths: string[]): Promise<void>;
+    /**
+     * Creates a new commit with staged files
+     *
+     * @param message - Commit message
+     * @param author - Optional commit author
+     * @returns Commit hash of the created commit
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const hash = await gitModule.commit("feat: add new task");
+     * // => "abc123def456..."
+     */
+    commit(message: string, author?: CommitAuthor): Promise<string>;
+    /**
+     * Creates an empty commit (no changes required)
+     *
+     * @param message - Commit message
+     * @param author - Optional commit author
+     * @returns Commit hash of the created commit
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const hash = await gitModule.commitAllowEmpty("chore: initialize state branch");
+     * // => "abc123def456..."
+     */
+    commitAllowEmpty(message: string, author?: CommitAuthor): Promise<string>;
+    /**
+     * Pushes a local branch to a remote repository
+     *
+     * @param remote - Remote name
+     * @param branchName - Branch name
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.push("origin", "main");
+     */
+    push(remote: string, branchName: string): Promise<void>;
+    /**
+     * Pushes a local branch to a remote repository and sets up tracking
+     *
+     * @param remote - Remote name
+     * @param branchName - Branch name
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.pushWithUpstream("origin", "feature-branch");
+     */
+    pushWithUpstream(remote: string, branchName: string): Promise<void>;
+    /**
+     * Configures tracking for a local branch with a remote branch
+     *
+     * @param branchName - Local branch name
+     * @param remote - Remote name
+     * @param remoteBranch - Remote branch name
+     * @throws BranchNotFoundError if local branch doesn't exist
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.setUpstream("feature-branch", "origin", "feature-branch");
+     */
+    setUpstream(branchName: string, remote: string, remoteBranch: string): Promise<void>;
+    /**
+     * Continues a rebase after resolving conflicts
+     *
+     * @returns Commit hash of the rebased commit
+     * @throws RebaseNotInProgressError if no rebase is in progress
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * const hash = await gitModule.rebaseContinue();
+     * // => "abc123def456..."
+     */
+    rebaseContinue(): Promise<string>;
+    /**
+     * Aborts an ongoing rebase
+     *
+     * @throws RebaseNotInProgressError if no rebase is in progress
+     * @throws GitCommandError if operation fails
+     *
+     * @example
+     * await gitModule.rebaseAbort();
+     */
+    rebaseAbort(): Promise<void>;
+    /**
+     * Creates a new branch and switches to it (git checkout -b)
+     *
+     * @param branchName - Name of the branch to create
+     * @param startPoint - Optional starting point (commit hash or branch name)
+     * @throws GitCommandError if branch already exists or operation fails
+     * @throws BranchAlreadyExistsError if the branch already exists locally
+     */
+    createBranch(branchName: string, startPoint?: string): Promise<void>;
+    /**
+     * Rebases current branch onto target branch (git rebase)
+     *
+     * @param targetBranch - Branch to rebase onto
+     * @throws GitCommandError if rebase fails
+     * @throws RebaseConflictError if conflicts are detected during rebase
+     */
+    rebase(targetBranch: string): Promise<void>;
+}
+
+/**
+ * Project Discovery Utilities
+ *
+ * Filesystem-based utilities for discovering GitGovernance project roots.
+ * Used at CLI bootstrap to resolve projectRoot before injecting it via DI.
+ *
+ * NOTE: These functions should only be called at the CLI/bootstrap level.
+ * Core modules receive projectRoot via constructor injection.
+ */
+/**
+ * Finds the project root by searching upwards for a .git directory.
+ * Caches the result for subsequent calls.
+ *
+ * @param startPath - Starting path (default: process.cwd())
+ * @returns Path to project root, or null if not found
+ */
+declare function findProjectRoot(startPath?: string): string | null;
+/**
+ * Finds the project root by searching upwards.
+ * First looks for .gitgov (initialized project), then .git (for init).
+ *
+ * @param startPath - Starting path (default: process.cwd())
+ * @returns Path to project root, or null if not found
+ */
+declare function findGitgovRoot(startPath?: string): string | null;
+/**
+ * Gets the .gitgov directory path from project root.
+ *
+ * @throws Error if not inside a GitGovernance project
+ */
+declare function getGitgovPath(): string;
+/**
+ * Checks if current directory is inside a GitGovernance project.
+ */
+declare function isGitgovProject(): boolean;
+/**
+ * Reset the project root cache.
+ * Useful for testing when switching between project contexts.
+ */
+declare function resetDiscoveryCache(): void;
+
+/**
+ * FsSyncStateModule - Manages state synchronization between local environment and gitgov-state branch
+ *
+ * Responsibilities:
+ * - Create and maintain the gitgov-state branch (local and remote)
+ * - Publish local changes (pushState)
+ * - Pull remote changes (pullState)
+ * - Resolve conflicts in a governed manner (resolveConflict)
+ * - Audit state integrity (auditState)
+ *
+ * Philosophy:
+ * - Pipeline Pattern: Sequential operations with validation at each phase
+ * - Fail-Fast: Early verifications to avoid costly operations
+ * - Strict Dependencies: All dependencies (git, config, identity, lint, indexer) are required for robust operations
+ */
+declare class FsSyncStateModule implements ISyncStateModule {
+    private git;
+    private config;
+    private identity;
+    private lint;
+    private indexer;
+    /**
+     * Constructor with dependency injection
+     */
+    constructor(dependencies: SyncStateModuleDependencies);
+    /**
+     * Static method to bootstrap .gitgov/ from gitgov-state branch.
+     * Used when cloning a repo that has gitgov-state but .gitgov/ is not in the work branch.
+     *
+     * This method only requires GitModule and can be called before full SyncStateModule initialization.
+     *
+     * @param gitModule - GitModule instance for git operations
+     * @param stateBranch - Name of the state branch (default: "gitgov-state")
+     * @returns Promise<{ success: boolean; error?: string }>
+     */
+    static bootstrapFromStateBranch(gitModule: IGitModule, stateBranch?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Gets the state branch name from configuration.
+     * Default: "gitgov-state"
+     *
+     * [EARS-A4]
+     */
+    getStateBranchName(): Promise<string>;
+    /**
+     * Ensures that the gitgov-state branch exists both locally and remotely.
+     * If it doesn't exist, creates it as an orphan branch.
+     *
+     * Use cases (4 edge cases):
+     * 1. Doesn't exist locally or remotely → Create orphan branch + initial commit + push
+     * 2. Exists remotely, not locally → Fetch + create local + set tracking
+     * 3. Exists locally, not remotely → Push + set tracking
+     * 4. Exists both → Verify tracking
+     *
+     * [EARS-A1, EARS-A2, EARS-A3]
+     */
+    ensureStateBranch(): Promise<void>;
+    /**
+     * Creates the gitgov-state orphan branch with an empty initial commit.
+     * Used by ensureStateBranch when the branch doesn't exist locally or remotely.
+     *
+     * [EARS-A1]
+     */
+    private createOrphanStateBranch;
+    /**
+     * Calculates the file delta in .gitgov/ between the current branch and gitgov-state.
+     *
+     * [EARS-A5]
+     */
+    calculateStateDelta(sourceBranch: string): Promise<StateDeltaFile[]>;
+    /**
+     * [EARS-B23] Detect file-level conflicts and identify remote-only changes.
+     *
+     * A conflict exists when:
+     * 1. A file was modified by the remote during implicit pull
+     * 2. AND the LOCAL USER also modified that same file (content in tempDir differs from what was in git before pull)
+     *
+     * This catches conflicts that git rebase can't detect because we copy files AFTER the pull.
+     *
+     * @param tempDir - Directory containing local .gitgov/ files (preserved before checkout)
+     * @param repoRoot - Repository root path
+    /**
+     * Checks if a rebase is in progress.
+     *
+     * [EARS-D6]
+     */
+    isRebaseInProgress(): Promise<boolean>;
+    /**
+     * Checks for absence of conflict markers in specified files.
+     * Returns list of files that still have markers.
+     *
+     * [EARS-D7]
+     */
+    checkConflictMarkers(filePaths: string[]): Promise<string[]>;
+    /**
+     * Gets the diff of conflicted files for manual analysis.
+     * Useful so the actor can analyze conflicted changes before resolving.
+     *
+     * [EARS-E8]
+     */
+    getConflictDiff(filePaths?: string[]): Promise<ConflictDiff>;
+    /**
+     * Verifies integrity of previous resolutions in gitgov-state history.
+     * Returns list of violations if any exist.
+     *
+     * [EARS-E1, EARS-E2, EARS-E3]
+     */
+    verifyResolutionIntegrity(): Promise<IntegrityViolation[]>;
+    /**
+     * Complete audit of gitgov-state status.
+     * Verifies integrity of resolutions, signatures in Records, checksums and expected files.
+     *
+     * [EARS-E4, EARS-E5, EARS-E6, EARS-E7]
+     */
+    auditState(options?: AuditStateOptions): Promise<AuditStateReport>;
+    /**
+     * Publishes local state changes to gitgov-state.
+     * Implements 3 phases: verification, reconciliation, publication.
+     *
+     * [EARS-B1 through EARS-B7]
+     */
+    pushState(options: SyncStatePushOptions): Promise<SyncStatePushResult>;
+    /**
+     * Pulls remote changes from gitgov-state to the local environment.
+     * Includes automatic re-indexing if there are new changes.
+     *
+     * [EARS-C1 through EARS-C4]
+     * [EARS-C5] Requires remote to be configured (pull without remote makes no sense)
+     */
+    pullState(options?: SyncStatePullOptions): Promise<SyncStatePullResult>;
+    /**
+     * Resolves state conflicts in a governed manner (Git-Native).
+     *
+     * Git-Native Flow:
+     * 1. User resolves conflicts using standard Git tools (edit files, remove markers)
+     * 2. User stages resolved files: git add .gitgov/
+     * 3. User runs: gitgov sync resolve --reason "reason"
+     *
+     * This method:
+     * - Verifies that a rebase is in progress
+     * - Checks that no conflict markers remain in staged files
+     * - Updates resolved Records with new checksums and signatures
+     * - Continues the git rebase (git rebase --continue)
+     * - Creates a signed resolution commit
+     * - Regenerates the index
+     *
+     * [EARS-D1 through EARS-D7]
+     */
+    resolveConflict(options: SyncStateResolveOptions): Promise<SyncStateResolveResult>;
+}
+
+interface WatcherStateModuleOptions {
+    gitgovPath: string;
+    debounceMs?: number;
+}
+interface WatcherStateModuleDependencies {
+    eventBus: IEventStream;
+    options: WatcherStateModuleOptions;
+}
+interface WatcherStateStatus {
+    isRunning: boolean;
+    watchedDirectories: string[];
+    eventsEmitted: number;
+    lastError: Error | undefined;
+}
+
+/**
+ * IWatcherStateModule - State Watcher Interface
+ *
+ * Defines the contract for watching .gitgov/ changes and emitting events.
+ * Unidirectional: read-only observation, never writes back.
+ *
+ * Implementations:
+ * - FsWatcherStateModule: Uses chokidar fs watcher (watcher_state/fs/)
+ * - Future: CloudWatcherStateModule via realtime subscription
+ *
+ * @module watcher_state
+ */
+
+interface IWatcherStateModule {
+    /** Start watching .gitgov/ directories for changes */
+    start(): Promise<void>;
+    /** Stop watching and release all resources */
+    stop(): Promise<void>;
+    /** Whether the watcher is currently active */
+    isRunning(): boolean;
+    /** Current status snapshot */
+    getStatus(): WatcherStateStatus;
+}
+
+/**
+ * FsWatcherStateModule — Filesystem watcher for .gitgov/ changes
+ *
+ * Watches .gitgov/ subdirectories using chokidar and emits events
+ * to the EventBus after debounce + checksum validation.
+ */
+
+declare class FsWatcherStateModule implements IWatcherStateModule {
+    private eventBus;
+    private gitgovPath;
+    private debounceMs;
+    private logger;
+    private watchers;
+    private watchedDirectories;
+    private running;
+    private debounceTimers;
+    private checksums;
+    private eventsEmitted;
+    private lastError?;
+    constructor(deps: WatcherStateModuleDependencies);
+    /**
+     * EARS-1: Creates watchers for existing directories in .gitgov/
+     * EARS-2: Throws ProjectNotInitializedError if .gitgov/ doesn't exist
+     */
+    start(): Promise<void>;
+    /** EARS-5: Closes watchers + cancels timers */
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    getStatus(): WatcherStateStatus;
+    /**
+     * EARS-3: Emits event after debounce
+     * EARS-6: Debounce — N rapid changes → 1 event
+     */
+    private onFileChange;
+    /**
+     * EARS-3: Emit event to EventBus
+     * EARS-4: Skip event on checksum mismatch
+     * EARS-7: Handle errors gracefully
+     */
+    private processFileChange;
+    private emitEvent;
+    private extractRecordType;
+    private extractRecordId;
+}
+
+/**
+ * Filesystem-based Agent Runner - Executes agents based on their engine.type.
+ *
+ * Responsibilities:
+ * - Load AgentRecords from .gitgov/agents/
+ * - Execute via appropriate backend (local, api, mcp, custom)
+ * - Capture responses and write ExecutionRecords
+ * - Emit events via EventBus
+ */
+declare class FsAgentRunner implements IAgentRunner {
+    private gitgovPath;
+    private projectRoot;
+    private identityAdapter;
+    private executionAdapter;
+    private eventBus;
+    /** Protocol handlers for CustomBackend */
+    readonly protocolHandlers: ProtocolHandlerRegistry | undefined;
+    private runtimeHandlers;
+    private localBackend;
+    private apiBackend;
+    private mcpBackend;
+    private customBackend;
+    constructor(deps: AgentRunnerDependencies);
+    /**
+     * Executes an agent once and returns the response.
+     * TaskRecord must exist before calling this method.
+     */
+    runOnce(opts: RunOptions): Promise<AgentResponse>;
+    /**
+     * [EARS-A1, A2] Loads AgentRecord from .gitgov/agents/agent-{id}.json
+     */
+    private loadAgent;
+    /**
+     * [EARS-I4] Emits event via EventBus if available.
+     * Works silently without EventBus.
+     */
+    private emitEvent;
+}
+
+/**
+ * Filesystem AgentRunner implementation
+ *
+ * This module provides the filesystem-based implementation of IAgentRunner:
+ * - FsAgentRunner: Loads AgentRecords from .gitgov/agents/
+ * - createAgentRunner(): Factory function for DI
+ *
+ * Note: LocalBackend is re-exported from backends/ for convenience.
+ * Use @gitgov/core for direct backend imports.
+ */
+
+/**
+ * Factory function to create a filesystem-based AgentRunner.
+ */
+declare function createAgentRunner(deps: AgentRunnerDependencies): IAgentRunner;
+
+export { DEFAULT_ID_ENCODER, type FileSystem, FsAgentRunner, AgentRunnerDependencies as FsAgentRunnerDependencies, FsConfigStore, type FsFixOptions, FsLintModule, type FsLintModuleDependencies, type FsLintOptions, FsProjectInitializer, FsRecordStore, FsSessionStore, FsSyncStateModule, FsWatcherStateModule, LocalGitModule as GitModule, GitModuleDependencies, type IFsLintModule, IGitModule, LocalGitModule, createAgentRunner, createConfigManager, createSessionManager, findGitgovRoot, findProjectRoot, getGitgovPath, isGitgovProject, resetDiscoveryCache };