feat: complete repo_architect methodology — lane scoping, enhanced validation, entrypoint_consolidation, 57 tests, campaign report

.github/workflows/repo-architect.yml

@@ -12,10 +12,11 @@ on:
           - analyze
           - report
           - mutate
+          - campaign
       github_model:
-        description: 'GitHub Models model id'
-        required: true
-        default: 'openai/gpt-4.1'
+        description: 'GitHub Models model id (overrides preferred model)'
+        required: false
+        default: ''
         type: string
       report_path:
         description: 'Primary report path'
@@ -31,6 +32,16 @@ on:
           - '1'
           - '2'
           - '3'
+      max_slices:
+        description: 'Campaign max slices (campaign mode only)'
+        required: false
+        default: '3'
+        type: string
+      lanes:
+        description: 'Comma-separated lane order (campaign mode only)'
+        required: false
+        default: 'parse_errors,import_cycles,hygiene,report'
+        type: string
   schedule:
     - cron: '17 * * * *'
 
@@ -62,22 +73,36 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
+      - name: Ensure artifact directories exist
+        run: |
+          mkdir -p .agent docs/repo_architect
+
       - name: Run repo architect
         env:
           GITHUB_TOKEN: ${{ github.token }}
           GITHUB_REPO: ${{ github.repository }}
           GITHUB_BASE_BRANCH: ${{ github.event.repository.default_branch }}
+          REPO_ARCHITECT_BRANCH_SUFFIX: ${{ github.run_id }}-${{ github.run_attempt }}
+          REPO_ARCHITECT_PREFERRED_MODEL: openai/gpt-5.4
+          REPO_ARCHITECT_FALLBACK_MODEL: openai/gpt-4.1
         run: |
           MODE="${{ github.event.inputs.mode }}"
           MODEL="${{ github.event.inputs.github_model }}"
           REPORT_PATH="${{ github.event.inputs.report_path }}"
           MUTATION_BUDGET="${{ github.event.inputs.mutation_budget }}"
+          MAX_SLICES="${{ github.event.inputs.max_slices }}"
+          LANES="${{ github.event.inputs.lanes }}"
           if [ -z "$MODE" ]; then MODE="report"; fi
-          if [ -z "$MODEL" ]; then MODEL="openai/gpt-4.1"; fi
           if [ -z "$REPORT_PATH" ]; then REPORT_PATH="docs/repo_architect/runtime_inventory.md"; fi
           if [ -z "$MUTATION_BUDGET" ]; then MUTATION_BUDGET="1"; fi
-          export GITHUB_MODEL="$MODEL"
-          python repo_architect.py --allow-dirty --mode "$MODE" --report-path "$REPORT_PATH" --mutation-budget "$MUTATION_BUDGET"
+          if [ -z "$MAX_SLICES" ]; then MAX_SLICES="3"; fi
+          if [ -z "$LANES" ]; then LANES="parse_errors,import_cycles,hygiene,report"; fi
+          EXTRA_ARGS=""
+          if [ -n "$MODEL" ]; then EXTRA_ARGS="$EXTRA_ARGS --github-model $MODEL"; fi
+          if [ "$MODE" = "campaign" ]; then
+            EXTRA_ARGS="$EXTRA_ARGS --max-slices $MAX_SLICES --lanes $LANES"
+          fi
+          python repo_architect.py --allow-dirty --mode "$MODE" --report-path "$REPORT_PATH" --mutation-budget "$MUTATION_BUDGET" $EXTRA_ARGS
 
       - name: Upload repo architect artifacts
         if: always()

docs/repo_architect/OPERATOR_GUIDE.md

