opencode-swarm 7.0.0-beta.1 → 7.0.1

package/dist/db/project-db.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-project SQLite database for opencode-swarm.
+ *
+ * Owns `.swarm/swarm.db` in each project directory. Stores per-project
+ * constraints and QA gate profiles. One cached instance per normalized
+ * directory path.
+ */
+import type { Database } from 'bun:sqlite';
+/**
+ * Run all pending migrations on the provided database.
+ * Idempotent: existing migrations are not re-applied.
+ */
+export declare function runProjectMigrations(db: Database): void;
+/**
+ * Return the absolute path to `.swarm/swarm.db` for the given directory.
+ * Does not create the file or any parent directory.
+ */
+export declare function projectDbPath(directory: string): string;
+/**
+ * Return true iff the project DB file already exists on disk. Does not
+ * open the DB, create `.swarm/`, or run migrations. Intended for
+ * read-only callers (e.g. `getProfile`) that must avoid mutating the
+ * workspace just to check for a missing record.
+ */
+export declare function projectDbExists(directory: string): boolean;
+/**
+ * Return the cached project database for the given directory, opening it
+ * if needed. Creates `.swarm/` if absent and enables WAL + foreign keys.
+ */
+export declare function getProjectDb(directory: string): Database;
+/**
+ * Close and remove the cached project database for the given directory.
+ * Test-only.
+ */
+export declare function closeProjectDb(directory: string): void;
+/**
+ * Close and remove all cached project databases.
+ * Test-only.
+ */
+export declare function closeAllProjectDbs(): void;

package/dist/db/project-db.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for src/db/project-db.ts.
+ */
+export {};

