File-Centric Change Sentinel Specification

Purpose

Create a proactive workstation application that tracks which current working directory is changing which files, why those files are changing, and whether the work is starting to create merge or coordination risk.

The application is intentionally file-centric. Git branches, worktrees, pull requests, and commits are metadata around the file change. They are not the primary human view.

Human Intent

A human should be able to answer these questions quickly:

• What CWD is changing files right now?
• Which files changed, and why?
• Which branch, PR, or intent owns each changed file?
• Is another local CWD, GitHub branch, or open PR changing the same file?
• Is a merge conflict starting before Git reports it at merge time?
• Is this change safe to continue, or should the human pause and review?

Product Name

Working name: Change Sentinel.

This is distinct from a branch visualizer. The product watches file changes, maps them to intent, and raises coordination alarms.

Core Principle

A branch is a transport mechanism. A file change intent is the human artifact.

The application should store and display:

• CWD
• repo
• file
• change status
• owning intent
• actor
• branch
• GitHub branch
• PR
• conflict risk
• deployment relevance

Scope

In Scope

• Watch one or more local repo CWDs.
• Discover Git worktrees, but treat each worktree as a CWD rather than as the primary product model.
• Detect changed files after each filesystem or Git status change.
• Track each changed file back to CWD, branch, actor, and intent.
• Compare local changed files against:
  • other local CWDs for the same repo,
  • GitHub/development,
  • GitHub/master or GitHub/main,
  • open PR head branches.
• Raise alarms when overlap or likely merge risk appears.
• Show a file-centric dashboard.
• Provide an agent-readable status endpoint or file.
• Preserve an audit trail of why a warning was raised.
• Optionally publish coordination issues to GitHub for cross-workstation awareness.

Out of Scope for MVP

• Replacing Git, GitHub, or PRs.
• Blocking file writes.
• Full semantic merge automation.
• Cloud service coordination across many users.
• Global policy enforcement.

Vocabulary

Architecture

Local Responsibilities

Change Sentinel Local runs as the signed-in workstation user. It should use the same Git and GitHub credentials the user already has.

Responsibilities:

• Discover local Git repositories and worktrees.
• Determine repo identity, CWD, branch, remote alignment, and changed files.
• Associate active work with issue, branch, PR, actor, and intent where available.
• Poll or watch filesystem and Git state.
• Analyze changed C# and Razor files with Roslyn where practical.
• Detect overlap across local CWDs.
• Poll GitHub PRs and branches for same-file and stale-branch risk.
• Surface warnings locally to the human and to agent-capable tools.
• Optionally create or update GitHub coordination issues using the local user's authorization.

MVP

Views

CWD View

Shows each monitored CWD:

CWD: C:\Users\Richard\source\repos\PhxBiz\ArticleMngrSLN
Repo: codeputer/ArticleMngrSLN
Branch: local/development
GitHub alignment: local/development == GitHub/development
Changed files: none
Alarms: none

File View

Shows all changed files grouped by file path, not branch:

File: deploy-temp/deploy-contenttraker-environment.ps1
Changed by:
  - CWD: C:\Users\Richard\source\repos\PhxBiz\ArticleMngrSLN
    Branch: codex/deploy-consistency-contract
    Intent: Enforce consistent Azure deployment
    PR: #160
Risk:
  - No local overlap
  - No open PR overlap
  - Production-relevant file

Alarm View

Shows actionable warnings:

Severity: blocker
File: ArticleMngrUserWeb/Components/Pages/SearchDiagnostics.razor
Reason: Two active branches changed overlapping hunks.
Actors:
  - CWD: ArticleMngrSLN
    Branch: local/development
    Intent: file_search diagnostics
  - GitHub branch: codex/use-vector-store-file-search
    PR: #158
Recommendation: Close stale PR or rebase before continuing.

Detection Model

Level 1: Dirty File

Signal:

• git status --porcelain reports a changed file.
• filesystem watcher reports a write and Git status confirms it.

Alarm:

• none by default.

Use:

• Updates CWD and file views.

Level 2: Local Same-File Overlap

Signal:

• Two monitored CWDs for the same repo have changes to the same repo-relative file.

Alarm:

• warning.

Use:

• Human should check whether the workstreams are actually independent.

Level 3: GitHub Branch Same-File Overlap

Signal:

• A local changed file is also changed by an open PR branch.
• A local changed file differs between GitHub/development and GitHub/master.

Alarm:

