Carlos Florêncio
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
---
|
|
id: "04-document-required-refresh"
|
|
title: "Document required repository refresh"
|
|
status: done
|
|
wave: 4
|
|
depends_on:
|
|
- "03-project-refresh-launch-failures"
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001
|
|
acceptance_criteria:
|
|
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.1
|
|
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.2
|
|
- AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3
|
|
system_design:
|
|
- ../../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
|
|
|
|
```bash
|
|
# 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](../../public/executors.md) with workspace automation versus
|
|
task Git credential boundaries, executor-local SSH requirements, host GitHub
|
|
SSH configuration, and restart guidance.
|
|
- Updated [Git Operations](../../public/git-operations.md) 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`.
|