Release 0.5.0

.archon/commands/defaults/archon-create-pr.md

@@ -84,8 +84,17 @@ git status --porcelain
 ```
 
 **If dirty**:
-1. Stage changes: `git add -A`
-2. Commit: `git commit -m "Final changes before PR"`
+
+1. Stage **only** the source files that are part of this change — never `git add -A`, `git add .`, or `git add -u`. List them by name:
+   ```bash
+   git add path/to/file1 path/to/file2 ...
+   git status --porcelain  # verify nothing else is staged
+   ```
+2. **Never stage** scratch / review / PR-body artifacts, even if they show up in `git status`:
+   - `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`
+   - `review/`, `*-report.md` at the repo root
+   - Anything under `$ARTIFACTS_DIR`
+3. Commit: `git commit -m "Final changes before PR"`
 
 ### 2.2 Push Branch
 

.archon/commands/defaults/archon-finalize-pr.md

@@ -71,13 +71,20 @@ git status --porcelain
 
 ### 2.2 Stage Changes
 
-Stage all implementation changes:
+Stage **only** the implementation files you actually edited — never `git add -A`, `git add .`, or `git add -u`. List them by name:
 
 ```bash
-git add -A
+git add path/to/file1 path/to/file2 ...
+git status --porcelain  # verify nothing else is staged
 ```
 
-**Review staged files** - ensure no sensitive files (.env, credentials) are included:
+**Never stage** scratch / review / PR-body artifacts, even if they appear in `git status`:
+
+- `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`
+- `review/`, `*-report.md` at the repo root
+- Anything under `$ARTIFACTS_DIR`
+
+**Review staged files** — ensure no sensitive files (`.env`, credentials) and no scratch artifacts are included:
 
 ```bash
 git diff --cached --name-only

.archon/commands/defaults/archon-fix-issue.md

@@ -131,28 +131,30 @@ git status
 
 ### 3.2 Decision Tree
 
-```
+```text
 ┌─ IN WORKTREE?
