docs: claude-cloud - Record spec 018 clarifications and convergence fixes #3727

Documentation Update Summary

Spec 018 (Standardised Claude Code Cloud Environment) no longer matched the code or the decisions made after #3524 merged. This issue covers:

• recording the seven clarifications agreed on 2026-10-01 (five) and 2026-10-02 (two) in spec.md
• running /speckit-converge to add the remaining work to tasks.md (convergence phases 7–11, T052–T065)
• making the convergence fixes that don't need edits to the guard's own files

Linked Stories/Tasks/PRs/Epic

• Related pull request: docs: claude-cloud - Record spec 018 clarifications and convergence fixes #3726 (delivers this issue; closes it on merge)
• Related pull request: chore: shared Claude Code cloud environment and branch-name guard #3524 (merged; introduced the cloud environment and the branch guard)
• Related pull request: feat: branch-cleanup - Add report-only branch audit CLI #3358 (spec 009 branch cleanup; FR-020 requires its claude/* auto-approval to stay off)
• Related issue: security: branch-guard - six residual gaps in the GraphQL and REST branch-write checks #3691 (the six guard gaps that the clarifications now treat as defects)
• Related issue: Label Prefix Governance Enforcement — Audit Results & Remediation Plan #1592 (label and branch governance enforcement)

Milestones & Timeline

• Milestone: v1.1
• No fixed deadline. This should merge before feat: branch-cleanup - Add report-only branch audit CLI #3358, so spec 018's FR-020 deferral is on develop first.

What documentation is needed?

• .github/specs/018-claude-cloud-environment/spec.md:
  • Session 2026-10-01 with five answers and the requirement updates that follow:
    • FR-012a: when the guard can't start, git and GitHub writes are refused and every other command only gets a warning.
    • FR-008: the gaps in security: branch-guard - six residual gaps in the GraphQL and REST branch-write checks #3691 are defects.
    • FR-020: the auto-deletion deferral applies to spec 009 as well.
    • FR-006: deleting main or the base branch is always refused.
    • FR-009: direct writes to main are refused on every LightSpeed repo.
  • Session 2026-10-02 with two answers:
    • Hotfixes use hotfix/{scope}-{title}; hotfix/vX.Y.Z is refused.
    • While auto-deletion is deferred, a maintainer may promote an empty, merged claude/* branch with no open PR from DISCUSS to DELETE, removed through spec 009's draft-PR approval (FR-020, FR-021, SC-002).
• Design documents: plan.md, research.md (R15–R17), data-model.md, contracts/branch-cleanup.md, contracts/hooks.md and quickstart.md (steps 1 and 5) aligned with the decisions above.
• .github/specs/018-claude-cloud-environment/tasks.md: convergence phases 7–11 (T052–T065), including regenerated tasks T061–T063, with correct ticks (65 tasks, 46 done).
• docs/CLAUDE_CLOUD_ENVIRONMENT.md: says auto-deletion of empty claude/* branches is deferred under FR-020, describes the DISCUSS promotion route and hotfix naming.
• Supporting changes:
  • a session-start timing test for SC-005 (T050)
  • setup-node-install.test.js added to the Claude Guard Tests workflow (T057)
  • stale "spec 016" comments renamed to "spec 018" outside the guard (T058)
  • docs contract test assertion updated for the new cleanup contract wording

Why is this documentation important?

The spec is the contract the branch guard and its contract tests are built against. A stale spec makes the next /speckit-implement pass work towards the wrong behaviour. The guide was also telling Owners that empty claude/* branches are deleted automatically, which is no longer true.

Acceptance Criteria

• Documentation is clear, accurate, and up-to-date
• Includes code examples/screenshots if applicable
• Documentation is accessible and easy to find
• Changelog entry prepared for PR if user-facing update
• PR uses correct branch prefix (docs/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards

Additional Context

These tasks are still open and are out of scope for #3726:

• Need edits to .claude/hooks/**: T045, T049, T052, T054, T055, and the guard halves of T056 and T058. The guard refuses those edits while enforcement is on, so they need a session started with LS_ENFORCE_BRANCH_NAMES=0, or a person.
• Waiting on feat: branch-cleanup - Add report-only branch audit CLI #3358 merging: T035 and T063, and ticking T053 and T060.
• Owner actions: T028–T030, T042, T043 and T048.

Definition of Ready (DoR)

• Documentation need is clear and well-defined
• Related docs/issues or files linked
• Acceptance criteria listed
• Estimate added if relevant
• Milestone/release assigned (if applicable)

Definition of Done (DoD)

• Documentation meets org standards and guidelines
• Changelog entry prepared for PR (CHANGELOG.md)
• Documentation reviewed for clarity and accessibility
• Screenshots/code examples included if relevant
• PR uses correct branch prefix (docs/)
• PR uses the correct PR template based on type:docs PR label or linked issue type or linked issue type:docs label
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge,
• The related epic should not be closed, instead updated with a comment to reflect the closed issue

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xwegb5oT1vPW6J8UJyNPqT