fix(commands): teach archon-implement-tasks to gitignore workflow telemetry

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

@@ -65,12 +65,37 @@ echo "unknown"
 
 Store the runner for validation commands.
 
+### 1.5 Repository Hygiene — Workflow Telemetry
+
+The Archon harness writes per-run telemetry into the target repo at:
+
+- `.archon/artifacts/` — per-run plan, implementation, and validation artifacts
+- `.archon/logs/` — per-run JSONL execution logs
+- `.archon/state/` — cross-run workflow state
+
+Per the project conventions in `CLAUDE.md`, **these paths are local-only and must never be committed**.
+
+**MANDATORY rule** for any task in this run that creates or modifies `.gitignore`:
+
+The `.gitignore` MUST include these patterns (add them if missing, leave them in place if already present):
+
+```
+.archon/artifacts/
+.archon/logs/
+.archon/state/
+```
+
+If the plan calls for scaffolding a new `.gitignore` from scratch, include these patterns alongside the language- or framework-specific entries.
+
+When staging changes (`git add`), never stage paths under `.archon/artifacts/`, `.archon/logs/`, or `.archon/state/`. If they appear in `git status` output, the `.gitignore` is missing or incomplete — fix the `.gitignore` first, then stage.
+
 **PHASE_1_CHECKPOINT:**
 
 - [ ] Plan context loaded
 - [ ] Confirmation status verified
 - [ ] Original plan loaded
 - [ ] Package manager identified
+- [ ] Repository hygiene rules acknowledged (`.archon/artifacts/`, `.archon/logs/`, `.archon/state/` will be gitignored)
 
 ---
 

.archon/workflows/defaults/archon-adversarial-dev.yaml

@@ -117,7 +117,7 @@ nodes:
   - id: adversarial-sprint
     depends_on: [init-workspace]
     idle_timeout: 600000
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     loop:
       prompt: |
         # Adversarial Development — Sprint Loop

.archon/workflows/defaults/archon-feature-development.yaml

@@ -8,7 +8,7 @@ description: |
 nodes:
   - id: implement
     command: archon-implement
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   - id: create-pr
     command: archon-create-pr

.archon/workflows/defaults/archon-fix-github-issue.yaml

@@ -133,7 +133,7 @@ nodes:
     command: archon-fix-issue
     depends_on: [bridge-artifacts]
     context: fresh
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   # ═══════════════════════════════════════════════════════════════
   # PHASE 5: VALIDATE

.archon/workflows/defaults/archon-idea-to-pr.yaml

@@ -52,7 +52,7 @@ nodes:
     command: archon-implement-tasks
     depends_on: [confirm-plan]
     context: fresh
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   # ═══════════════════════════════════════════════════════════════════
   # PHASE 4: VALIDATE

.archon/workflows/defaults/archon-piv-loop.yaml

@@ -198,14 +198,10 @@ nodes:
       3. **Read example test files** — understand testing patterns
       4. **Check for any recent changes** — `git log --oneline -10`
 
-      ## Step 2: Determine Plan Location
+      ## Step 2: Plan File Location
 
-      Generate a kebab-case slug from the feature name.
-      Save to `.claude/archon/plans/{slug}.plan.md`.
-
-      ```bash
-      mkdir -p .claude/archon/plans
-      ```
+      Save the plan to `$ARTIFACTS_DIR/plan.md`.
+      The directory already exists (pre-created by the workflow executor).
 
       ## Step 3: Write the Plan
 
