kandev/docs/plans/commit-provenance-refresh-stability/task-01-stabilize-commit-provenance.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-stabilize-commit-provenance	Stabilize commit provenance across refreshes	completed	1		plan.md	REQ-TASKS-REMOTE-CONTRIBUTION-TASKS-001	AC-TASKS-REMOTE-CONTRIBUTION-TASKS-001.4 AC-TASKS-REMOTE-CONTRIBUTION-TASKS-001.7	../../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

(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.