package/dist/db/qa-gate-profile.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Service layer for the `qa_gate_profile` table in the per-project database.
+ *
+ * A QA gate profile is keyed by plan_id and captures which QA gates are
+ * enabled for that plan. Profiles are locked after critic approval; once
+ * locked, row updates are rejected by a SQLite trigger and by this service.
+ * Sessions can only ratchet gates tighter (enable more), never disable them.
+ */
+/**
+ * QA gate flags. All ten gates are tracked explicitly.
+ */
+export interface QaGates {
+    reviewer: boolean;
+    test_engineer: boolean;
+    council_mode: boolean;
+    sme_enabled: boolean;
+    critic_pre_plan: boolean;
+    hallucination_guard: boolean;
+    sast_enabled: boolean;
+    mutation_test: boolean;
+    council_general_review: boolean;
+    drift_check: boolean;
+}
+/**
+ * Default QA gate configuration for newly-created profiles.
+ */
+export declare const DEFAULT_QA_GATES: QaGates;
+/**
+ * Row-level representation of a persisted QA gate profile.
+ */
+export interface QaGateProfile {
+    id: number;
+    plan_id: string;
+    created_at: string;
+    project_type: string | null;
+    gates: QaGates;
+    locked_at: string | null;
+    locked_by_snapshot_seq: number | null;
+}
+/**
+ * Fetch the profile for `planId` or return null if none exists.
+ *
+ * Read-only: if `.swarm/swarm.db` does not exist yet, returns null
+ * without creating the DB file or running migrations. This keeps callers
+ * on read-only paths (`get_approved_plan`, `get_qa_gate_profile`, the
+ * `qa-gates show` command) from silently mutating the workspace just by
+ * looking for a profile. Write paths (`getOrCreateProfile`, `setGates`,
+ * `lockProfile`) continue to initialize the DB on demand.
+ */
+export declare function getProfile(directory: string, planId: string): QaGateProfile | null;
+/**
+ * Return the existing profile for `planId`, or create a new one seeded with
+ * `DEFAULT_QA_GATES` if none exists. Tolerates races on the UNIQUE index.
+ */
+export declare function getOrCreateProfile(directory: string, planId: string, projectType?: string): QaGateProfile;
+/**
+ * Update gates for `planId`. Gates can only be ratcheted tighter —
+ * attempting to disable a currently-enabled gate throws. Throws if the
+ * profile is locked.
+ */
+export declare function setGates(directory: string, planId: string, gates: Partial<QaGates>): QaGateProfile;
+/**
+ * Lock the profile for `planId`, recording the snapshot seq that anchors it.
+ * Idempotent: locking an already-locked profile returns it unchanged.
+ */
+export declare function lockProfile(directory: string, planId: string, snapshotSeq: number): QaGateProfile;
+/**
+ * Compute a SHA-256 hex digest over the stable identity of a profile.
+ * Used by `get_approved_plan` for drift detection.
+ */
+export declare function computeProfileHash(profile: QaGateProfile): string;
+/**
+ * Merge session-level gate overrides on top of the spec-level profile.
+ * Session overrides can only ratchet gates tighter (set to true); false
+ * values in overrides are ignored.
+ *
+ * IMPORTANT — caller responsibility: this function is the *computation*
+ * of effective gates, not an enforcement point. Enforcement consumers
+ * must call this at their own check sites, passing the current profile
+ * from `getProfile` and the agent session's `qaGateSessionOverrides ?? {}`.
+ * Reading raw `profile.gates` directly from an enforcement site will
+ * silently ignore operator-applied session overrides.
+ *
+ * Active enforcement consumers (keep this list in sync when wiring new gates):
+ * - reviewer / test_engineer — src/hooks/delegation-gate.ts (Stage B state
+ *   machine; blocks coder→next-coder advancement until reviewer + test_engineer
+ *   delegations observed).
+ * - council_mode — src/state.ts isCouncilGateActive + src/hooks/delegation-gate.ts
+ *   (Stage B replaced by submit_council_verdicts verdict).
+ * - sme_enabled — consumed during MODE: BRAINSTORM/SPECIFY architect dialogue.
+ * - critic_pre_plan — consumed by MODE: PLAN critic delegation before save_plan.
+ * - sast_enabled — consumed inside pre_check_batch tool.
+ * - hallucination_guard — src/tools/phase-complete.ts Gate 3 (blocks phase_complete
+ *   until .swarm/evidence/{phase}/hallucination-guard.json has APPROVED verdict).
+ * - mutation_test — src/tools/phase-complete.ts Gate 4 (blocks phase_complete
+ *   until .swarm/evidence/{phase}/mutation-gate.json has pass verdict; warn does not block)
+ * - council_general_review — src/agents/architect.ts SPECIFY-COUNCIL-REVIEW
+ *   (fires when gate is true; runs convene_general_council on draft spec before
+ *   critic-gate to fold multi-model deliberation into the spec).
+ * - drift_check — src/tools/phase-complete.ts Gate 2 (blocks phase_complete when
+ *   drift-verifier.json missing or rejected)
+ *
+ * Session overrides are intentionally ephemeral — they live only in
+ * in-memory `AgentSessionState.qaGateSessionOverrides` and are NOT
+ * persisted to the session snapshot. Process restart clears them.
+ */
+export declare function getEffectiveGates(profile: QaGateProfile, sessionOverrides: Partial<QaGates>): QaGates;

package/dist/db/qa-gate-profile.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for src/db/qa-gate-profile.ts.
+ */
+export {};

package/dist/diff/__tests__/semantic-classifier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/diff/__tests__/summary-generator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/diff/ast-diff.d.ts

@@ -0,0 +1,21 @@
+export interface ASTChange {
+    type: 'added' | 'modified' | 'removed' | 'renamed';
+    category: 'function' | 'class' | 'type' | 'export' | 'import' | 'variable' | 'other';
+    name: string;
+    lineStart: number;
+    lineEnd: number;
+    signature?: string;
+    renamedFrom?: string;
+}
+export interface ASTDiffResult {
+    filePath: string;
+    language: string | null;
+    changes: ASTChange[];
+    durationMs: number;
+    usedAST: boolean;
+    error?: string;
+}
+/**
+ * Compute AST-level diff between old and new file content
+ */
+export declare function computeASTDiff(filePath: string, oldContent: string, newContent: string): Promise<ASTDiffResult>;

