Skip to content

kickoff entrypoint: crosslink init --force rewrites .crosslink/hook-config.json on every container start #583

@maxine-at-forecast

Description

@maxine-at-forecast

The container entrypoint at `crosslink/resources/container/entrypoint.sh` runs:

```bash
gosu agent bash -c "cd '$WORKSPACE' && crosslink init --force"
```

on every container start. `init --force` apparently re-templates `.crosslink/hook-config.json` to the latest schema, including reordering / nesting fields under `agent_overrides`, even when the existing config is already valid for the current crosslink binary.

This is a problem because:

  1. The diff lands in agent-produced PRs. Every kickoff feature branch ends up with `.crosslink/hook-config.json` modified, even when the agent didn't intend to touch project-shared config. Reviewers have to manually `git restore .crosslink/hook-config.json` before merging — easy to miss.
  2. Project-tuned settings risk being overwritten. The on-disk `hook-config.json` may have been edited by the project owner to set `tracking_mode`, `comment_discipline`, custom `allowed_bash_prefixes`, etc. `init --force` re-templating drops those if the local schema doesn't carry them through.

Concrete observations

In forecast-bio/santana M0 and both M1 (Python + Rust) kickoff runs, the agent's worktree showed this diff vs the incoming `hook-config.json`:

  • Top-level keys (`tracking_mode`, `intervention_tracking`, `comment_discipline`, `signing_enforcement`, `kickoff_verification`) moved into an `agent_overrides` block.
  • New fields (`agent_lint_commands`, `agent_test_commands`, `blocked_git_commands`, `gated_git_commands`) added inside `agent_overrides`.
  • The diff was ~50 lines / file. Not subtle.

We worked around by running `git restore .crosslink/hook-config.json` in the worktree before `git add` for every PR. Three PRs so far (#1 M0, #3 M1-py, #4 M1-rs).

Suggested fix

Three options, in increasing-effort order:

  1. Don't run `init --force` if a valid `hook-config.json` already exists. The entrypoint should detect existing config and skip the re-template. (`init --force` is the expensive option; `init` without `--force` already short-circuits on existing.)
  2. Make `init --force` schema-preserving: when migrating to a new schema, deeply merge the existing values rather than templating from scratch.
  3. Document the behavior in the entrypoint and in agent-prompt-side guidance, plus add a kickoff-report validation that flags `.crosslink/hook-config.json` as a not-expected modified file in the agent's diff.

Cross-refs

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions