[EPIC][expert] Git / repository expert: symbolic repository reasoning over typed host-supplied Git capabilities #416

New issue

Open

opened 2026-09-08 01:29:21 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 01:29:21 +00:00

Owner

Parent: #376
Depends on: #377
Integrates with: #379, #380, #141, #355

Goal

Add a reusable Git / Repository Expert that reasons about repository state, history, branches, diffs, worktrees, remotes and safe repository transitions using typed host-supplied Git observations/actions.

The expert belongs in prolog-rlm because the reasoning policy and normalized repository knowledge are reusable. Concrete product Git tool implementations remain downstream/host supplied per #141.

Hard boundary

Do not reintroduce the old #49/#50 architecture by shipping ambient concrete Git commands in core.

The expert reasons over normalized capabilities/results equivalent to:

repo_status
repo_head
repo_branch
repo_diff
repo_show
repo_log
repo_merge_base
repo_worktree_state
repo_remote_state
repo_apply_patch / commit / branch operations when host supplies them

Exact tool names are host/product contracts. The expert contract should operate on normalized repository facts and typed capability metadata, not shell command strings.

D6-11 interaction

sync_remote/1 remains a plan-native deterministic operation per #355 and is not implemented as an expert handler.

The Git Expert may conclude that synchronization is required and return a typed requirement/plan recommendation for sync_remote, after which the plan layer executes it through the canonical capability/authority/effect boundary.

Likewise, deterministic run, index, and delete remain outside this expert.

Responsibilities

establish current repository/worktree/head/branch state from host observations;
reason about clean/dirty/conflicted/diverged/detached/behind/ahead states;
compare expected vs observed head/preimage state;
identify relevant commits/diffs/history for a task or failure;
determine whether an edit is safe against current repository state;
recommend branch/worktree/sync/commit operations as typed data where permitted;
detect stale assumptions after concurrent/external changes;
support rollback/recovery reasoning using recorded state and evidence;
provide repository provenance/evidence to Planner, Write, Verify and Review experts.

Symbolic repository KB

Normalize observations into inspectable terms/facts equivalent to:

repo(Repo).
repo_head(Repo, Commit).
repo_branch(Repo, Branch).
repo_dirty(Repo, Paths).
repo_remote_tracking(Repo, Branch, RemoteRef).
repo_ahead_behind(Repo, Branch, Ahead, Behind).
commit_parent(Commit, Parent).
commit_touches(Commit, Path).
worktree_state(Repo, State).

Use Prolog graph reasoning for ancestry, reachability, divergence, change attribution and expected-state checks.

Safety / authority

Observing repository state grants no mutation authority.

If the expert recommends a mutating Git action:

it is represented as closed typed data;
availability != capability != authority;
expected head/preimage should be included where relevant;
actual mutation goes through the canonical host tool/effect boundary;
uncertain remote outcomes stay uncertain until observed/reconciled;
expert logic gets no ambient shell.

Cooperation

Project Knowledge Expert owns source semantics; Git Expert owns repository/version-control semantics.
Write Expert checks repository/preimage state before emitting edits.
Planner uses Git Expert to establish prerequisites and recovery paths.
Verify/Review use Git history/diff evidence where requirements concern changed state.
Repair Expert may ask Git Expert to localize regression-introducing changes.

LLM policy

Normal Git reasoning uses zero model calls.

Optional model fallback may help interpret fuzzy operator intent or summarize a complex history, but cannot decide authority, execute commands, or replace deterministic repository-state checks. Only explicit fallback usage is metered.

Acceptance

Clean/dirty/diverged/detached fixtures classify correctly with zero model calls.
Commit ancestry and merge-base style relationships are derived symbolically from fixture facts.
Expected-head mismatch produces structured stale/conflict state before mutation.
sync_remote is recommended as typed plan work but never registered as a Git Expert operation.
Repository observation does not grant write capability.
Mutating recommendations remain typed inert data until canonical authority/effect admission.
Concurrent head/worktree change invalidates stale assumptions deterministically.
Git evidence can be consumed by Write/Verify/Review without scraping prose.
No shell command assembled from model/project data is executed by the core expert.
Concrete downstream Git implementation can be swapped without changing expert reasoning tests.

Non-goals

No concrete product Git CLI pack in core.
No forge issue/PR API ownership unless later added as a separate reusable expert.
No replacement for source semantic knowledge in #380.