@@ -282,7 +278,7 @@ nodes:
       ```
       ## Plan Created
 
-      **File**: `.claude/archon/plans/{slug}.plan.md`
+      **File**: `$ARTIFACTS_DIR/plan.md`
       **Tasks**: {count}
       **Files to change**: {count}
 
@@ -310,13 +306,9 @@ nodes:
 
         ---
 
-        ## Step 1: Find and Read the Plan
+        ## Step 1: Read the Plan
 
-        ```bash
-        ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1
-        ```
-
-        Read the entire plan file. Also read CLAUDE.md for conventions.
+        Read `$ARTIFACTS_DIR/plan.md` and CLAUDE.md for conventions.
 
         ## Step 2: Process Feedback
 
@@ -375,10 +367,10 @@ nodes:
     bash: |
       set -e
 
-      PLAN_FILE=$(ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1)
+      PLAN_FILE="$ARTIFACTS_DIR/plan.md"
 
-      if [ -z "$PLAN_FILE" ]; then
-        echo "ERROR: No plan file found in .claude/archon/plans/"
+      if [ ! -f "$PLAN_FILE" ]; then
+        echo "ERROR: No plan file found at $ARTIFACTS_DIR/plan.md"
         exit 1
       fi
 
@@ -403,8 +395,12 @@ nodes:
       echo ""
       echo "=== PLAN_END ==="
 
-      TASK_COUNT=$(grep -c "^### Task [0-9]" "$PLAN_FILE" || true)
-      echo "TASK_COUNT=${TASK_COUNT:-0}"
+      TASK_COUNT=$(grep -c "^### Task [0-9]" "$PLAN_FILE" 2>/dev/null || echo "0")
+      if [ "$TASK_COUNT" -eq 0 ]; then
+        echo "ERROR: No '### Task N:' sections found in $PLAN_FILE. Plan may be malformed."
+        exit 1
+      fi
+      echo "TASK_COUNT=${TASK_COUNT}"
 
   # ═══════════════════════════════════════════════════════════════
   # PHASE 3b: IMPLEMENT — Task-by-Task Loop (Ralph pattern)
@@ -447,7 +443,7 @@ nodes:
         may have changed things. **You MUST re-read from disk:**
 
         1. **Read the plan file** — your implementation guide
-        2. **Read progress tracking** — check if `.claude/archon/plans/progress.txt` exists
+        2. **Read progress tracking** — check if `$ARTIFACTS_DIR/progress.txt` exists
         3. **Read CLAUDE.md** — project conventions and constraints
 
         ### 0.3 Check Git State
@@ -511,7 +507,7 @@ nodes:
         )"
         ```
 
-        Track progress in `.claude/archon/plans/progress.txt`:
+        Track progress in `$ARTIFACTS_DIR/progress.txt`:
         ```
         ## Task {N}: {title} — COMPLETED
         Date: {ISO date}
@@ -552,11 +548,9 @@ nodes:
 
       ---
 
-      ## Step 1: Find and Read the Plan
+      ## Step 1: Read the Plan
 
-      ```bash
-      ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1
-      ```
+      Read `$ARTIFACTS_DIR/plan.md` to understand the intended implementation.
 
       ## Step 2: Review All Changes
 
@@ -581,7 +575,7 @@ nodes:
 
       Fix type errors, lint warnings, missing imports, formatting. Commit any fixes:
       ```bash
