Skip to content
This repository was archived by the owner on Apr 14, 2026. It is now read-only.

BehaviorContract.md

Latest commit

 

History

History
53 lines (40 loc) · 2.52 KB

BehaviorContract.md

File metadata and controls

53 lines (40 loc) · 2.52 KB

JunieOrchestrator Behavior Contract (Canonical)

This document is the canonical reference for what JunieOrchestrator does. If code, README, or tests disagree with this document, the code/tests/README must be changed to match THIS document.

Core safety invariant (MUST NEVER CHANGE)

JunieOrchestrator MUST NEVER operate in-place in the user’s current git repository.

“In-place” means any of the following happening to the repo you are currently standing in when you invoke the CLI:

  • creating or switching branches
  • modifying files
  • writing orchestration artifacts (confirmation.md, steps_to_complete_the_task.md, junie_output_iter_*.txt, .junie_state.json)

This is forbidden.

What the tool does (high level)

Given a natural-language task, JunieOrchestrator:

  1. Creates a dedicated task working directory under --base-dir (default: junie-tasks/).
  2. Performs a dedicated checkout into that directory (typically git clone).
  3. Creates and checks out a task branch inside the dedicated checkout.
  4. Runs the Junie + GPT review loop inside the dedicated checkout.

Repo source selection rules

JunieOrchestrator needs a clone source (repo_url). It must be determined as follows:

  1. If --repo is provided:
  • Use it as the clone source.
  1. If --repo is omitted AND the current directory is inside a git repository:
  • Auto-detect the current repo root and use it as the clone source.
  • IMPORTANT: this is still a dedicated checkout (clone/copy). No in-place operations.
  1. If --repo is omitted AND the current directory is NOT inside a git repository:
  • Prompt the user for the clone source.

Dedicated checkout rules

  • All orchestration work happens under a new folder: <base-dir>/<task-slug>/.
  • The clone happens into that folder.
  • Branch creation/checkouts happen only inside that cloned folder.

Safety rails (recommended)

Implementations SHOULD include at least one of:

  • a hard check that refuses to run if the selected work directory equals the current repo root
  • a warning if repo_url resolves to the same path as the current directory, clarifying it is used only as clone source

Acceptance tests (MUST exist)

The test suite MUST include a test verifying:

  • Running with no --repo from inside a git repo does NOT call any “in-place” setup.
  • It instead creates a work dir and clones from the detected repo.

Non-goals

  • Supporting any “in-place mode” is explicitly not a feature.
  • Convenience auto-detection exists only to avoid typing --repo, not to reuse the current working tree.