• warning for same file.
• blocker if the open PR is stale, conflicting, or targets the same base branch.

Level 4: Diff Hunk Overlap

Signal:

• Local diff hunks overlap or are adjacent to hunks in another CWD, branch, or PR.

Alarm:

• warning or blocker depending on proximity and file type.

Level 5: Semantic Boundary Overlap

Signal:

• C# changes touch the same class, method, property, or constructor.
• Razor changes touch the same component section, handler, parameter, or injected service.
• JSON/config changes touch the same key path.

Alarm:

• blocker when two active intents touch the same semantic boundary.

Conflict Risk Rules

The application should evaluate after each confirmed change.

Data Model

Repository

{
  "repoId": "codeputer/ArticleMngrSLN",
  "rootPath": "C:/Users/Richard/source/repos/PhxBiz/ArticleMngrSLN",
  "rootBranchName": "master",
  "developmentBranchName": "development",
  "remoteName": "origin"
}

CWD Snapshot

{
  "cwdId": "articlemngr-main",
  "repoId": "codeputer/ArticleMngrSLN",
  "path": "C:/Users/Richard/source/repos/PhxBiz/ArticleMngrSLN",
  "branch": "development",
  "headCommit": "f86426e50d684f32ed5be37d182428a8c393ec1f",
  "githubDevelopmentCommit": "f86426e50d684f32ed5be37d182428a8c393ec1f",
  "githubRootCommit": "757634b...",
  "isClean": true,
  "capturedUtc": "2026-06-02T12:30:00Z"
}

File Change

{
  "repoId": "codeputer/ArticleMngrSLN",
  "cwdId": "articlemngr-main",
  "path": "deploy-temp/deploy-contenttraker-environment.ps1",
  "status": "modified",
  "intentId": "intent-deploy-consistency",
  "actor": {
    "type": "agent",
    "name": "codex"
  },
  "branch": "codex/deploy-consistency-contract",
  "baseBranch": "development",
  "prNumber": 160,
  "firstSeenUtc": "2026-06-02T12:10:00Z",
  "lastSeenUtc": "2026-06-02T12:20:00Z"
}

Alarm

{
  "alarmId": "alarm-20260602-searchdiagnostics-pr158",
  "severity": "blocker",
  "repoId": "codeputer/ArticleMngrSLN",
  "file": "ArticleMngrUserWeb/Components/Pages/SearchDiagnostics.razor",
  "reason": "Open PR branch changes the same file and is stale against GitHub/development.",
  "evidence": [
    "PR #158 mergeable=CONFLICTING",
    "GitHub/development contains PR #159 and PR #160",
    "Diff from GitHub/development to PR #158 would delete current diagnostics changes"
  ],
  "recommendation": "Close PR #158 and delete its branch.",
  "status": "active",
  "createdUtc": "2026-06-02T12:25:00Z"
}

Event Sources

Required

• git status --porcelain=v1
• git diff --name-status
• git diff --unified=0
• git branch --show-current
• git rev-parse HEAD
• git symbolic-ref --short refs/remotes/origin/HEAD
• git worktree list --porcelain
• GitHub CLI or GitHub API for PR file lists and mergeability.

Optional

• filesystem watcher for faster detection.
• Roslyn for C# semantic boundaries.
• Razor parser for component boundaries.
• JSON parser for appsettings and configuration files.
• local agent session metadata.

Proactive Check Loop

Agent Integration

Agents should be able to query a local status artifact before editing:

.change-sentinel/status.json

Minimum agent-readable fields:

• current CWD identity,
• clean/dirty state,
• changed files,
• active alarms,
• files that should not be touched without human approval,
• current branch and GitHub alignment.

Agents should also write intent metadata when beginning work:

.change-sentinel/intents/{timestamp}-{slug}.json

Example:

{
  "intentId": "intent-deploy-consistency",
  "actor": {
    "type": "agent",
    "name": "codex"
  },
  "humanRequest": "tighten deployment consistency",
  "cwd": "C:/Users/Richard/source/repos/PhxBiz/ArticleMngrSLN",
  "expectedFiles": [
    "deploy-temp/deploy-contenttraker-environment.ps1",
    "_Documentation/ContentTraker-Deployment-Consistency-Contract.md"
  ],
  "startedUtc": "2026-06-02T12:10:00Z"
}

MVP

Implementation Plan

