RepoGuardian Phase 3: File and agent activity monitoring

[JustAGhosT]

Problem

Claude Code, IDE extensions, MCP servers, and other development tools write files to unexpected locations (%TEMP%, %APPDATA%, .claude/, extension-output-* folders). There is no visibility into what files are created, modified, or deleted during agent operations, leading to:

• Orphaned artifacts: temp files, debug outputs, and intermediate files that accumulate over time
• Accidental secret exposure: API keys, tokens, or connection strings written to untracked locations
• Temp file pollution: disk space consumed by forgotten agent outputs
• No audit trail: impossible to determine which tool/agent produced which file changes

Architecture

Extends the existing RepoGuardian team from Phase 2 with 2 additional agents (total: 8):

Agent	Type	Phase	Role
(6 from Phase 1+2)	...	P1+P2	Dependency + tree analysis
FileChangeTracker	Analyst	P3	Monitors file system changes, detects writes outside project tree, identifies patterns
AgentAuditReporter	Writer	P3	Summarizes agent activity, flags anomalies, recommends cleanup actions

Key capabilities

1. File system diff — take snapshots before/after agent operations, report all created/modified/deleted files
2. Out-of-tree detection — flag writes to %TEMP%, %APPDATA%, .claude/, and other non-project paths
3. Secret detection — scan new/modified files for patterns matching API keys, tokens, connection strings (regex-based)
4. Artifact cleanup recommendations — identify temp files safe to remove, with estimated disk savings
5. Agent activity audit — correlate file changes with agent team executions, track which team produced which artifacts

New infrastructure (FoundationLayer)

src/FoundationLayer/FileMonitoring/
    Ports/IFileMonitorPort.cs             — TakeSnapshotAsync, DiffSnapshotsAsync, ScanForSecretsAsync
    Adapters/FileSystemMonitorAdapter.cs  — FileSystemWatcher + snapshot comparison
    Models/FileMonitorModels.cs           — FileSnapshot, FileDiff, SecretFinding, CleanupRecommendation
    Infrastructure/ServiceCollectionExtensions.cs

IFileMonitorPort interface

public interface IFileMonitorPort
{
    Task<FileSnapshot> TakeSnapshotAsync(string rootPath, SnapshotOptions? options = null, CancellationToken ct = default);
    Task<FileDiffReport> DiffSnapshotsAsync(FileSnapshot before, FileSnapshot after, CancellationToken ct = default);
    Task<IReadOnlyList<SecretFinding>> ScanForSecretsAsync(string rootPath, CancellationToken ct = default);
    Task<IReadOnlyList<CleanupRecommendation>> IdentifyCleanupTargetsAsync(string rootPath, CancellationToken ct = default);
}

Secret detection patterns

- `ghp_[a-zA-Z0-9]{36}` (GitHub PAT)
- `sk-[a-zA-Z0-9]{48}` (OpenAI API key)
- `AKIA[A-Z0-9]{16}` (AWS access key)
- `(?i)password\s*[:=]\s*\S+` (inline passwords)
- `(?i)connection\s*string\s*[:=].*` (connection strings)
- `-----BEGIN (RSA |EC )?PRIVATE KEY-----` (private keys)

Integration points

Existing component	How it is used
FileSystemWatcher (.NET built-in)	Real-time file change monitoring
AuditLogging (src/FoundationLayer/AuditLogging/)	Persist file change audit trail
INotificationAdapter (src/FoundationLayer/Notifications/)	Alert on secret detection or anomalous writes
IRepoGuardianPort (src/AgencyLayer/RepoGuardian/Ports/)	Extends existing RepoGuardian team

Extended port

public interface IRepoGuardianPort : IAgentTeamPort
{
    // From Phase 1
    Task<DependencyHealthReport> AnalyzeDependenciesAsync(string solutionRoot, CancellationToken ct = default);

    // From Phase 2
    Task<MonorepoHealthReport> GenerateFullHealthReportAsync(string solutionRoot, CancellationToken ct = default);

    // New in Phase 3
    Task<FileActivityReport> AuditFileActivityAsync(FileSnapshot before, FileSnapshot after, CancellationToken ct = default);
    Task<IReadOnlyList<SecretFinding>> ScanSecretsAsync(string rootPath, CancellationToken ct = default);
}

Acceptance criteria

• IFileMonitorPort defined with snapshot/diff/scan operations
• FileSystemMonitorAdapter uses FileSystemWatcher for real-time monitoring
• Detects file writes outside project root directory
• Regex-based secret pattern scanning with configurable patterns
• Integrates with AuditLogging for persistence of file change events
• Notification sent via INotificationAdapter on secret detection or anomalous writes
• FileChangeTracker agent analyzes diffs and identifies patterns
• AgentAuditReporter agent produces human-readable summaries with cleanup recommendations
• RepoGuardianEngine.DefineAgents() returns 8 agents (6 from Phase 1+2 + 2 new)
• Unit tests with temp directory fixtures
• XML doc comments on all public types (CS1591 compliance)
• dotnet build — 0 warnings, 0 errors

Dependencies

• Requires Phase 2 (RepoGuardian tree maintenance) to be complete
• Uses AuditLogging infrastructure from FoundationLayer
• Uses INotificationAdapter for alerting

Estimated effort

4-6 days

[JustAGhosT]

Dependencies: Requires #336 (RepoGuardian Phase 2) to be complete. Uses AuditLogging from FoundationLayer and INotificationAdapter for alerting.