-      git add -A && git commit -m "fix: address code review findings" 2>/dev/null || true
+      git add -A && git commit -m "fix: address code review findings" || true
       ```
 
       ## Step 6: Present Review
@@ -627,11 +621,7 @@ nodes:
 
         ## Step 1: Read Context
 
-        ```bash
-        ls -t .claude/archon/plans/*.plan.md 2>/dev/null | head -1
-        ```
-
-        Read the plan file and CLAUDE.md for conventions.
+        Read `$ARTIFACTS_DIR/plan.md` and CLAUDE.md for conventions.
 
         ## Step 2: Process Feedback
 
@@ -710,7 +700,7 @@ nodes:
       ## Step 1: Push Changes
 
       ```bash
-      git push -u origin HEAD 2>&1 || true
+      git push -u origin HEAD 2>&1 || echo "WARNING: Push failed — verify remote authentication and branch state before creating the PR."
       ```
 
       ## Step 2: Generate Summary
@@ -720,7 +710,7 @@ nodes:
       git diff --stat $(git merge-base HEAD $BASE_BRANCH)..HEAD
       ```
 
-      Read the plan file and progress tracking for context.
+      Read `$ARTIFACTS_DIR/plan.md` and `$ARTIFACTS_DIR/progress.txt` for context.
 
       ## Step 3: Create PR (if not already created)
 

.archon/workflows/defaults/archon-plan-to-pr.yaml

@@ -42,7 +42,7 @@ nodes:
     command: archon-implement-tasks
     depends_on: [confirm-plan]
     context: fresh
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   # ═══════════════════════════════════════════════════════════════════
   # PHASE 4: VALIDATE

.archon/workflows/defaults/archon-ralph-dag.yaml

@@ -189,7 +189,7 @@ nodes:
   - id: implement
     depends_on: [validate-prd]
     idle_timeout: 600000
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     loop:
       prompt: |
         # Ralph Agent — Autonomous Story Implementation

.archon/workflows/defaults/archon-refactor-safely.yaml

@@ -207,7 +207,7 @@ nodes:
   # ═══════════════════════════════════════════════════════════════
 
   - id: execute-refactor
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     prompt: |
       You are executing a refactoring plan with strict safety guardrails.
 

.archon/workflows/defaults/archon-workflow-builder.yaml

@@ -61,7 +61,8 @@ nodes:
       5. Whether this should be a simple DAG or include a loop node
 
       Be specific and concrete. Each proposed node should have a clear type
-      (bash, prompt, command, or loop) and a one-line description of what it does.
+      (bash, prompt, command, script, loop, or approval) and a one-line
+      description of what it does.
     model: haiku
     allowed_tools: []
     output_format:
@@ -115,7 +116,7 @@ nodes:
 
       nodes:
         - id: node-id-kebab-case
-          # Choose ONE of: prompt, bash, command, loop
+          # Choose ONE of: prompt, bash, command, script, loop, approval
 
           # --- prompt node (AI-executed) ---
           prompt: |
@@ -131,6 +132,17 @@ nodes:
           # --- command node (references a .archon/commands/ file) ---
           command: command-name
 
+          # --- script node (TypeScript via bun, or Python via uv — no AI, stdout = $<nodeId>.output) ---
+          # Use for deterministic data transforms the shell would mangle (JSON parsing, etc.)
+          script: |
+            const raw = String.raw`$other-node.output`;
+            const data = JSON.parse(raw);
+            console.log(JSON.stringify({ count: data.items.length }));
+          runtime: bun                       # required: 'bun' (.ts/.js) or 'uv' (.py)
+          # deps: [requests]                 # uv only
+          # Or reference a named script in .archon/scripts/:
+          # script: extract-labels           # no extension; bun resolves .ts/.js, uv resolves .py
+
           # --- loop node (iterative AI execution) ---
           loop:
             prompt: |
@@ -139,17 +151,22 @@ nodes:
             max_iterations: 10
             fresh_context: true  # optional: reset context each iteration
 
+          # --- approval node (human gate — pauses workflow) ---
+          approval:
+            message: "Review the plan above. Approve to continue."
+            # capture_response: true         # store reviewer comment as $<nodeId>.output
+
           # Common options for all node types:
           depends_on: [other-node-id]       # DAG edges
           when: "$<other-node>.output == 'value'"  # conditional execution
           trigger_rule: all_success          # all_success | one_success | all_done
-          timeout: 120000                    # ms, for bash nodes
+          timeout: 120000                    # ms, for bash and script nodes
       ```
 
       ## Variable Reference
       - `$ARGUMENTS` — user's input text
       - `$ARTIFACTS_DIR` — pre-created directory for workflow artifacts
-      - `$<nodeId>.output` — stdout from a bash node or AI response from a prompt node
+      - `$<nodeId>.output` — stdout from a bash/script node or AI response from a prompt node
       - `$<nodeId>.output.field` — JSON field from a node with output_format
       - `$BASE_BRANCH` — base git branch
 
@@ -158,12 +175,14 @@ nodes:
       2. The `description:` MUST follow the "Use when / Triggers / Does / NOT for" pattern
       3. Every node MUST have a unique kebab-case `id`
       4. Use `depends_on` to define execution order
-      5. Use `bash` nodes for deterministic operations (file checks, git commands, installs)
-      6. Use `prompt` nodes for AI reasoning tasks
-      7. Use `output_format` on prompt nodes when downstream nodes need structured data
-      8. Use `allowed_tools: []` on classification/analysis nodes that don't need tools
-      9. Use `denied_tools: [Edit, Bash]` when a node should only use Write (not edit existing files)
-      10. Prefer `model: haiku` for simple classification tasks to save cost
+      5. Use `bash` nodes for deterministic shell operations (file checks, git commands, installs)
+      6. Use `script` nodes for typed data transforms (TypeScript JSON parsing, Python with deps) — stdout is captured as output, stderr is forwarded as a warning. $nodeId.output is NOT shell-quoted in script bodies — parse with JSON.parse / json.loads, not shell interpolation
+      7. Use `prompt` nodes for AI reasoning tasks
+      8. Use `approval` nodes to pause for human review at risky gates (plan→execute boundary, destructive actions)
+      9. Use `output_format` on prompt nodes when downstream nodes need structured data
+      10. Use `allowed_tools: []` on classification/analysis nodes that don't need tools
+      11. Use `denied_tools: [Edit, Bash]` when a node should only use Write (not edit existing files)
+      12. Prefer `model: haiku` for simple classification tasks to save cost
 
       ## Output