package/dist/diff/semantic-classifier.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Semantic classifier for AST changes.
+ * Classifies AST changes into semantic categories with risk ranking.
+ * @module diff/semantic-classifier
+ */
+import type { ASTDiffResult } from '../diff/ast-diff.js';
+/**
+ * Semantic categories for classified changes.
+ * Describes the nature of the change from a code impact perspective.
+ */
+export type ChangeCategory = 'SIGNATURE_CHANGE' | 'API_CHANGE' | 'GUARD_REMOVED' | 'LOGIC_CHANGE' | 'DELETED_FUNCTION' | 'NEW_FUNCTION' | 'REFACTOR' | 'COSMETIC' | 'UNCLASSIFIED';
+/**
+ * Risk level associated with a classified change.
+ * Indicates the potential impact severity of the change.
+ */
+export type RiskLevel = 'Critical' | 'High' | 'Medium' | 'Low';
+/**
+ * A classified AST change with semantic categorization and risk assessment.
+ */
+export interface ClassifiedChange {
+    /** Semantic category of the change */
+    category: ChangeCategory;
+    /** Risk level indicating potential impact severity */
+    riskLevel: RiskLevel;
+    /** Path to the file containing this change */
+    filePath: string;
+    /** Name of the symbol (function, class, etc.) affected */
+    symbolName: string;
+    /** Type of change operation */
+    changeType: 'added' | 'modified' | 'removed' | 'renamed';
+    /** Starting line number of the change */
+    lineStart: number;
+    /** Ending line number of the change */
+    lineEnd: number;
+    /** Human-readable description of what was detected */
+    description: string;
+    /** Original AST change signature detail (if available) */
+    signature?: string;
+    /** Original name before rename, if this is a renamed symbol */
+    renamedFrom?: string;
+    /** Number of files that depend on this file (blast radius indicator) */
+    consumersCount?: number;
+}
+/**
+ * Classify an array of AST diff results into semantic categories with risk levels.
+ *
+ * @param astDiffs - Array of ASTDiffResult from the AST differ
+ * @returns Array of ClassifiedChange with semantic categorization
+ *
+ * @example
+ * ```typescript
+ * const diffs = await astDiff(oldCode, newCode);
+ * const classified = classifyChanges(diffs);
+ * for (const change of classified) {
+ *   console.log(`[${change.riskLevel}] ${change.category}: ${change.symbolName}`);
+ * }
+ * ```
+ */
+export declare function classifyChanges(astDiffs: ASTDiffResult[], fileConsumers?: Record<string, number>): ClassifiedChange[];

package/dist/diff/summary-generator.d.ts

@@ -0,0 +1,33 @@
+import type { ChangeCategory, ClassifiedChange, RiskLevel } from './semantic-classifier.js';
+/**
+ * Structured summary of classified semantic diff changes.
+ * Provides multiple views for different review workflows.
+ */
+export interface SemanticDiffSummary {
+    /** Number of files with changes */
+    totalFiles: number;
+    /** Total number of classified changes */
+    totalChanges: number;
+    /** Changes grouped by risk level */
+    byRisk: Record<RiskLevel, ClassifiedChange[]>;
+    /** Changes grouped by category */
+    byCategory: Record<ChangeCategory, ClassifiedChange[]>;
+    /** Quick access to Critical items for gate checks */
+    criticalItems: ClassifiedChange[];
+}
+/**
+ * Generates a structured summary from classified changes.
+ * Provides by-risk and by-category groupings plus critical item quick access.
+ *
+ * @param changes - Array of classified changes to summarize
+ * @returns SemanticDiffSummary with all grouping views
+ */
+export declare function generateSummary(changes: ClassifiedChange[]): SemanticDiffSummary;
+/**
+ * Generates reviewer-ready markdown summary from a SemanticDiffSummary.
+ * Format groups by risk level with file:category annotations.
+ *
+ * @param summary - The structured summary to render as markdown
+ * @returns Markdown-formatted string ready for PR review
+ */
+export declare function generateSummaryMarkdown(summary: SemanticDiffSummary): string;

