Make protected-file policy configurable and consistent for migration branches

[mrjf]

Background

During the githubnext/apm Python-to-Go migration, Crane repeatedly needed to touch files that are commonly protected: go.mod, go.sum, workflow files, and other project configuration. With protected files set to fallback-to-issue, Crane could describe work in an issue but not push the actual migration commit. That caused false progress and stalled PR updates.

APM locally changed the Crane workflow so create-pull-request uses protected-files: allowed. The upstream lesson is broader: code migration frequently requires manifest, lockfile, or workflow changes, so protected-file behavior must be explicit, configurable, and consistent across both creating the PR and pushing later iteration commits.

Problem

The default upstream Crane workflow has create-pull-request protected files set to fallback-to-issue, while push-to-pull-request-branch also has its own protected-file behavior from safe outputs. This can create surprising behavior:

• First accepted iteration can fail to create a useful PR if protected files are touched.
• Later iterations can fail to push to the existing migration branch.
• Crane may write fallback issues that look like progress but do not update the PR branch.
• Migrations involving Go, Node, Python, Java, or Rust often need dependency manifest and lockfile edits.

For a migration tool, touching manifest and lock files is often not exceptional. It is part of the migration.

Proposed implementation

Make protected-file policy an explicit Crane installation or workflow configuration choice.

Possible design:

1. Add an installer prompt in install.md:

   • Strict: protected files fall back to issue for maximum safety.
   • Migration-friendly: protected files are allowed on Crane migration branches.
   • Custom: user provides an allowlist or policy.

2. Apply the selected policy consistently to both:

   • create-pull-request
   • push-to-pull-request-branch

3. Document when to use each mode:

   • Use strict for repositories where agents must never touch manifests or workflow files without human intervention.
   • Use migration-friendly when the migration target requires dependency, lockfile, build, or workflow updates.

4. If a protected-file fallback still happens, Crane should treat it as blocked or incomplete, not as an accepted migration iteration. It should tell the maintainer what policy or allowlist needs to change.

5. Consider per-migration override support in migration frontmatter, for example:

protected-files-policy: allowed

or

protected-files-policy: fallback-to-issue

Suggested test coverage

• Prompt or installer tests that verify the protected-file policy is described.
• Workflow prompt test that verifies the policy applies to both PR creation and PR branch pushes.
• If implemented in installer code, test that the selected policy is written into workflows/crane.md before gh aw compile.

Acceptance criteria

• A repository owner can choose strict or migration-friendly protected-file behavior during installation.
• The chosen behavior is applied consistently for initial PR creation and later PR updates.
• Crane does not mark protected-file fallback output as a successful accepted iteration unless a commit actually reached the migration branch.
• Documentation explains why migrations may need to touch manifest and lock files.

Provenance

This came from githubnext/apm, where the Python-to-Go migration needed dependency and workflow changes and protected-file fallback prevented Crane from generating new PR commits.