kandev/docs/plans/worktree-refresh-fail-closed/task-04-document-required-refresh.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
04-document-required-refresh	Document required repository refresh	done	4	03-project-refresh-launch-failures	plan.md	REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001	AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.1 AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.2 AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3	../../specs/workspaces/system-design/worktree-base-refresh.md

Task 04: Document Required Repository Refresh

Summary

Document the SSH configuration boundary, required-refresh failure behavior, offline opt-out, and safe retry procedure in the public Git guidance.

In scope

• Update executor documentation to state where host and remote executors read Git and SSH credentials.
• Update Git operations documentation to explain that pull-before-worktree stops launch when refresh fails.
• Document gh config set git_protocol ssh --host github.com for a host that uses executor-inherited GitHub access.
• State that Kandev must restart after host GitHub protocol changes so managed checkout origins are reconciled before the next task launch.
• Explain how to disable pull-before-worktree for an intentional offline local workflow.
• Add credential-safe troubleshooting steps for authentication and network errors.

Out of scope

• New settings, screenshots, or UI copy.
• Provider-specific SSH installation guides beyond the existing supported configuration surface.
• Documentation for setup-script failure policy.

Acceptance

• Public docs distinguish workspace automation identity from task Git credential policy and selected Git transport.
• Public docs state that a required refresh failure stops launch and does not use a stale local fallback.
• Commands, internal links, and headings pass the public documentation validators.

Verification

# From the repository root:
rtk node --test scripts/validate-public-docs.test.mjs
rtk node scripts/validate-public-docs.mjs
rtk python3 scripts/lint-spec-files.py --all
rtk git diff --check

Files likely touched

• docs/public/executors.md
• docs/public/git-operations.md
• docs/plans/worktree-refresh-fail-closed/plan.md
• docs/plans/worktree-refresh-fail-closed/task-04-document-required-refresh.md

Dependencies

• Task 03 verifies the exact launch and retry behavior that the public docs describe.

Risks

• Documentation can imply that a named GitHub CLI automation connection makes SSH available to every executor. State the separate task policy and runtime boundary explicitly.
• Remote executors need their own SSH key and known-host configuration. Do not describe host configuration as portable to Docker or SSH executors.

Parallelism

sequential

Inputs

• Verified behavior from Tasks 01 through 03.
• ADR-2026-07-27-task-git-credential-policy.
• docs/public/executors.md and docs/public/git-operations.md.

Results

• Updated Executors with workspace automation versus task Git credential boundaries, executor-local SSH requirements, host GitHub SSH configuration, and restart guidance.
• Updated Git Operations with required-refresh failure behavior, the offline opt-out, and credential-safe troubleshooting.
• Verified with public-doc unit and live validators, specification lint, and git diff --check.