Refs #376 #377 #379 #380 #141 #355

Parent: #376 Depends on: #377 Integrates with: #379, #380, #141, #355 ## Goal Add a reusable **Git / Repository Expert** that reasons about repository state, history, branches, diffs, worktrees, remotes and safe repository transitions using typed host-supplied Git observations/actions. The expert belongs in `prolog-rlm` because the **reasoning policy and normalized repository knowledge are reusable**. Concrete product Git tool implementations remain downstream/host supplied per #141. ## Hard boundary Do not reintroduce the old #49/#50 architecture by shipping ambient concrete Git commands in core. The expert reasons over normalized capabilities/results equivalent to: ```text repo_status repo_head repo_branch repo_diff repo_show repo_log repo_merge_base repo_worktree_state repo_remote_state repo_apply_patch / commit / branch operations when host supplies them ``` Exact tool names are host/product contracts. The expert contract should operate on normalized repository facts and typed capability metadata, not shell command strings. ## D6-11 interaction `sync_remote/1` remains a **plan-native deterministic operation** per #355 and is not implemented as an expert handler. The Git Expert may conclude that synchronization is required and return a typed requirement/plan recommendation for `sync_remote`, after which the plan layer executes it through the canonical capability/authority/effect boundary. Likewise, deterministic `run`, `index`, and `delete` remain outside this expert. ## Responsibilities - establish current repository/worktree/head/branch state from host observations; - reason about clean/dirty/conflicted/diverged/detached/behind/ahead states; - compare expected vs observed head/preimage state; - identify relevant commits/diffs/history for a task or failure; - determine whether an edit is safe against current repository state; - recommend branch/worktree/sync/commit operations as typed data where permitted; - detect stale assumptions after concurrent/external changes; - support rollback/recovery reasoning using recorded state and evidence; - provide repository provenance/evidence to Planner, Write, Verify and Review experts. ## Symbolic repository KB Normalize observations into inspectable terms/facts equivalent to: ```prolog repo(Repo). repo_head(Repo, Commit). repo_branch(Repo, Branch). repo_dirty(Repo, Paths). repo_remote_tracking(Repo, Branch, RemoteRef). repo_ahead_behind(Repo, Branch, Ahead, Behind). commit_parent(Commit, Parent). commit_touches(Commit, Path). worktree_state(Repo, State). ``` Use Prolog graph reasoning for ancestry, reachability, divergence, change attribution and expected-state checks. ## Safety / authority Observing repository state grants no mutation authority. If the expert recommends a mutating Git action: - it is represented as closed typed data; - availability != capability != authority; - expected head/preimage should be included where relevant; - actual mutation goes through the canonical host tool/effect boundary; - uncertain remote outcomes stay uncertain until observed/reconciled; - expert logic gets no ambient shell. ## Cooperation - Project Knowledge Expert owns source semantics; Git Expert owns repository/version-control semantics. - Write Expert checks repository/preimage state before emitting edits. - Planner uses Git Expert to establish prerequisites and recovery paths. - Verify/Review use Git history/diff evidence where requirements concern changed state. - Repair Expert may ask Git Expert to localize regression-introducing changes. ## LLM policy Normal Git reasoning uses zero model calls. Optional model fallback may help interpret fuzzy operator intent or summarize a complex history, but cannot decide authority, execute commands, or replace deterministic repository-state checks. Only explicit fallback usage is metered. ## Acceptance - [ ] Clean/dirty/diverged/detached fixtures classify correctly with zero model calls. - [ ] Commit ancestry and merge-base style relationships are derived symbolically from fixture facts. - [ ] Expected-head mismatch produces structured stale/conflict state before mutation. - [ ] `sync_remote` is recommended as typed plan work but never registered as a Git Expert operation. - [ ] Repository observation does not grant write capability. - [ ] Mutating recommendations remain typed inert data until canonical authority/effect admission. - [ ] Concurrent head/worktree change invalidates stale assumptions deterministically. - [ ] Git evidence can be consumed by Write/Verify/Review without scraping prose. - [ ] No shell command assembled from model/project data is executed by the core expert. - [ ] Concrete downstream Git implementation can be swapped without changing expert reasoning tests. ## Non-goals - No concrete product Git CLI pack in core. - No forge issue/PR API ownership unless later added as a separate reusable expert. - No replacement for source semantic knowledge in #380. Refs #376 #377 #379 #380 #141 #355