Skip to content

Implement GitWorkspaceState classifier and Git probe severity discipline#41

Draft
Copilot wants to merge 2 commits intomainfrom
copilot/implement-git-workspace-state-classifier
Draft

Implement GitWorkspaceState classifier and Git probe severity discipline#41
Copilot wants to merge 2 commits intomainfrom
copilot/implement-git-workspace-state-classifier

Conversation

Copy link
Copy Markdown

Copilot AI commented May 6, 2026

Terminal/workspace watchers were probing non-repo directories, .git dirs, detached/bare/corrupt repos, and superseded watcher states without typed classification, producing warning spam for expected negative conditions.

New module: src/agent_term/git_workspace.py

  • GitWorkspaceState enum — ten typed states: not_a_repo, repo_root, inside_worktree, inside_git_dir, bare_repo, worktree_no_remote, detached_head, corrupt_repo, permission_denied, operation_superseded
  • severity_for_state() — severity-discipline table; expected negative states (not_a_repo, inside_git_dir, bare_repo, worktree_no_remote, detached_head) are info by default; operation_superseded is debug; corrupt_repo/permission_denied are warning; severity escalates to warning only when the caller signals the pending op actually requires the missing capability
  • classify_git_workspace(path, *, force=False) — runs git rev-parse sub-commands, detects .git dir probing before any branch commands, catches PermissionError from both os.listdir and git stderr, detects corrupt repos from stderr keywords; results cached by resolved absolute path (force=True bypasses cache)
  • GitWorkspaceClassification dataclass — carries state, path, branch, remote_status, severity, action_hint; to_status_line() renders the compact terminal UX format; to_metadata() emits adapter-ready dict
clf = classify_git_workspace("/some/dir")
print(clf.to_status_line())
# Workspace: /some/dir
# Git state: worktree_no_remote
# Remote: missing
# Branch: main
# Severity: info
# Action: Run `git remote add origin <url>` to add a remote.

# Severity escalates only when the op actually needs the missing capability
severity_for_state(GitWorkspaceState.WORKTREE_NO_REMOTE, operation_requires_remote=True)
# → "warning"

Tests: tests/test_git_workspace.py

27 tests covering every state, cache/debounce behaviour, severity-discipline invariants, status-line format, and metadata shape. All git I/O faked via unittest.mock.patch on _run_git.

Copilot AI changed the title [WIP] Implement GitWorkspaceState classifier and Git probe severity discipline Implement GitWorkspaceState classifier and Git probe severity discipline May 6, 2026
Copilot AI requested a review from mdheller May 6, 2026 18:31
Copy link
Copy Markdown
Contributor

mdheller commented May 6, 2026

Review: good classifier foundation, but not contract-complete yet

This PR has a strong start: typed state enum, severity discipline, caching/debounce, status-line output, and broad tests. CI is also reported successful on the PR head.

However, before this should be marked ready/merged, it needs to align directly with the merged upstream contract from SourceOS-Linux/sourceos-spec PR #101.

Required remediation:

  1. Add a GitWorkspaceState receipt/emission shape that matches upstream schemas/GitWorkspaceState.json exactly enough for downstream validation.
  2. Add or copy a canonical fixture equivalent to upstream examples/gitworkspacestate.json.
  3. Add validation against that schema/fixture, or a documented sync path from sourceos-spec.
  4. Align enum spellings with upstream where emitted as receipt data. In particular, upstream uses remoteState = not_applicable, while this module currently exposes not-applicable as a terminal UI constant. UI text can keep hyphenated display text, but emitted receipt metadata should match upstream schema.
  5. Ensure emitted receipt data includes the upstream-required fields: sessionRef, capabilityLedgerRef, workspaceRef, state, severity, operation, actionability, pathEvidence, gitFacts, policyDecisionRef, non-empty evidenceRefs, and capturedAt.

Recommendation: keep the classifier as the implementation core, then add a thin adapter such as to_git_workspace_state_receipt(...) that produces the upstream contract payload without forcing terminal UI internals to become schema-shaped everywhere.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Implement GitWorkspaceState classifier and Git probe severity discipline

2 participants