fix: preserve staged and unstaged changes per file (#3104)
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# ADR-2026-08-27-mixed-git-change-facets: Preserve mixed Git changes as path facets
|
||||
|
||||
**Status:** accepted
|
||||
**Date:** 2026-08-27
|
||||
**Area:** backend, agentctl, frontend, protocol
|
||||
|
||||
## Context
|
||||
|
||||
Git porcelain reports the index and working tree independently. A tracked path can therefore have a
|
||||
staged edit and a later unstaged edit (`MM`), while a newly staged path can receive another unstaged
|
||||
edit (`AM`). Kandev currently collapses both columns into one `FileInfo`. The parser prioritizes the
|
||||
working-tree column, so the file appears only under Unstaged, and its `HEAD`-relative diff merges both
|
||||
layers.
|
||||
|
||||
The file path is still one mutation and review identity. Duplicating the path in the status map would
|
||||
distort changed-file counts, path-based stage operations, multi-repository keys, carry-forward logic,
|
||||
and Review deduplication. Replacing the wire shape outright would also break stored snapshots and
|
||||
older frontend consumers. The model needs to retain one path identity while exposing two independently
|
||||
selectable change layers.
|
||||
|
||||
## Decision
|
||||
|
||||
`GitStatusUpdate.Files` remains a map with one entry per repository-relative path. `FileInfo` keeps
|
||||
its existing flattened fields and adds two optional facet objects: `staged_change` and
|
||||
`unstaged_change`. A facet carries status, additions, deletions, old path, diff content, and diff skip
|
||||
reason.
|
||||
|
||||
Agentctl emits both facet objects when the porcelain index and working-tree columns both describe a
|
||||
change. Single-layer paths retain the existing compact shape. For mixed paths, the flattened fields
|
||||
remain the existing compatibility projection: worktree-priority classification plus the combined
|
||||
`HEAD`-to-working-tree diff. The staged facet is computed from `HEAD` to the index, and the unstaged
|
||||
facet from the index to the working tree.
|
||||
|
||||
New consumers use the facets when present and fall back to the flattened fields otherwise. Changes
|
||||
may project two temporary rows, but raw status, Review aggregation, badges, and Git mutations remain
|
||||
keyed once by `(repository, path)`. A diff target is keyed by `(repository, path, layer)` so opening
|
||||
the staged and unstaged rows cannot resolve to the same content or pinned panel.
|
||||
|
||||
Every serialized diff representation participates in the existing total snapshot budget and retains
|
||||
the existing per-representation output cap and skip reasons. Facet metadata survives even when its
|
||||
diff content is skipped. Git unmerged/conflict states are not redefined by this decision.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Desktop and mobile Changes can show one path in both Staged and Unstaged with accurate layer stats
|
||||
and diffs.
|
||||
- Existing snapshots and clients remain decodable because the flattened fields stay present and the
|
||||
new fields are optional.
|
||||
- Mixed entries can serialize more diff content than single-layer entries, but the shared snapshot
|
||||
threshold still bounds total enrichment.
|
||||
- Frontend equality checks, diff identities, and focus fingerprints must include the layer/facet data
|
||||
or facet-only updates can be missed.
|
||||
- Stage, unstage, discard, Review deduplication, and changed-file totals must never treat a projected
|
||||
facet row as a second path mutation.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Add two status-map entries with synthetic path keys
|
||||
|
||||
Rejected. Synthetic keys would leak into path operations, changed-file counts, multi-repository
|
||||
identity, editor synchronization, and Review deduplication.
|
||||
|
||||
### Replace `FileInfo` with an array of layer records
|
||||
|
||||
Rejected. This is a breaking wire and stored-snapshot migration for a state that can be represented
|
||||
additively. Older consumers would fail to decode or render ordinary status snapshots.
|
||||
|
||||
### Keep one record and concatenate staged and unstaged diffs
|
||||
|
||||
Rejected. A separator can make both hunks visible, but it cannot give each section accurate status,
|
||||
line totals, selection identity, or staging transitions.
|
||||
|
||||
### Fetch a layer-specific diff only after row selection
|
||||
|
||||
Rejected for this repair. It avoids duplicate streamed diff content but adds a new request lifecycle,
|
||||
loading and failure states, and cache invalidation path to a panel that already receives bounded diff
|
||||
data. The existing snapshot budget is sufficient for the additive facet contract.
|
||||
@@ -214,4 +214,5 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
|
||||
| 2026-08-27-bounded-agent-profile-recency | [Store Agent Profile Recency in Bounded Context Rows](2026-08-27-bounded-agent-profile-recency.md) | accepted | backend, frontend, protocol | 2026-08-27 |
|
||||
| 2026-08-27-protect-deferred-launch-attribution | [Protect Deferred Launch Attribution](2026-08-27-protect-deferred-launch-attribution.md) | accepted | backend, protocol | 2026-08-27 |
|
||||
| 2026-08-27-preserve-legacy-sqlite-before-default-initialization | [Preserve Legacy SQLite Data Before Default Initialization](2026-08-27-preserve-legacy-sqlite-before-default-initialization.md) | accepted | backend, cli, operations | 2026-08-27 |
|
||||
| 2026-08-27-mixed-git-change-facets | [Preserve mixed Git changes as path facets](2026-08-27-mixed-git-change-facets.md) | accepted | backend, agentctl, frontend, protocol | 2026-08-27 |
|
||||
| 2026-08-28-bind-github-auto-merge-attempts-to-reviewed-head | [Bind GitHub Auto-Merge Attempts to the Reviewed Head](2026-08-28-bind-github-auto-merge-attempts-to-reviewed-head.md) | accepted | backend, frontend, protocol, security, GitHub | 2026-08-28 |
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
created: 2026-08-27
|
||||
status: completed
|
||||
requirements:
|
||||
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
|
||||
system_design:
|
||||
- ../../specs/platform/system-design/workspace-git-status.md
|
||||
legacy_specs: []
|
||||
---
|
||||
|
||||
# Implementation Plan: Mixed Staged and Unstaged Changes
|
||||
|
||||
## Overview
|
||||
|
||||
Preserve both Git layers for one path, then project them into accurate Changes rows and diff targets.
|
||||
Implementation starts with red backend, desktop, and mobile regressions; publishes the additive
|
||||
agentctl contract next; then consumes it in the shared frontend so both platform layouts turn green.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- Preserve staged and unstaged facets for ordinary mixed porcelain states such as `MM` and `AM`.
|
||||
- Keep one raw repository/path identity while rendering facet-specific rows, stats, and diffs.
|
||||
- Route desktop and mobile diff selection by change layer.
|
||||
- Preserve current file-level stage, unstage, discard, Review, and unique changed-file counts.
|
||||
- Keep facet diff content inside the established status-snapshot budget.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Hunk-level staging.
|
||||
- New conflict or unmerged-state semantics.
|
||||
- A Changes panel visual redesign.
|
||||
- A new on-demand diff API.
|
||||
|
||||
## Technical approach
|
||||
|
||||
### Agentctl status contract
|
||||
|
||||
Add `FileChangeFacet` plus optional `StagedChange` and `UnstagedChange` fields to
|
||||
`apps/backend/internal/agentctl/types/streams/git.go`. Refactor `applyPorcelainLine` in
|
||||
`workspace_git_status.go` to interpret the `X` and `Y` columns independently while preserving the
|
||||
one-path compatibility projection.
|
||||
|
||||
Extend `workspace_git_diff.go` so a mixed path retains its existing `HEAD`-relative flattened diff,
|
||||
gets a staged `git diff --cached HEAD -- <path>` facet, and gets an unstaged
|
||||
`git diff -- <path>` facet. Teach diff-budget accounting and same-HEAD carry-forward to traverse the
|
||||
optional facets. No facet diff may bypass the shared threshold or existing skip-reason vocabulary.
|
||||
|
||||
### Frontend projection
|
||||
|
||||
Mirror the optional facet type in both frontend wire models. Add a pure projection helper under
|
||||
`apps/web/hooks/domains/session/` that returns staged and unstaged `FileInfo` views for Changes while
|
||||
keeping `allFiles` unique. `useSessionGit` and multi-repository summaries use those projected arrays
|
||||
for section and action availability. Store equality, editor synchronization, and Changes focus
|
||||
fingerprints include facet data so a layer-only update is observable.
|
||||
|
||||
Review's aggregate uncommitted source continues to use the flattened compatibility file. Mutation
|
||||
dispatch continues to receive only repository plus path, even when both projected rows exist.
|
||||
|
||||
### Layer-qualified diff selection
|
||||
|
||||
Add a staged/unstaged layer to `OpenDiffOptions` and file-mode `DiffSheetMode`. Propagate it through
|
||||
Changes rows, TaskChangesPanel selection, Dockview preview/pinned IDs, and the mobile diff drawer.
|
||||
Layer-qualified selections project the matching facet; legacy and non-layer selections keep the
|
||||
combined uncommitted view. The same shared Changes body remains in desktop and mobile layouts.
|
||||
|
||||
This approach implements
|
||||
[ADR-2026-08-27-mixed-git-change-facets](../../decisions/2026-08-27-mixed-git-change-facets.md).
|
||||
|
||||
## Tests
|
||||
|
||||
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7` and `.9`: add
|
||||
`apps/backend/internal/agentctl/server/process/workspace_git_mixed_changes_test.go` covering `MM`,
|
||||
`AM`, independent numstat/diff content, carry-forward, and shared budget accounting.
|
||||
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10` and `.11`: add
|
||||
`apps/web/hooks/domains/session/git-change-facets.test.ts` for unique raw identity, two projections,
|
||||
layer stats, and mutation-path deduplication; extend Git summary and status equality tests.
|
||||
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10`: extend
|
||||
`apps/web/components/task/task-changes-panel.test.ts` and
|
||||
`apps/web/lib/state/dockview-panel-actions.test.ts` for layer-specific content and panel identity.
|
||||
- `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12`: add focused mobile component coverage proving the same
|
||||
facet target reaches the existing full-height diff drawer.
|
||||
|
||||
## E2E tests
|
||||
|
||||
- Desktop, `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10` and `.11`: extend
|
||||
`apps/web/e2e/tests/git/git-changes-panel.spec.ts` with a tracked `MM` file. Assert the same path is
|
||||
present in both sections, each row shows its own line count and diff, and unstage leaves the
|
||||
unstaged facet.
|
||||
- Mobile, `AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12`: extend
|
||||
`apps/web/e2e/tests/task/mobile-changes-panel.spec.ts` with the same setup and assert both sections,
|
||||
layer-specific drawer content, and touch staging behavior.
|
||||
|
||||
## Work orders
|
||||
|
||||
- [x] [Task 01: Capture mixed-change regression](task-01-capture-mixed-change-regression.md)
|
||||
- [x] [Task 02: Publish mixed-change facets](task-02-publish-mixed-change-facets.md)
|
||||
- [x] [Task 03: Render layer-specific changes](task-03-render-layer-specific-changes.md)
|
||||
|
||||
## Verification results
|
||||
|
||||
- Task 01 RED evidence captured. Agentctl omitted `staged_change`; desktop and mobile could not find
|
||||
the staged section for the mixed path.
|
||||
- Task 02 published additive staged and unstaged facets with independent diffs, bounded shared
|
||||
accounting, and budget-aware carry-forward. The focused and package-level Go suites passed.
|
||||
- Task 03 projected one raw path into two layer-qualified rows and diff targets while retaining
|
||||
unique totals and mutation identity. Focused frontend tests, typecheck, lint guards, and fresh
|
||||
desktop/mobile Playwright regressions passed, including the unstage transition.
|
||||
|
||||
## Risks
|
||||
|
||||
- Compatibility and facet diffs duplicate content for mixed paths; incorrect budget accounting could
|
||||
exceed the bounded snapshot contract.
|
||||
- A path shown twice can accidentally double-count badges or dispatch the same mutation twice unless
|
||||
raw identity and projected presentation remain separate.
|
||||
- Omitting the layer from a Dockview or mobile selection key would reopen the bug by showing the
|
||||
combined or wrong facet diff.
|
||||
- Rename/delete combinations use different porcelain and numstat path shapes; parser tests must prove
|
||||
that ordinary supported mixed states retain the correct final path.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: "01-capture-mixed-change-regression"
|
||||
title: "Capture mixed-change regression"
|
||||
status: completed
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
|
||||
acceptance_criteria:
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.9
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12
|
||||
system_design:
|
||||
- ../../specs/platform/system-design/workspace-git-status.md
|
||||
---
|
||||
|
||||
# Task 01: Capture mixed-change regression
|
||||
|
||||
## Summary
|
||||
|
||||
Create permanent backend, desktop, and mobile tests that reproduce the confirmed `MM` failure before
|
||||
production changes. Record red results showing that the staged facet is missing and the diff is
|
||||
combined.
|
||||
|
||||
## In scope
|
||||
|
||||
- Add a focused backend mixed-status test file.
|
||||
- Add one desktop and one mobile Playwright regression using a real tracked file.
|
||||
- Capture the expected red reason for each test before implementation.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Production contract or UI changes.
|
||||
- Broad E2E suite execution.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- The backend test expects independent staged and unstaged facets from one path.
|
||||
- Both browser tests expect the same path in both sections and layer-specific diff content.
|
||||
- Before correction, each targeted test fails only because current code collapses the two layers.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps/backend
|
||||
go test ./internal/agentctl/server/process -run 'TestWorkspaceGitStatusPreservesMixedChangeFacets'
|
||||
|
||||
cd apps/web
|
||||
pnpm e2e:run tests/git/git-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
|
||||
pnpm e2e:run --project mobile-chrome tests/task/mobile-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
|
||||
```
|
||||
|
||||
The commands are expected to fail at this red checkpoint. Save the precise assertion failures in the
|
||||
work-order Results section before continuing.
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agentctl/server/process/workspace_git_mixed_changes_test.go`
|
||||
- `apps/web/e2e/tests/git/git-changes-panel.spec.ts`
|
||||
- `apps/web/e2e/tests/task/mobile-changes-panel.spec.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Risks
|
||||
|
||||
- E2E setup must mutate only its disposable fixture worktree and wait on observable status updates.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirement acceptance criteria `.9`, `.10`, and `.12`.
|
||||
- Existing workspace Git process tests and desktop/mobile Changes E2E fixtures.
|
||||
- Manual reproduction evidence from `MM README.md` and `AM mixed-stage-panel-test.txt`.
|
||||
|
||||
## Results
|
||||
|
||||
- `go test -json ./internal/agentctl/server/process -run '^TestWorkspaceGitStatusPreservesMixedChangeFacets$' -count=1` failed at the intended assertion: the `FileInfo` wire had one combined `+2` diff and no `staged_change` facet.
|
||||
- Desktop Chromium failed at the intended assertion: `staged-files-section-collapse-toggle` was absent.
|
||||
- Mobile Chrome failed twice at the same intended assertion: `staged-files-section-collapse-toggle` was absent.
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
id: "02-publish-mixed-change-facets"
|
||||
title: "Publish mixed-change facets"
|
||||
status: completed
|
||||
wave: 2
|
||||
depends_on:
|
||||
- "01-capture-mixed-change-regression"
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
|
||||
acceptance_criteria:
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.8
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.9
|
||||
system_design:
|
||||
- ../../specs/platform/system-design/workspace-git-status.md
|
||||
---
|
||||
|
||||
# Task 02: Publish mixed-change facets
|
||||
|
||||
## Summary
|
||||
|
||||
Extend the agentctl status wire additively and populate independent staged and unstaged metadata for
|
||||
mixed paths. Preserve legacy fields and the established enrichment limits.
|
||||
|
||||
## In scope
|
||||
|
||||
- Add the optional facet type and fields to `FileInfo`.
|
||||
- Parse index and working-tree porcelain columns independently for ordinary supported states.
|
||||
- Enrich `HEAD -> index`, `index -> worktree`, and flattened compatibility diffs.
|
||||
- Include facet content in budget, truncation, carry-forward, and skip-reason logic.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Frontend facet rendering.
|
||||
- New behavior for unmerged/conflict states.
|
||||
- New Git routes.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- `MM` and `AM` produce one path entry with both accurate facets.
|
||||
- Pure staged, pure unstaged, and untracked paths retain the legacy compact representation.
|
||||
- Facet content cannot bypass the 256 KiB representation cap or shared 2 MiB threshold.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps/backend
|
||||
go test ./internal/agentctl/server/process -run 'TestWorkspaceGitStatusPreservesMixedChangeFacets|TestMixedChangeFacetDiffs|TestMixedChangeFacetBudget|TestCarryForwardMixedChangeFacets'
|
||||
go test ./internal/agentctl/types/streams ./internal/agentctl/server/process
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/backend/internal/agentctl/types/streams/git.go`
|
||||
- `apps/backend/internal/agentctl/server/process/workspace_git_status.go`
|
||||
- `apps/backend/internal/agentctl/server/process/workspace_git_diff.go`
|
||||
- `apps/backend/internal/agentctl/server/process/workspace_git_mixed_changes_test.go`
|
||||
- `apps/backend/internal/agentctl/server/process/workspace_git_diff_test.go`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 01 red regression evidence.
|
||||
|
||||
## Risks
|
||||
|
||||
- Rename numstat paths and compatibility projections can address different old/new names.
|
||||
- Carrying prior facet content after an enrichment failure must not overwrite a fresh sibling facet.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirement acceptance criteria `.7`, `.8`, and `.9`.
|
||||
- Mixed-change section of the workspace Git status design.
|
||||
- ADR-2026-08-27-mixed-git-change-facets.
|
||||
|
||||
## Results
|
||||
|
||||
- Added optional `staged_change` and `unstaged_change` wire facets while preserving the flattened
|
||||
compatibility fields and compact pure-change representation.
|
||||
- Parsed supported porcelain index/worktree states independently and enriched mixed paths with
|
||||
`HEAD -> index` and `index -> worktree` diffs.
|
||||
- Shared representation accounting now includes both facets; same-HEAD carry-forward preserves each
|
||||
facet independently without bypassing an exhausted budget.
|
||||
- `go test ./internal/agentctl/types/streams ./internal/agentctl/server/process` passed.
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
id: "03-render-layer-specific-changes"
|
||||
title: "Render layer-specific changes"
|
||||
status: completed
|
||||
wave: 3
|
||||
depends_on:
|
||||
- "02-publish-mixed-change-facets"
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
|
||||
acceptance_criteria:
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.11
|
||||
- AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12
|
||||
system_design:
|
||||
- ../../specs/platform/system-design/workspace-git-status.md
|
||||
---
|
||||
|
||||
# Task 03: Render layer-specific changes
|
||||
|
||||
## Summary
|
||||
|
||||
Consume mixed facets as two presentation rows while retaining one raw file identity and one mutation
|
||||
target. Carry the selected layer through desktop Dockview and the existing mobile diff drawer, then
|
||||
turn the red browser regressions green.
|
||||
|
||||
## In scope
|
||||
|
||||
- Mirror and project the optional facet contract in frontend state.
|
||||
- Derive staged/unstaged sections and action availability from projected facets.
|
||||
- Keep overall counts, Review aggregation, and mutation dispatch unique by repository/path.
|
||||
- Include facet data in status equality, editor synchronization, and focus fingerprints.
|
||||
- Add layer to desktop and mobile diff targets and pinned identities.
|
||||
- Add focused unit/component tests and satisfy both Playwright regressions.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- New layout, copy, controls, or localization keys.
|
||||
- Hunk staging.
|
||||
- Changing the combined Review source.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- One mixed raw entry produces accurate Staged and Unstaged rows without doubling the overall file
|
||||
count or Git mutation.
|
||||
- Selecting either row renders only its facet and may coexist with the other layer as a pinned diff.
|
||||
- Desktop and mobile targeted E2E tests pass using the same backend snapshot contract.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps
|
||||
pnpm --filter @kandev/web test -- hooks/domains/session/git-change-facets.test.ts hooks/domains/session/use-session-git-grouping.test.ts hooks/domains/session/use-session-git-summary.test.ts lib/state/slices/session-runtime/set-git-status-return.test.ts components/task/changes-panel-focus.test.ts components/task/task-changes-panel.test.ts lib/state/dockview-panel-actions.test.ts components/task/mobile/mobile-changes-panel.test.tsx
|
||||
|
||||
cd apps/web
|
||||
pnpm run typecheck
|
||||
pnpm e2e:run tests/git/git-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
|
||||
pnpm e2e:run --project mobile-chrome tests/task/mobile-changes-panel.spec.ts -- --grep "same path in staged and unstaged sections"
|
||||
pnpm run lint:e2e-sleeps
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/lib/state/slices/session-runtime/types.ts`
|
||||
- `apps/web/lib/types/backend.ts`
|
||||
- `apps/web/hooks/domains/session/git-change-facets.ts`
|
||||
- `apps/web/hooks/domains/session/git-change-facets.test.ts`
|
||||
- `apps/web/hooks/domains/session/use-session-git.ts`
|
||||
- `apps/web/hooks/domains/session/use-session-git-summary.ts`
|
||||
- `apps/web/lib/state/slices/session-runtime/session-runtime-slice.ts`
|
||||
- `apps/web/components/task/changes-panel-focus.ts`
|
||||
- `apps/web/components/task/changes-diff-target.ts`
|
||||
- `apps/web/components/task/task-changes-panel.tsx`
|
||||
- `apps/web/components/task/dockview-panel-content.tsx`
|
||||
- `apps/web/components/task/dockview-shared.tsx`
|
||||
- `apps/web/lib/state/dockview-panel-actions.ts`
|
||||
- `apps/web/lib/state/dockview-store.ts`
|
||||
- `apps/web/components/task/mobile/mobile-changes-panel.tsx`
|
||||
- `apps/web/components/task/mobile/mobile-diff-sheet.tsx`
|
||||
- `apps/web/e2e/tests/git/git-changes-panel.spec.ts`
|
||||
- `apps/web/e2e/tests/task/mobile-changes-panel.spec.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 02 additive wire contract and green backend regression.
|
||||
|
||||
## Risks
|
||||
|
||||
- Preview and pinned panel IDs must include the layer without breaking legacy file and commit targets.
|
||||
- Selected-diff compatibility paths can reopen combined-diff behavior if they omit the layer.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirement acceptance criteria `.10`, `.11`, and `.12`.
|
||||
- Mixed-change and mobile-parity sections of the workspace Git status design.
|
||||
- Existing shared Changes body, Dockview preview machinery, and mobile diff drawer.
|
||||
|
||||
## Results
|
||||
|
||||
- Added shared facet projection and layer-qualified desktop/mobile diff targets while preserving one
|
||||
aggregate Review file and one repository/path mutation target.
|
||||
- Included facet updates in state equality, editor synchronization, focus fingerprints, summary
|
||||
projection, and Dockview identity.
|
||||
- Coarse-pointer tree rows now expose an always-visible 44px stage action; fine-pointer hover layout
|
||||
remains unchanged.
|
||||
- Focused Vitest coverage, frontend typecheck, targeted ESLint, i18n ratchet, and E2E sleep ratchet
|
||||
passed. The repository-wide `lint:e2e-sleeps` command still reports unrelated baseline violations;
|
||||
both changed E2E files pass its dedicated ESLint configuration.
|
||||
- Fresh desktop Chromium and mobile Chrome regressions passed, proving independent row counts and
|
||||
diffs plus the unstage transition that removes only the staged facet.
|
||||
@@ -2,7 +2,7 @@
|
||||
status: active
|
||||
system: platform
|
||||
created: 2026-07-19
|
||||
updated: 2026-08-19
|
||||
updated: 2026-08-27
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
@@ -26,8 +26,12 @@ Users opening or focusing Changes and Review need a current workspace snapshot w
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.4:** Every non-cancelled caller receives the same completed snapshot or error from a shared observation. A caller whose own context is cancelled returns promptly without cancelling or otherwise poisoning the result for other callers.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.5:** Tracker shutdown or the bounded shared-observation deadline cancels the underlying work. Cancelled work does not publish or cache a partial snapshot.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.6:** After Git output is parsed, changed-file and synthetic untracked-diff enrichment performs work proportional to the number of changed entries plus the bounded content processed.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7:** Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum emitted diff per file, and a 2 MiB enrichment threshold per status snapshot. Because the threshold is checked before enriching each file, the final accepted file may preserve the existing overshoot of up to the 256 KiB per-file cap. Existing skip reasons remain unchanged.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.7:** Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum per emitted diff representation, and a 2 MiB enrichment threshold per status snapshot. Flattened compatibility diffs and layer-specific diffs all participate in the same snapshot threshold. Because the threshold is checked before enriching each representation, the final accepted representation may preserve the existing overshoot of up to the 256 KiB cap. Existing skip reasons remain unchanged.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.8:** Large changed sets retain every path and its status metadata. Once the total diff budget is exhausted, files that are not enriched retain `budget_exceeded` as their diff skip reason.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.9:** When one path has both index and working-tree changes, the workspace snapshot preserves the staged and unstaged change facets independently, including each facet's status, line totals, rename origin, diff content, and diff skip reason when applicable.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.10:** Changes lists a mixed path in both Staged and Unstaged, with facet-specific status and line totals. Opening either row shows only that layer's diff. Overall changed-file totals continue to count the repository and path once.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.11:** Staging or unstaging a mixed path operates once on its repository-qualified path and the next snapshot removes the consumed facet while preserving any facet that remains.
|
||||
- **AC-PLATFORM-WORKSPACE-GIT-STATUS-001.12:** Desktop and mobile Changes surfaces expose the same mixed-path sections, facet-specific diff selection, and staging actions without replacing their established platform-native layouts.
|
||||
|
||||
## System design
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ system: platform
|
||||
requirements:
|
||||
- REQ-PLATFORM-WORKSPACE-GIT-STATUS-001
|
||||
created: 2026-07-19
|
||||
updated: 2026-08-19
|
||||
updated: 2026-08-27
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
@@ -18,7 +18,7 @@ This design preserves the technical source detail for `REQ-PLATFORM-WORKSPACE-GI
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-PLATFORM-WORKSPACE-GIT-STATUS-001` | [Migrated source detail](#migrated-source-detail) |
|
||||
| `REQ-PLATFORM-WORKSPACE-GIT-STATUS-001` | [Migrated source detail](#migrated-source-detail), [Mixed index and working-tree changes](#mixed-index-and-working-tree-changes), [API surface](#api-surface) |
|
||||
|
||||
## Migrated source detail
|
||||
|
||||
@@ -34,11 +34,52 @@ Users opening or focusing Changes and Review need a current workspace snapshot w
|
||||
- Every non-cancelled caller receives the same completed snapshot or error from a shared observation. A caller whose own context is cancelled returns promptly without cancelling or otherwise poisoning the result for other callers.
|
||||
- Tracker shutdown or the bounded shared-observation deadline cancels the underlying work. Cancelled work does not publish or cache a partial snapshot.
|
||||
- After Git output is parsed, changed-file and synthetic untracked-diff enrichment performs work proportional to the number of changed entries plus the bounded content processed.
|
||||
- Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum emitted diff per file, and a 2 MiB enrichment threshold per status snapshot. Because the threshold is checked before enriching each file, the final accepted file may preserve the existing overshoot of up to the 256 KiB per-file cap. Existing skip reasons remain unchanged.
|
||||
- Existing diff limits remain in force: 10 MiB maximum source file size, 256 KiB maximum per emitted diff representation, and a 2 MiB enrichment threshold per status snapshot. Every flattened or layer-specific representation participates in that threshold. Because the threshold is checked before enriching each representation, the final accepted representation may preserve the existing overshoot of up to the 256 KiB cap. Existing skip reasons remain unchanged.
|
||||
- Large changed sets retain every path and its status metadata. Once the total diff budget is exhausted, files that are not enriched retain `budget_exceeded` as their diff skip reason.
|
||||
- Multi-repository responses retain repository identity and partial-success behavior.
|
||||
- Verification tooling preserves shared managed Go and lint caches for reuse while keeping invocation scratch and command output outside repository worktrees. The root-level `.verify-cache` and `.tmp` paths are ignored as safeguards against legacy or misconfigured verification runs.
|
||||
|
||||
### Mixed index and working-tree changes
|
||||
|
||||
Git porcelain reports two independent status columns for each path: the index state (`X`) and the
|
||||
working-tree state (`Y`). A path such as `MM README.md` or `AM new-file.txt` is one file identity with
|
||||
two change facets. The workspace model MUST preserve both columns instead of selecting one as the
|
||||
file's only state.
|
||||
|
||||
`GitStatusUpdate.Files` remains keyed once by repository-relative path. `FileInfo` retains its
|
||||
flattened fields as a compatibility projection and adds optional `staged_change` and
|
||||
`unstaged_change` objects. Each object carries the facet's status, additions, deletions, old path,
|
||||
diff, and diff skip reason. Agentctl emits the facet objects for a mixed path; a path with only one
|
||||
layer continues to use the existing flattened representation. Consumers MUST accept both shapes.
|
||||
|
||||
For a mixed path, agentctl computes three intentional views:
|
||||
|
||||
- the flattened compatibility view compares `HEAD` with the working tree and preserves the existing
|
||||
worktree-priority `staged=false` classification for older consumers;
|
||||
- `staged_change` compares `HEAD` with the index using `git diff --cached`; and
|
||||
- `unstaged_change` compares the index with the working tree using `git diff` without a base ref.
|
||||
|
||||
All serialized diff strings, including the compatibility projection, participate in the existing
|
||||
snapshot-wide enrichment budget. Each representation retains the existing output cap and skip
|
||||
reasons. Budget exhaustion may omit one representation without discarding either facet's status
|
||||
metadata.
|
||||
|
||||
The frontend keeps the raw file map unique by `(repository_name, path)` for task badges, Review
|
||||
aggregation, mutation routing, and change-file totals. Changes derives two temporary `FileInfo`
|
||||
views from a mixed entry, one per facet, and falls back to the flattened fields when facet objects
|
||||
are absent. Stage, unstage, and discard operations continue to send only the repository-qualified
|
||||
path, never the temporary view identity.
|
||||
|
||||
Diff navigation adds the change layer to its target identity. Desktop preview and pinned diff tabs
|
||||
use `(repository_name, path, layer)` so the staged and unstaged views of one path cannot alias each
|
||||
other. The mobile full-height diff drawer carries the same layer while retaining its existing sheet,
|
||||
touch-target, and scroll behavior. Review's all-files source remains a single combined uncommitted
|
||||
file; only a layer-qualified Changes selection projects a facet-specific diff.
|
||||
|
||||
Status equality, editor synchronization signatures, and Changes focus fingerprints include the
|
||||
optional facet fields. A snapshot that changes only one facet must therefore publish and render.
|
||||
This contract follows [ADR-2026-08-27-mixed-git-change-facets](../../../decisions/2026-08-27-mixed-git-change-facets.md).
|
||||
|
||||
### Base-commit staleness and refresh
|
||||
|
||||
The commits panel (`git log <base>..HEAD`) and cumulative diff anchor to a base commit derived from the session's stored `base_commit_sha` and `base_branch`. That anchor becomes stale when the branch history moves relative to the true integration branch after the base was recorded — most commonly a stacked-PR parent that merges and disappears, a rebase onto the integration branch, or a base branch that was deleted upstream. When the anchor is stale, the panel enumerates commits that are not part of the branch's own contribution, inflating the count.
|
||||
@@ -73,6 +114,7 @@ Existing Git-status routes remain in place. Their result and stream payloads add
|
||||
- `GET /api/v1/git/status/multi?fresh=<bool>` returns the existing `MultiRepoGitStatusResult` shape containing `PerRepoGitStatus` entries.
|
||||
- The `fresh` query parameter continues to select a live observation rather than a cached tracker snapshot.
|
||||
- A repository status MAY include `comparison_target` with its credential-free display identity and `comparison_error_code` when the explicit target is unavailable.
|
||||
- A mixed-path `FileInfo` MAY include `staged_change` and `unstaged_change`. Each facet uses the same bounded status, line-total, rename, diff, and skip-reason vocabulary as the flattened file fields. Their absence preserves the legacy single-layer shape.
|
||||
- Commit and cumulative-diff requests use agentctl's configured repository-qualified ref when present. A caller-supplied branch name cannot override it.
|
||||
- The internal agentctl control API adds a per-repository comparison-target update alongside the existing base-branch update. It validates identities and refs, materializes the exact ref, replaces tracker state, and triggers a refresh.
|
||||
- The bounded task Git summary adds `comparison_unavailable`; when true, additions/deletions are not rendered as authoritative task-card statistics.
|
||||
@@ -83,6 +125,8 @@ Existing Git-status routes remain in place. Their result and stream payloads add
|
||||
|---|---|
|
||||
| Primary branch or porcelain observation fails | The live observation fails and the prior cached snapshot remains available. |
|
||||
| Secondary diff enrichment fails | The established same-HEAD carry-forward behavior is preserved. |
|
||||
| A path has both index and working-tree changes | One raw file entry carries both facets. Changes renders one row in Staged and one in Unstaged, while overall file totals count the path once. |
|
||||
| A mixed path's layer diff exceeds its cap or the snapshot budget | The affected facet retains status metadata and reports the existing `truncated` or `budget_exceeded` skip reason; the other facet remains independently usable. |
|
||||
| One caller cancels while a shared observation is running | That caller returns its context cancellation promptly; other callers remain eligible to receive the shared result. |
|
||||
| The tracker stops or the shared deadline expires | Underlying work is cancelled and no partial result is published or cached. |
|
||||
| One repository fails during a multi-repository request | Successful repository entries remain available and the failure is reported on its repository entry. |
|
||||
@@ -104,6 +148,9 @@ Existing Git-status routes remain in place. Their result and stream payloads add
|
||||
- **GIVEN** one waiter cancels during a shared observation, **WHEN** other waiters remain, **THEN** the cancelled waiter returns promptly and the remaining waiters receive the completed result.
|
||||
- **GIVEN** tracker shutdown or the shared-observation deadline while enrichment is running, **WHEN** cancellation reaches the observation, **THEN** filesystem iteration stops and no partial snapshot is cached.
|
||||
- **GIVEN** approximately 15,000 untracked text files, **WHEN** fresh status is computed, **THEN** every path is present, emitted diff content obeys the existing limits, files not enriched after total-budget exhaustion have `budget_exceeded`, and post-porcelain enrichment remains linear in the number of entries.
|
||||
- **GIVEN** a tracked file with one staged edit and a different unstaged edit, **WHEN** fresh status is computed, **THEN** its one path entry contains staged and unstaged facets with independent line totals and `HEAD -> index` and `index -> working tree` diffs.
|
||||
- **GIVEN** a newly added staged file that receives another unstaged edit, **WHEN** Changes opens on desktop or mobile, **THEN** the same path appears in both Staged and Unstaged, selecting each row shows only that layer, and the overall changed-file count remains one.
|
||||
- **GIVEN** a mixed path visible in both sections, **WHEN** the user stages or unstages it, **THEN** one repository-qualified Git mutation runs and the next snapshot shows only the facet that remains.
|
||||
- **GIVEN** one invalid repository in a multi-repository request, **WHEN** other repositories succeed, **THEN** the response retains the successful entries and reports the failure only on the invalid repository.
|
||||
- **GIVEN** verification needs writable scratch space, **WHEN** it selects a location, **THEN** the location is outside every Git worktree and existing shared caches remain reusable; if a legacy run creates root-level `.verify-cache` or `.tmp`, Git status ignores it.
|
||||
- **GIVEN** a session whose stored `base_commit_sha` is a strict ancestor of `merge-base(HEAD, <resolved integration candidate>)` (for example a stacked-PR parent branch that has since merged into the integration branch and lost its upstream ref), **WHEN** the commits panel is requested, **THEN** the enumerated commit count matches `git rev-list --first-parent --count $(git merge-base HEAD <resolved integration candidate>)..HEAD` and excludes the commits that already landed on the integration branch.
|
||||
@@ -131,7 +178,10 @@ Existing Git-status routes remain in place. Their result and stream payloads add
|
||||
- Granting a new Git credential scope for a private comparison repository.
|
||||
- Periodically fetching a moving target branch on every status poll. Targets are refreshed on association, retarget, launch/resume, and explicit comparison refresh.
|
||||
- Automatically changing the checkout, push remote, upstream, or `origin` because a comparison target changes.
|
||||
- Redesigning the desktop Changes panel or compressing it into the mobile layout.
|
||||
- Adding hunk-level staging or changing the existing whole-file stage, unstage, and discard semantics.
|
||||
- Defining new behavior for Git's unmerged/conflict porcelain states; those continue to follow their existing handling.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
See [Workspace Git Status Scalability plan](../../../plans/workspace-git-status-scalability/plan.md) and [Fork PR Comparison Targets plan](../../../plans/fork-pr-comparison-targets/plan.md).
|
||||
See [Workspace Git Status Scalability plan](../../../plans/workspace-git-status-scalability/plan.md), [Fork PR Comparison Targets plan](../../../plans/fork-pr-comparison-targets/plan.md), and [Mixed Staged and Unstaged Changes plan](../../../plans/mixed-staged-unstaged-changes/plan.md).
|
||||
|
||||
Reference in New Issue
Block a user