package/dist/environment/index.d.ts

@@ -0,0 +1,3 @@
+export type { CommandPolicy, EnvironmentProfile, ExecutionMode, HostOS, OperatingMode, ShellFamily, } from './profile.js';
+export { deriveCommandPolicy, detectEnvironmentProfile } from './profile.js';
+export { renderEnvironmentPrompt } from './prompt-renderer.js';

package/dist/environment/profile.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Session-level execution environment profiling for opencode-swarm.
+ * Computed once per session; never re-detected within a session.
+ */
+export type HostOS = 'windows' | 'linux' | 'macos' | 'unknown';
+export type ShellFamily = 'powershell' | 'cmd' | 'bash' | 'zsh' | 'sh' | 'unknown';
+export type ExecutionMode = 'native' | 'docker' | 'wsl' | 'unknown';
+export type OperatingMode = 'linux' | 'macos-native' | 'windows-native' | 'unknown';
+export interface EnvironmentProfile {
+    hostOS: HostOS;
+    shellFamily: ShellFamily;
+    executionMode: ExecutionMode;
+    operatingMode: OperatingMode;
+    isWindowsNative: boolean;
+    isWindowsDocker: boolean;
+    isWSL: boolean;
+    pathStyle: 'windows' | 'posix';
+    shellCommandPreference: 'powershell-native' | 'posix-native';
+    evidence: {
+        processPlatform: string;
+        comspec?: string;
+        psModulePath?: string;
+        termProgram?: string;
+        shell?: string;
+        wslDistroName?: string;
+        containerMarkers: string[];
+    };
+}
+export interface CommandPolicy {
+    preferredShell: ShellFamily;
+    avoidPosixExamples: boolean;
+    preferNodeApis: boolean;
+    preferToolingOverShell: boolean;
+    pathExampleStyle: 'windows' | 'posix';
+    examples: {
+        listDir: string;
+        removeFile: string;
+        setEnv: string;
+        printEnv: string;
+        searchText: string;
+    };
+}
+/**
+ * Detect the current execution environment. Call once per session.
+ */
+export declare function detectEnvironmentProfile(): EnvironmentProfile;
+/**
+ * Derive a CommandPolicy from a detected EnvironmentProfile.
+ */
+export declare function deriveCommandPolicy(profile: EnvironmentProfile): CommandPolicy;

package/dist/environment/prompt-renderer.d.ts

@@ -0,0 +1,6 @@
+import type { EnvironmentProfile } from './profile.js';
+/**
+ * Renders a concise runtime environment block for agent prompts.
+ * Audience: 'coder' or 'testengineer'
+ */
+export declare function renderEnvironmentPrompt(profile: EnvironmentProfile, audience: 'coder' | 'testengineer'): string;

package/dist/evidence/index.d.ts

@@ -0,0 +1,2 @@
+export type { LoadEvidenceResult } from './manager';
+export { archiveEvidence, deleteEvidence, listEvidenceTaskIds, loadEvidence, sanitizeTaskId, saveEvidence, } from './manager';

