fix(claude-swe-agent): add scope-discipline guardrails so the agent stops instead of over-reaching (#185)

[k5s-bot]

Closes #185.

Problem

The Claude code SWE agent (apps/claude-code-swe-agent) runs headless as a one-shot Kubernetes Job — there is no interactive human in the loop while it works. But the fixed, trusted policy in buildPrompt() (the text that wraps every task) only covered the git workflow and the destructive-command bans. Nothing told the agent to:

• stay within the scope of the task it was handed, or
• stop when it hits a wall (missing repo access/permissions, an ambiguous or wrong-looking instruction, a repeatedly-failing command).

So when it was unsure or something went wrong, it tended to keep going — expanding the task, or improvising a workaround (substituting or creating a repository, guessing at intent) — instead of pausing for a human. That's the "too eager / goes off the rails" behavior reported in the issue.

The triage promptTemplate already carries some of this language, but only for the triage flow. Putting it in buildPrompt() makes it apply to every Claude agent invocation, which is where the general behavior lives.

Change

Three scope-discipline rules added to the ## Rules (must follow) block in buildPrompt():

1. Stay in scope — do the task asked and no more; surface extra ideas in the final summary instead of doing them.
2. Stop, don't improvise, when blocked or unsure — missing access, ambiguous/wrong instructions, or persistently-failing commands mean the turn is done. Explicitly: do not substitute a different repository, create a repo the task didn't call for, broaden the task, or guess at intent to keep making progress.
3. Surface the blocker — explain the blocker/question plainly in the final reply (and in an issue/PR comment where one exists) so a human can decide and re-trigger. A halted turn with a clear question is a successful outcome, not a failure.

The human-in-the-loop mechanism in this headless, one-turn model is exactly this: stop, report clearly, and let a maintainer re-trigger (e.g. via the existing label workflow) rather than having the agent barrel through on its own guess.

Tests

claude.ts previously had no test module. Added claude.test.ts covering the existing buildClaudeSettings/buildPrompt behavior (continuation context, instruction embedding) plus the new guardrails, asserting they are present on both fresh and continuation turns.

• npm test -w claude-code-swe-agent → 7 files / 62 tests pass (12 in the new claude.test.ts).
• npm run typecheck -w claude-code-swe-agent → clean (after npm run build:libs).

Scope note

Deliberately kept to the Claude agent that the issue names. The sibling opencode-swe-agent has a parallel buildPrompt(); mirroring these rules there is a reasonable follow-up but was intentionally left out to avoid broadening this change beyond the issue.

---

Maintainer: apply the ai-review label to this PR to request an automated code review, or the ai-triage label to have the review feedback addressed and the branch brought back in sync with its base. (The automation can't apply either label to its own PR, so a human needs to.)