@@ -0,0 +1,131 @@
+# repo-architect Operator Guide
+
+## Overview
+
+`repo_architect.py` is a single-file autonomous agent that:
+- Analyses the Python codebase for parse errors, import cycles, entrypoints, and hygiene issues.
+- Generates or refreshes architecture documentation under `docs/repo_architect/`.
+- Creates mutation branches and pull-requests that fix real code issues.
+- Can run repeatedly without branch collisions or stale-branch failures.
+
+---
+
+## Model Selection (preferred / fallback)
+
+The agent tries a **preferred** model first and automatically retries with a **fallback** model when the preferred one is unavailable or returns an unknown-model error.
+
+| Priority | Source |
+|---|---|
+| 1 | `--preferred-model` CLI flag |
+| 2 | `REPO_ARCHITECT_PREFERRED_MODEL` env var |
+| 3 | Hard-coded default (`openai/gpt-5.4`) |
+
+| Fallback priority | Source |
+|---|---|
+| 1 | `--fallback-model` CLI flag |
+| 2 | `REPO_ARCHITECT_FALLBACK_MODEL` env var |
+| 3 | Hard-coded default (`openai/gpt-4.1`) |
+
+**Failure tolerance:** if both model calls fail (network, quota, unavailability), the run continues without model-generated output instead of aborting. The JSON result records `fallback_reason` and `fallback_occurred`.
+
+The workflow exports:
+```yaml
+REPO_ARCHITECT_PREFERRED_MODEL: openai/gpt-5.4
+REPO_ARCHITECT_FALLBACK_MODEL: openai/gpt-4.1
+```
+
+---
+
+## Unique Branch Strategy
+
+Every mutation branch is suffixed with a per-run unique token to prevent branch-push collisions.
+
+**Suffix precedence:**
+1. `REPO_ARCHITECT_BRANCH_SUFFIX` env var (if set and non-empty)
+2. `GITHUB_RUN_ID-GITHUB_RUN_ATTEMPT` (when both are present)
+3. UTC timestamp fallback (`YYYYmmddHHMMSS`)
+
+The suffix is sanitised to `[A-Za-z0-9._-]` only.
+
+**Push collision recovery:** Before pushing, the agent checks whether the remote branch already exists. If it does, a fresh unique branch name is generated. A single retry is also performed if the push is rejected due to a non-fast-forward error.
+
+The workflow exports:
+```yaml
+REPO_ARCHITECT_BRANCH_SUFFIX: ${{ github.run_id }}-${{ github.run_attempt }}
+```
+
+---
+
+## Lane Priority Rules
+
+In `mutate` and `campaign` modes the agent selects exactly one lane per slice, in this priority order:
+
+| Priority | Lane | Behaviour |
+|---|---|---|
+| 1 | `parse_errors` | Model-assisted syntax fix for one or more files with parse errors. Skipped if no parse errors exist or model is unavailable. |
+| 2 | `import_cycles` | Model-assisted import cycle break (TYPE_CHECKING guard / lazy import). Skipped if no cycles or model unavailable. |
+| 3 | `hygiene` | Remove explicitly `# DEBUG`-marked `print()` statements. No model required. |
+| 4 | `report` | Refresh the architecture documentation packet. Only selected when no higher-priority code mutation is possible. |
+
+A **report-only mutation is never produced when parse errors exist** unless all code-lane attempts fail (in which case `no_safe_code_mutation_reason` is populated in the JSON output).
+
+---
+
+## Campaign Mode
+
+Campaign mode executes up to `--max-slices` mutation slices across the lane priority order, re-analysing between each slice so later lanes see the updated repository state.
+
+```bash
+python repo_architect.py \
+  --mode campaign \
+  --allow-dirty \
+  --max-slices 3 \
+  --lanes parse_errors,import_cycles,hygiene,report \
+  --stop-on-failure
+```
+
+**CLI flags:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--max-slices` | `3` | Maximum slices to attempt |
+| `--lanes` | `parse_errors,import_cycles,hygiene,report` | Comma-separated lane order |
+| `--stop-on-failure` | `false` | Abort remaining slices on first failure |
+| `--preferred-model` | (env / default) | Override preferred model for this run |
+| `--fallback-model` | (env / default) | Override fallback model for this run |
+
+Campaign results are emitted as `status: campaign_complete` JSON and also saved to `.agent/campaign_summary.json`.
+
+---
+
+## Output Contract (machine-readable JSON)
+
+Every run emits a JSON object on stdout. Key fields:
+
+| Field | Description |
+|---|---|
+| `status` | `analyzed`, `analysis_only`, `mutated`, `no_meaningful_delta`, `no_safe_mutation_available`, `campaign_complete` |
+| `mode` | Active mode |
+| `lane` | Selected mutation lane (`none` if no mutation) |
+| `architecture_score` | 1–100 composite health score |
+| `requested_model` | Model that was requested |
+| `actual_model` | Model that actually responded (may differ if fallback occurred) |
+| `fallback_reason` | Reason fallback was triggered (or `null`) |
+| `fallback_occurred` | `true` if the fallback model was used |
+| `no_safe_code_mutation_reason` | Explanation when no code-level mutation was safe |
+| `branch` | Git branch name pushed (or `null`) |
+| `changed_files` | List of files modified |
+| `validation` | Output from `py_compile` or equivalent validation |
+| `artifact_files` | All artifact paths generated in this run |
+| `pull_request_url` | PR URL if created |
+
+---
+
+## Workflow Dispatch Modes
+
+| Mode | Effect |
+|---|---|
+| `analyze` | Builds analysis, writes `.agent/` artifacts, no branch or PR |
+| `report` | Refreshes `docs/repo_architect/` documentation |
+| `mutate` | Attempts one code or report mutation in lane-priority order |
+| `campaign` | Runs up to `max_slices` slices serially across lanes |