-│  └─ YES → Use it (assume it's for this work)
-│           Log: "Using worktree at {path}"
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree at {path} on branch {branch}"
 │
-├─ ON MAIN/MASTER?
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
 │  └─ Q: Working directory clean?
 │     ├─ YES → Create branch: fix/issue-{number}-{slug}
 │     │        git checkout -b fix/issue-{number}-{slug}
-│     └─ NO  → Warn user:
-│              "Working directory has uncommitted changes.
-│               Please commit or stash before proceeding."
-│              STOP
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Uncommitted changes on $BASE_BRANCH.
+│              Please commit or stash before proceeding."
 │
-├─ ON FEATURE/FIX BRANCH?
-│  └─ Use it (assume it's for this work)
+├─ ON OTHER BRANCH?
+│  └─ Use it AS-IS (assume it was set up for this work).
+│     Do NOT switch to another branch (e.g., one shown by `git branch` but
+│     not currently checked out).
 │     If branch name doesn't contain issue number:
 │       Warn: "Branch '{name}' may not be for issue #{number}"
 │
 └─ DIRTY STATE?
-   └─ Warn and suggest: git stash or git commit
-      STOP
+   └─ STOP: "Uncommitted changes. Please commit or stash first."
 ```
 
 ### 3.3 Ensure Up-to-Date
@@ -292,11 +294,19 @@ Execute any manual verification steps from the artifact.
 
 ### 7.1 Stage Changes
 
+Stage **only** the files you actually edited — never `git add -A`, `git add .`, or `git add -u`. List them by name:
+
 ```bash
-git add -A
-git status  # Review what's being committed
+git add path/to/file1 path/to/file2 ...
+git status --porcelain  # verify nothing scratch/review/PR-body is staged
 ```
 
+**Never stage**:
+
+- `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`
+- `review/`, `*-report.md` at the repo root
+- Anything under `$ARTIFACTS_DIR`
+
 ### 7.2 Write Commit Message
 
 **Format:**

.archon/commands/defaults/archon-implement-issue.md

@@ -132,28 +132,30 @@ git status
 
 ### 3.2 Decision Tree
 
-```
+```text
 ┌─ IN WORKTREE?
-│  └─ YES → Use it (assume it's for this work)
-│           Log: "Using worktree at {path}"
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree at {path} on branch {branch}"
 │
-├─ ON MAIN/MASTER?
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
 │  └─ Q: Working directory clean?
 │     ├─ YES → Create branch: fix/issue-{number}-{slug}
 │     │        git checkout -b fix/issue-{number}-{slug}
-│     └─ NO  → Warn user:
-│              "Working directory has uncommitted changes.
-│               Please commit or stash before proceeding."
-│              STOP
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Uncommitted changes on $BASE_BRANCH.
+│              Please commit or stash before proceeding."
 │
-├─ ON FEATURE/FIX BRANCH?
-│  └─ Use it (assume it's for this work)
+├─ ON OTHER BRANCH?
+│  └─ Use it AS-IS (assume it was set up for this work).
+│     Do NOT switch to another branch (e.g., one shown by `git branch` but
+│     not currently checked out).
 │     If branch name doesn't contain issue number:
 │       Warn: "Branch '{name}' may not be for issue #{number}"
 │
 └─ DIRTY STATE?
-   └─ Warn and suggest: git stash or git commit
-      STOP
+   └─ STOP: "Uncommitted changes. Please commit or stash first."
 ```
 
 ### 3.3 Ensure Up-to-Date
@@ -293,11 +295,19 @@ Execute any manual verification steps from the artifact.
 
 ### 7.1 Stage Changes
 
+Stage **only** the files you actually edited — never `git add -A`, `git add .`, or `git add -u`. List them by name:
+
 ```bash
-git add -A
-git status  # Review what's being committed
+git add path/to/file1 path/to/file2 ...
+git status --porcelain  # verify nothing scratch/review/PR-body is staged
 ```
 
+**Never stage**:
+
+- `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`
+- `review/`, `*-report.md` at the repo root
+- Anything under `$ARTIFACTS_DIR`
+
 ### 7.2 Write Commit Message
 
 **Format:**
@@ -365,7 +375,8 @@ Write the prepared body to `$ARTIFACTS_DIR/pr-body.md`, then:
 
 ```bash
 gh pr create --title "Fix: {title} (#{number})" \
-  --body-file $ARTIFACTS_DIR/pr-body.md
+  --body-file $ARTIFACTS_DIR/pr-body.md \
+  --base $BASE_BRANCH
 ```
 
 ### 8.3 Get PR Number

.archon/commands/defaults/archon-implement-review-fixes.md

@@ -175,11 +175,19 @@ Must succeed.
 
 ### 4.1 Stage Changes
 
+Stage **only** the files you actually edited while applying review fixes — never `git add -A`, `git add .`, or `git add -u`. List them by name:
+
 ```bash
-git add -A
-git status
+git add path/to/file1 path/to/file2 ...
+git status --porcelain  # verify nothing scratch/review/PR-body is staged
 ```
 
+**Never stage**:
+
+- `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`
+- `review/`, `*-report.md` at the repo root
+- Anything under `$ARTIFACTS_DIR` (review artifacts live here, not in the worktree)
+
 ### 4.2 Commit
 
 ```bash

.archon/commands/defaults/archon-implement.md

@@ -93,19 +93,40 @@ Provide a valid plan path or GitHub issue containing the plan.
 ### 2.1 Check Current State
 
 ```bash
+# What branch are we on?
 git branch --show-current
-git status --porcelain
+
+# Are we in a worktree?
+git rev-parse --show-toplevel
 git worktree list
+
+# Is working directory clean?
+git status --porcelain
 ```
 
 ### 2.2 Branch Decision
 
-| Current State     | Action                                               |
-| ----------------- | ---------------------------------------------------- |
-| In worktree       | Use it (log: "Using worktree")                       |
-| On base branch, clean    | Create branch: `git checkout -b feature/{plan-slug}` |
-| On base branch, dirty    | STOP: "Stash or commit changes first"                |
-| On feature branch | Use it (log: "Using existing branch")                |
+```text
+┌─ IN WORKTREE?
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree at {path} on branch {branch}"
+│
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
+│  └─ Q: Working directory clean?
+│     ├─ YES → Create branch: git checkout -b feature/{plan-slug}
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Stash or commit changes first"
+│
+├─ ON OTHER BRANCH?
+│  └─ Use it AS-IS. Do NOT switch to another branch (e.g., one shown by
+│     `git branch` but not currently checked out).
+│     Log: "Using existing branch {name}"
+│
+└─ DIRTY STATE?
+   └─ STOP: "Stash or commit changes first"
+```
 
 ### 2.3 Sync with Remote
 
@@ -116,7 +137,7 @@ git pull --rebase origin $BASE_BRANCH 2>/dev/null || true
 
 **PHASE_2_CHECKPOINT:**
 
-- [ ] On correct branch (not base branch with uncommitted work)
+- [ ] On correct branch (not $BASE_BRANCH with uncommitted work)
 - [ ] Working directory ready
 - [ ] Up to date with remote
 

.archon/commands/defaults/archon-plan-setup.md

@@ -112,13 +112,26 @@ gh repo view --json nameWithOwner -q .nameWithOwner
 
 ### 2.3 Branch Decision
 
-| Current State | Action |
-|---------------|--------|
-| Already on correct feature branch | Use it, log "Using existing branch: {name}" |
-| On base branch, clean working directory | Create and checkout: `git checkout -b {branch-name}` |
-| On base branch, dirty working directory | STOP with error: "Uncommitted changes on base branch. Stash or commit first." |
-| On different feature branch | STOP with error: "On branch {X}, expected {Y}. Switch branches or adjust plan." |
-| In a worktree | Use the worktree's branch, log "Using worktree branch: {name}" |
+Evaluate in order (first matching case wins):
+
+```text
+┌─ IN WORKTREE?
+│  └─ YES → Use current branch AS-IS. Do NOT switch branches. Do NOT create
+│           new branches. The isolation system has already set up the correct
+│           branch; any deviation operates on the wrong code.
+│           Log: "Using worktree branch: {name}"
+│
+├─ ON $BASE_BRANCH? (main, master, or configured base branch)
+│  └─ Q: Working directory clean?
+│     ├─ YES → Create and checkout: `git checkout -b {branch-name}`
+│     │        (only applies outside a worktree — e.g., manual CLI usage)
+│     └─ NO  → STOP: "Uncommitted changes on $BASE_BRANCH. Stash or commit first."
+│
+└─ ON OTHER BRANCH?
+   └─ Q: Does it match the expected branch for this plan?
+      ├─ YES → Use it, log "Using existing branch: {name}"
+      └─ NO  → STOP: "On branch {X}, expected {Y}. Switch branches or adjust plan."
+```
 
 ### 2.4 Sync with Remote
 

.archon/commands/defaults/archon-simplify-changes.md

@@ -61,16 +61,29 @@ For each simplification:
 2. Run `bun run type-check` — if it fails, revert that change
 3. Run `bun run lint` — if it fails, fix or revert
 
+**Track every path you edit.** You will need this list in Phase 3 to stage only the files you touched.
+
 ### Phase 3: VALIDATE & COMMIT
 
 1. Run full validation: `bun run type-check && bun run lint`
-2. If changes were made:
+2. If simplifications were applied, stage **only** the files you edited in Phase 2 — never `git add -A`, `git add .`, or `git add -u`:
+   ```bash
+   # Stage by name, using the list you tracked in Phase 2
+   git add path/to/file1.ts path/to/file2.ts
+   # Verify nothing else snuck in
+   git status --porcelain
+   ```
+3. **Never stage** report, scratch, or PR-body artifacts, even if they show up as untracked or modified in the worktree:
+   - Anything under `$ARTIFACTS_DIR` (the artifacts directory normally lives outside the worktree, but copies/symlinks may exist)
+   - `review/`, `simplify-report.md`, `*-report.md` at the repo root
+   - `.pr-body.md`, `pr-body.md`, `*.scratch.md`, `*.tmp.md`
+   - If `git status --porcelain` shows files you don't recognize as part of your simplifications, leave them unstaged
+4. Commit and push only the staged source edits:
    ```bash
-   git add -A
    git commit -m "simplify: reduce complexity in changed files"
    git push
    ```
-3. If no simplifications found, skip commit
+5. If no simplifications were applied, skip the commit entirely
 
 ### Phase 4: REPORT
 

.archon/commands/e2e-echo-command.md

@@ -0,0 +1,13 @@
+---
+description: E2E test command — echoes back the user message
+argument-hint: <any text>
+---
+
+# E2E Echo Command
+
+You are a simple echo agent for testing. Your ONLY job is to repeat back the user's message.
+
+User message: $ARGUMENTS
+
+Respond with EXACTLY this format and nothing else:
+command-echo: <the user message above>

.archon/scripts/echo-args.js

@@ -0,0 +1,3 @@
+// Simple script node test — echoes input as JSON
+const input = process.argv[2] ?? 'no-input';
+console.log(JSON.stringify({ echoed: input, timestamp: new Date().toISOString() }));

.archon/scripts/echo-py.py

@@ -0,0 +1,7 @@
+"""Simple script node test — echoes input as JSON (uv/Python runtime)."""
+import json
+import sys
+from datetime import datetime, timezone
+
+input_val = sys.argv[1] if len(sys.argv) > 1 else "no-input"
+print(json.dumps({"echoed": input_val, "timestamp": datetime.now(timezone.utc).isoformat()}))