Carlos Florêncio
112 lines
4.7 KiB
Markdown
112 lines
4.7 KiB
Markdown
---
|
|
id: "01-stabilize-commit-provenance"
|
|
title: "Stabilize commit provenance across refreshes"
|
|
status: completed
|
|
wave: 1
|
|
depends_on: []
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-TASKS-REMOTE-CONTRIBUTION-TASKS-001
|
|
acceptance_criteria:
|
|
- AC-TASKS-REMOTE-CONTRIBUTION-TASKS-001.4
|
|
- AC-TASKS-REMOTE-CONTRIBUTION-TASKS-001.7
|
|
system_design:
|
|
- ../../specs/tasks/system-design/remote-contribution-tasks.md
|
|
---
|
|
|
|
# Task 01: Stabilize Commit Provenance Across Refreshes
|
|
|
|
## Summary
|
|
|
|
Retain the last successful provider commit list for display while a newer evidence version for the same
|
|
pull request is pending or failed. Keep relation classification and all remote actions bound to current,
|
|
complete evidence, then prove the task-switch behavior through focused unit and browser regressions.
|
|
|
|
## In scope
|
|
|
|
- Add an explicit display-commit projection to the provider commit resource and hook result.
|
|
- Carry retained display commits only across source versions with the same stable contribution identity.
|
|
- Keep provider head, completeness, errors, and authoritative commits scoped to the current version.
|
|
- Route authoritative evidence to relation classification and display evidence to Changes reconciliation.
|
|
- Cover pending, failure, success replacement, identity switch, action safety, and task-switch rendering.
|
|
|
|
## Out of scope
|
|
|
|
- Provider snapshot persistence.
|
|
- Local Git status or backend commit-history changes.
|
|
- Commit marker design, translations, or responsive layout changes.
|
|
- General Git subscription deduplication.
|
|
|
|
## Acceptance
|
|
|
|
- A same-PR version refresh never replaces previous confirmed pushed markers with unpushed arrows while
|
|
the current request is pending or failed. A successful response replaces the retained display
|
|
snapshot.
|
|
- A different workspace, repository, or pull request cannot receive retained commits, and late responses
|
|
cannot replace the selected identity or version.
|
|
- Retained display commits never establish alignment or divergence and never enable Push, Pull, or
|
|
contribution replacement without complete current evidence.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
(cd apps && pnpm --filter @kandev/web test -- --run hooks/domains/github/use-pr-commits.test.ts hooks/domains/session/use-remote-contribution-relation.test.tsx components/task/changes-panel-remote.test.ts)
|
|
(cd apps/web && pnpm run typecheck)
|
|
(cd apps && pnpm --filter @kandev/web lint)
|
|
(cd apps/web && pnpm e2e:run tests/pr/pr-switcher-changes.spec.ts)
|
|
(git diff --check)
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/web/hooks/domains/github/pr-commits-resource.ts`
|
|
- `apps/web/hooks/domains/github/use-pr-commits.ts`
|
|
- `apps/web/hooks/domains/github/use-pr-commits.test.ts`
|
|
- `apps/web/hooks/domains/session/use-remote-contribution-relation.ts`
|
|
- `apps/web/hooks/domains/session/use-remote-contribution-relation.test.tsx`
|
|
- `apps/web/components/task/changes-panel-data.tsx`
|
|
- `apps/web/components/task/changes-panel-remote.test.ts`
|
|
- `apps/web/e2e/tests/pr/pr-switcher-changes.spec.ts`
|
|
|
|
If the existing mock API cannot hold the provider response pending, these test-support files can also
|
|
change:
|
|
|
|
- `apps/web/e2e/helpers/api-client.ts`
|
|
- The corresponding backend mock GitHub handler and test
|
|
|
|
## Dependencies
|
|
|
|
None.
|
|
|
|
## Risks
|
|
|
|
- A combined authoritative/display state can accidentally make stale provider evidence actionable.
|
|
- Cache pruning and rapid task switches can drop retained evidence or expose it under the wrong identity.
|
|
- The existing E2E mock may need a narrow deterministic latency control to observe the pending interval.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- `REQ-TASKS-REMOTE-CONTRIBUTION-TASKS-001`, especially
|
|
`AC-TASKS-REMOTE-CONTRIBUTION-TASKS-001.4` and `.7`.
|
|
- `docs/specs/tasks/system-design/remote-contribution-tasks.md` provider-history and failure sections.
|
|
- `docs/decisions/2026-08-13-provider-history-changes-enrichment.md`.
|
|
- Existing stale-while-revalidate behavior in
|
|
`apps/web/hooks/domains/github/use-active-task-pr-files.ts` and its refresh-retention tests.
|
|
|
|
## Results
|
|
|
|
- Added separate display and authoritative commit lists to the provider resource.
|
|
- Retained display commits now follow the latest selected source version for each contribution identity.
|
|
A late response cannot become the retained source for a newer version.
|
|
- Pending and failed refreshes preserve pushed markers. A successful refresh replaces the retained list.
|
|
- Relation classification uses only complete current evidence. All remote actions stay disabled when
|
|
that evidence is pending or failed.
|
|
- Added focused coverage for pending, failed, successful, identity-switch, and late-response cases.
|
|
- Extended the Chromium task-switch scenario with a failed provider refresh and a pushed-marker check.
|
|
- No public docs change is needed because this correction changes no command, setting, label, or user
|
|
workflow.
|