1. Build a CLI scanner that emits .change-sentinel/status.json.
2. Track all Git CWDs under C:/Users/Richard/source/repos.
3. Add GitHub PR file-list comparison.
4. Add same-file and stale-branch alarms.
5. Add diff-hunk overlap alarms.
6. Add a small local dashboard.
7. Add agent preflight conventions.
8. Add Roslyn/Razor semantic alarms after the file and hunk model is stable.

Optional GitHub Coordination

GitHub Issues can be used as a v1 cross-workstation coordination ledger when more than one workstation or actor is working in the same repository.

The application should not send raw high-frequency telemetry to GitHub. GitHub Issues should contain meaningful coordination events:

• active workstream registration,
• overlap warning,
• overlap conflict,
• blocker requiring review,
• acknowledgement,
• resolution.

Labels

Each participating repository may define these labels:

Workstream Issue Shape

Title:

[Change Sentinel] Active workstream: codex/deploy-consistency-contract

Labels:

sentinel:workstream

Body:

repo: codeputer/ArticleMngrSLN
cwd: C:/Users/Richard/source/repos/PhxBiz/ArticleMngrSLN
branch: codex/deploy-consistency-contract
actor:
  type: agent
  name: codex
intent:
  source: human-request
  title: tighten deployment consistency
status: active
heartbeatUtc: 2026-06-02T12:00:00Z
changedFiles:
  - deploy-temp/deploy-contenttraker-environment.ps1
  - _Documentation/ContentTraker-Deployment-Consistency-Contract.md

Overlap Issue Shape

Title:

[Change Sentinel] Overlap detected: SearchDiagnostics.razor

Labels:

sentinel:overlap-conflict
sentinel:blocker

Body:

repo: codeputer/ArticleMngrSLN
file: ArticleMngrUserWeb/Components/Pages/SearchDiagnostics.razor
severity: blocker
reason: Open PR branch changes the same file and is stale against GitHub/development.
workstreams:
  - branch: codex/use-vector-store-file-search
    pr: 158
    status: stale
  - branch: development
    pr: 159
    status: merged
recommendation: Close PR #158 and delete the stale branch.

Runtime Model

V1 should be a workstation-local service. On Windows, this can be installed as a Windows service or started as a user-level background process.

The service should run as the signed-in user. This preserves the existing Git and GitHub authorization model. If the user cannot create an issue in a repository, Change Sentinel should not be able to create one either.

Implementation Phases

Phase 1: File-Level Local Sentinel

• Discover Git CWDs and worktrees.
• Poll git status, git diff --name-status, and branch metadata.
• Store local CWD and file-change state.
• Detect same-file overlap across local CWDs.
• Show local warnings.

Phase 2: GitHub PR and Branch Risk

• Read open PR file lists and mergeability.
• Compare local changed files with open PRs.
• Detect stale PR branches that conflict with GitHub/development.
• Detect branches with no open PR and no clear active intent.

Phase 3: Optional GitHub Issue Coordination

• Configure labels.
• Create/update active workstream issues.
• Create/update overlap issues.
• Throttle updates to avoid issue noise.

Phase 4: Semantic Detection

• Parse changed .cs and .razor files.
• Identify touched classes, methods, properties, and components.
• Upgrade overlap severity when the same symbol is touched.

Phase 5: Agent and IDE Integration

• Expose a local endpoint for agents to check before editing.
• Add desktop or tray notifications.
• Add Visual Studio or VS Code status surfaces if useful.

MVP

Acceptance Criteria

• Shows every monitored CWD and branch.
• Shows changed files grouped by file path.
• Identifies whether local/development matches GitHub/development.
• Identifies whether local/master matches GitHub/master.
• Detects local file overlap across CWDs.
• Detects overlap with open PR file lists.
• Detects stale PR branches that would remove or overwrite current GitHub/development changes.
• Emits an alarm before a production deploy from a dirty or non-root source.
• Writes machine-readable status for AI agents.
• Can optionally publish meaningful coordination issues without broad GitHub credentials.

First ContentTraker Scenario

The scenario that just occurred should be a test case:

1. Feature work starts on codex/use-vector-store-file-search.
2. Later work is merged through PR #159 and PR #160.
3. PR #158 remains open and becomes stale/conflicting.
4. Change Sentinel detects that PR #158 is no longer the path forward because its diff conflicts with GitHub/development.
5. Alarm recommends closing PR #158 and deleting the branch.

Expected result:

Severity: blocker
Reason: Open PR branch is stale and conflicting with GitHub/development.
Recommendation: Close PR #158 and delete codex/use-vector-store-file-search.