[codeforester]

Summary

• move a linked Project item to In Progress before the issue-start handoff
• preserve the handoff with a visible warning when the issue has no linked Project, with explicit --no-project, --project, --project-owner, and --allow-cross-repo controls
• fail closed when an available Project transition or exact readback fails
• avoid Project field mutations when the requested values are already current
• document and test the lifecycle transition, fallback behavior, and shell completions

Issue

Closes #2616

Validation

• 1,825 Python tests passed
• 1,058 shell tests passed
• targeted GitHub command, Project metadata, and completion tests passed
• git diff --check and ShellCheck passed

Docs Impact

Updated the command reference, GitHub workflow guide, GitHub-command README, and completions for the verified lifecycle transition and explicit Project-independent handoff behavior.

Review follow-up

Addresses the review feedback on no-linked-Project compatibility, shared warning handling, and no-op Project mutations. This PR is intentionally left open for review.

[codeforester]

Automated review findings

1. Confirmed regression — issue start now hard-fails for repos without a linked Project (cli/bash/commands/basectl/subcommands/gh.sh, base_gh_set_issue_in_progress ~line 911, called from gh_issue.sh ~line 491): the new Project-status sync hardcodes the repo-derived Project title/owner with no --allow-cross-repo/--no-project escape hatch, and aborts the whole command (no branch/worktree output) if the Project call fails. Verified: basectl gh issue start <n> -R upstream/base (a supported, tested repo-flag pattern per the existing bats test "basectl gh issue start honors an explicit upstream repository") will hit project_issue_fields_command.py's ProjectError/ProjectUsageError ("Project '...' is not linked to repository '...' ... pass --allow-cross-repo intentionally") for any repo whose Project isn't named/linked exactly as expected, or that has no Project board at all - and issue start now exits non-zero before ever printing the branch/worktree handoff that AGENTS.md's pre-edit workflow gate depends on. Previously issue start had no Project dependency at all. Note: the PR's own new test mock always exits 0 regardless of repo, so this real enforcement path isn't actually exercised by the added test coverage.

2. Duplicated warn-loop logic (gh.sh): base_gh_apply_project_issue_fields (lines ~900-904) and the new base_gh_set_issue_in_progress block contain the identical "split stderr into lines, warn each one" loop verbatim. A shared helper (e.g. base_gh_log_warn_lines "$output") would replace both with no behavior change.

3. Unconditional mutation on every call (~line 924): the Status=In Progress GraphQL mutation runs on every issue start invocation with no prior-state check, including when re-running on an issue that's already In Progress (e.g. after recreating a worktree) - a redundant write every time instead of a no-op when the field is already correct.

Finding 1 is the one I'd fix before merge - it changes issue start from Project-independent to Project-required, which is a real behavior change not covered by the new tests.

Posted via Claude Code

[codeforester]

Addressed in follow-up commit 4f04abf0.

• issue start now preserves the worktree handoff when the issue has no linked Project, with the warning surfaced and Project status: not updated; --no-project is available for an intentional Project-independent start. --project, --project-owner, and --allow-cross-repo cover explicit alternate-Project cases. Other Project/API failures remain fail-closed.
• Shared warning-line handling is now used by both Project update paths.
• Project field updates now read current values and skip mutations when the requested values are already current.
• Added regression coverage, docs, and completion updates.

Validation: full gate passed with 1,825 Python and 1,058 shell tests; targeted GitHub command, Project metadata, and completion tests also passed. Hosted checks are rerunning on the new head.