package/dist/evidence/lock.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Evidence write-lock helper (PR 1 — dark foundation).
+ *
+ * Wraps every evidence read-modify-write path with a proper-lockfile-backed
+ * exclusive lock so that concurrent writers cannot interleave their
+ * read-compute-write cycles.  The underlying temp-file-plus-rename atomic
+ * write is preserved; this lock adds a coordinating layer on top.
+ *
+ * Telemetry events emitted:
+ *   evidence_lock_acquired   — lock obtained, fn executing
+ *   evidence_lock_contended  — lock busy, backing off before retry
+ *   evidence_lock_stale_recovered — stale lock detected and recovered by proper-lockfile
+ *   (timeout path emits nothing extra; EvidenceLockTimeoutError is thrown instead)
+ */
+export declare class EvidenceLockTimeoutError extends Error {
+    readonly directory: string;
+    readonly evidencePath: string;
+    readonly agent: string;
+    readonly taskId: string;
+    constructor(directory: string, evidencePath: string, agent: string, taskId: string, timeoutMs: number);
+}
+/**
+ * Acquire an exclusive evidence lock, execute `fn`, then release the lock.
+ *
+ * Retries with exponential backoff until `evidenceLockTimeoutMs` elapses,
+ * then throws `EvidenceLockTimeoutError`.  Always releases the lock in a
+ * `finally` block even if `fn` throws.
+ *
+ * @param directory    Project root directory
+ * @param evidencePath Relative path of the evidence file to lock
+ * @param agent        Acquiring agent name (for diagnostics)
+ * @param taskId       Task identifier (for diagnostics)
+ * @param fn           Callback that performs the read-modify-write
+ * @param timeoutMs    Maximum wait time before EvidenceLockTimeoutError (default 60 000)
+ */
+export declare function withEvidenceLock<T>(directory: string, evidencePath: string, agent: string, taskId: string, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/evidence/manager.d.ts

@@ -0,0 +1,78 @@
+import { type BuildEvidence, type Evidence, type EvidenceBundle, type PlaceholderEvidence, type QualityBudgetEvidence, type SastEvidence, type SbomEvidence, type SecretscanEvidence, type SyntaxEvidence } from '../config/evidence-schema';
+/**
+ * Discriminated union returned by loadEvidence.
+ * - 'found': file exists and passed Zod schema validation
+ * - 'not_found': file does not exist on disk
+ * - 'invalid_schema': file exists but failed Zod validation; errors contains field names
+ */
+export type LoadEvidenceResult = {
+    status: 'found';
+    bundle: EvidenceBundle;
+} | {
+    status: 'not_found';
+} | {
+    status: 'invalid_schema';
+    errors: string[];
+};
+/**
+ * All valid evidence types (13 total)
+ */
+export declare const VALID_EVIDENCE_TYPES: readonly ["review", "test", "diff", "approval", "note", "retrospective", "syntax", "placeholder", "sast", "sbom", "build", "quality_budget", "secretscan"];
+/**
+ * Check if a string is a valid evidence type.
+ * Returns true if the type is recognized, false otherwise.
+ */
+export declare function isValidEvidenceType(type: string): type is (typeof VALID_EVIDENCE_TYPES)[number];
+/**
+ * Type guards for new evidence types
+ */
+export declare function isSyntaxEvidence(evidence: Evidence): evidence is SyntaxEvidence;
+export declare function isPlaceholderEvidence(evidence: Evidence): evidence is PlaceholderEvidence;
+export declare function isSastEvidence(evidence: Evidence): evidence is SastEvidence;
+export declare function isSbomEvidence(evidence: Evidence): evidence is SbomEvidence;
+export declare function isBuildEvidence(evidence: Evidence): evidence is BuildEvidence;
+export declare function isQualityBudgetEvidence(evidence: Evidence): evidence is QualityBudgetEvidence;
+/**
+ * Type guard for secretscan evidence
+ */
+export declare function isSecretscanEvidence(evidence: Evidence): evidence is SecretscanEvidence;
+import { sanitizeTaskId as _sanitizeTaskId } from '../validation/task-id';
+export declare const sanitizeTaskId: typeof _sanitizeTaskId;
+/**
+ * Save evidence to a task's evidence bundle.
+ * Creates new bundle if doesn't exist, appends to existing.
+ * Performs atomic write via temp file + rename.
+ * @throws Error if task ID is invalid or size limit would be exceeded
+ */
+export declare function saveEvidence(directory: string, taskId: string, evidence: Evidence): Promise<EvidenceBundle>;
+/**
+ * Load evidence bundle for a task.
+ * Returns a LoadEvidenceResult discriminated union.
+ */
+export declare function loadEvidence(directory: string, taskId: string): Promise<LoadEvidenceResult>;
+/**
+ * List all task IDs that have evidence bundles.
+ * Returns sorted array of valid task IDs.
+ * Returns empty array if evidence directory doesn't exist.
+ */
+export declare function listEvidenceTaskIds(directory: string): Promise<string[]>;
+/**
+ * Delete evidence bundle for a task.
+ * Returns true if deleted, false if didn't exist or deletion failed.
+ */
+export declare function deleteEvidence(directory: string, taskId: string): Promise<boolean>;
+/**
+ * Check if a requirement coverage file exists for a given phase.
+ * Looks for .swarm/evidence/req-coverage-phase-{N}.json
+ */
+export declare function checkRequirementCoverage(phase: number, directory: string): Promise<{
+    exists: boolean;
+    path: string;
+}>;
+/**
+ * Archive old evidence bundles based on retention policy.
+ * Removes evidence older than maxAgeDays.
+ * If maxBundles is provided, enforces a maximum bundle count by deleting oldest first.
+ * Returns array of archived (deleted) task IDs.
+ */
+export declare function archiveEvidence(directory: string, maxAgeDays: number, maxBundles?: number): Promise<string[]>;

package/dist/gate-evidence.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gate Evidence Store
+ *
+ * Durable, task-scoped evidence for QA gate completion.
+ * Evidence is recorded on disk (.swarm/evidence/{taskId}.json) by the
+ * delegation-gate toolAfter hook and read by checkReviewerGate at
+ * update_task_status(completed) time.
+ *
+ * Evidence files survive session restarts (unlike in-memory state).
+ * Agents never write these files directly — only the hook does.
+ * Gates are append-only: required_gates can only grow, never shrink.
+ */
+export interface GateEvidence {
+    sessionId: string;
+    timestamp: string;
+    agent: string;
+}
+export interface TaskEvidence {
+    taskId: string;
+    required_gates: string[];
+    gates: Record<string, GateEvidence>;
+    turbo?: boolean;
+}
+export declare const DEFAULT_REQUIRED_GATES: string[];
+/**
+ * Canonical task-id validation helper.
+ * Delegates to the shared strict validator (#452 item 2).
+ * Re-exported for backward compatibility with existing callers.
+ */
+export declare function isValidTaskId(taskId: string): boolean;
+/**
+ * Maps the first-dispatched agent type to the initial required_gates array.
+ * Unknown agent types fall back to the safe default ["reviewer", "test_engineer"].
+ */
+export declare function deriveRequiredGates(agentType: string): string[];
+/**
+ * Returns the union of existingGates and deriveRequiredGates(newAgentType).
+ * Sorted, deduplicated. Gates can only grow, never shrink.
+ */
+export declare function expandRequiredGates(existingGates: string[], newAgentType: string): string[];
+/**
+ * Creates or updates .swarm/evidence/{taskId}.json with a gate pass entry.
+ * If file doesn't exist: creates with required_gates from deriveRequiredGates(gate).
+ * If file exists: merges gate entry, expands required_gates via expandRequiredGates.
+ * Atomic write: temp file + rename.
+ */
+export declare function recordGateEvidence(directory: string, taskId: string, gate: string, sessionId: string, turbo?: boolean): Promise<void>;
+/**
+ * Sets or expands required_gates WITHOUT recording a gate pass.
+ * Used when non-gate agents are dispatched (coder, explorer, sme, etc.).
+ * Creates evidence file if it doesn't exist yet.
+ */
+export declare function recordAgentDispatch(directory: string, taskId: string, agentType: string, turbo?: boolean): Promise<void>;
+/**
+ * Returns the TaskEvidence for a task, or null if file missing or parse error.
+ * Never throws.
+ */
+export declare function readTaskEvidence(directory: string, taskId: string): Promise<TaskEvidence | null>;
+/**
+ * Returns the TaskEvidence for a task, or null if the file does not exist (ENOENT).
+ * Throws on malformed JSON, permission errors, or other non-ENOENT issues.
+ * Used by checkReviewerGate for evidence-first gate checking with proper error handling.
+ */
+export declare function readTaskEvidenceRaw(directory: string, taskId: string): TaskEvidence | null;
+/**
+ * Returns true only when every required_gate has a matching gates entry.
+ * Returns false if no evidence file exists.
+ */
+export declare function hasPassedAllGates(directory: string, taskId: string): Promise<boolean>;

package/dist/gate-evidence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/git/branch.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Check if we're in a git repository
+ */
+export declare function isGitRepo(cwd: string): boolean;
+/**
+ * Get current branch name
+ */
+export declare function getCurrentBranch(cwd: string): string;
+/**
+ * Create a new branch
+ * @param cwd - Working directory
+ * @param branchName - Name of the branch to create
+ * @param remote - Remote name (default: 'origin')
+ */
+export declare function createBranch(cwd: string, branchName: string, remote?: string): void;
+/**
+ * Get list of changed files compared to main/master
+ * @param cwd - Working directory
+ * @param branch - Base branch to compare against (optional, auto-detected if not provided)
+ * @returns Array of changed file paths, or empty array if error occurs
+ */
+export declare function getChangedFiles(cwd: string, branch?: string): string[];
+/**
+ * Get default base branch (main or master)
+ */
+export declare function getDefaultBaseBranch(cwd: string): string;
+/**
+ * Stage specific files for commit
+ * @param cwd - Working directory
+ * @param files - Array of file paths to stage (must not be empty)
+ * @throws Error if files array is empty
+ */
+export declare function stageFiles(cwd: string, files: string[]): void;
+/**
+ * Stage all files in the working directory
+ * @param cwd - Working directory
+ */
+export declare function stageAll(cwd: string): void;
+/**
+ * Commit changes
+ */
+export declare function commitChanges(cwd: string, message: string): void;
+/**
+ * Get current commit SHA
+ */
+export declare function getCurrentSha(cwd: string): string;
+/**
+ * Check if there are uncommitted changes
+ */
+export declare function hasUncommittedChanges(cwd: string): boolean;
+export interface ResetToRemoteBranchResult {
+    success: boolean;
+    targetBranch: string;
+    localBranch: string;
+    message: string;
+    alreadyAligned: boolean;
+    prunedBranches: string[];
+    warnings: string[];
+}
+/**
+ * Reset local branch to align with its remote counterpart.
+ * Safely handles uncommitted changes, unpushed commits, and detached HEAD states.
+ *
+ * @param cwd - Working directory
+ * @param options - Options including pruneBranches flag
+ * @returns Result object with success status and details
+ */
+export declare function resetToRemoteBranch(cwd: string, options?: {
+    pruneBranches?: boolean;
+}): ResetToRemoteBranchResult;

package/dist/git/index.d.ts

@@ -0,0 +1,22 @@
+import { createBranch, isGitRepo } from './branch.js';
+import { isAuthenticated, isGhAvailable } from './pr.js';
+export interface PRWorkflowOptions {
+    title: string;
+    body?: string;
+    branch?: string;
+}
+export interface PRWorkflowResult {
+    success: boolean;
+    url?: string;
+    number?: number;
+    error?: string;
+}
+/**
+ * Full PR workflow: create branch → commit → push → create PR
+ */
+export declare function runPRWorkflow(cwd: string, options: PRWorkflowOptions): Promise<PRWorkflowResult>;
+/**
+ * Generate evidence summary without creating PR
+ */
+export declare function prepareEvidence(cwd: string): string;
+export { isGhAvailable, isAuthenticated, isGitRepo, createBranch };

package/dist/git/pr.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sanitize input string to prevent command injection
+ * Removes or escapes shell metacharacters
+ */
+export declare function sanitizeInput(input: string): string;
+/**
+ * Check if gh CLI is available
+ */
+export declare function isGhAvailable(cwd: string): boolean;
+/**
+ * Check if authenticated with gh
+ */
+export declare function isAuthenticated(cwd: string): boolean;
+/**
+ * Create evidence.md summary
+ */
+export declare function generateEvidenceMd(cwd: string): string;
+/**
+ * Create a pull request
+ */
+export declare function createPullRequest(cwd: string, title: string, body?: string, baseBranch?: string): Promise<{
+    url: string;
+    number: number;
+}>;
+/**
+ * Commit and push current changes
+ */
+export declare function commitAndPush(cwd: string, message: string): void;