Restructure for concurrent agent contributions: derive registration, isolate patches, split guidance

.github/workflows/pr-overlap.yml

@@ -0,0 +1,63 @@
+name: PR overlap
+
+# Advisory only: with many agent sessions working concurrently, two open PRs that
+# touch the same files are usually duplicated or conflicting work discovered too
+# late (post-merge). This surfaces the intersection as a warning annotation +
+# step summary while both PRs are still open; it never fails the build.
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, ready_for_review, synchronize]
+
+# Least privilege: listing open PRs and their files only needs read access.
+# No checkout, no third-party actions — the job is a single `gh api` script.
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  overlap:
+    name: warn when another open PR touches the same files
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      GH_TOKEN: ${{ github.token }}
+      # Numeric / repo-slug values, passed through env (not inlined into the
+      # script) so no event-controlled text is interpolated into bash.
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      REPO: ${{ github.repository }}
+    steps:
+      - name: Compare changed files against every other open PR
+        run: |
+          set -euo pipefail
+          mine="$(mktemp)"
+          theirs="$(mktemp)"
+          gh api "repos/${REPO}/pulls/${PR_NUMBER}/files" --paginate \
+            --jq '.[].filename' | sort -u > "$mine"
+          found=0
+          while read -r number; do
+            [ "$number" = "$PR_NUMBER" ] && continue
+            gh api "repos/${REPO}/pulls/${number}/files" --paginate \
+              --jq '.[].filename' | sort -u > "$theirs"
+            shared="$(comm -12 "$mine" "$theirs")"
+            if [ -n "$shared" ]; then
+              found=1
+              count="$(printf '%s\n' "$shared" | wc -l | tr -d '[:space:]')"
+              echo "::warning title=PR overlap::PR #${number} also changes ${count} of this PR's files - check for duplicated or conflicting work."
+              {
+                echo "### Overlap with PR #${number}"
+                echo ""
+                printf '%s\n' "$shared" | sed 's/^/- /'
+                echo ""
+              } >> "$GITHUB_STEP_SUMMARY"
+            fi
+          done < <(gh api "repos/${REPO}/pulls?state=open&per_page=100" --paginate \
+            --jq '.[].number')
+          if [ "$found" = 0 ]; then
+            echo "No open PR shares files with this one." >> "$GITHUB_STEP_SUMMARY"
+          fi

.importlinter

@@ -11,6 +11,7 @@ source_modules =
     aai_cli.argscan
     aai_cli.auth
     aai_cli.caption_exec
+    aai_cli.choices
     aai_cli.client
     aai_cli.clip_exec
     aai_cli.clip_select
@@ -23,37 +24,47 @@ source_modules =
     aai_cli.deploy_exec
     aai_cli.dev_exec
     aai_cli.dictate_exec
+    aai_cli.doctor_checks
     aai_cli.dub_exec
     aai_cli.environments
     aai_cli.errors
     aai_cli.eval_data
+    aai_cli.eval_hf_api
     aai_cli.evaluate_exec
     aai_cli.follow
     aai_cli.help_panels
     aai_cli.help_text
     aai_cli.hotkey
     aai_cli.init
     aai_cli.init_exec
+    aai_cli.jsonshape
     aai_cli.llm
     aai_cli.llm_exec
     aai_cli.mediafile
     aai_cli.microphone
+    aai_cli.onboard
     aai_cli.options
     aai_cli.output
     aai_cli.procs
     aai_cli.remotefs
     aai_cli.render
+    aai_cli.setup_exec
     aai_cli.share_exec
     aai_cli.speak_exec
     aai_cli.stdio
+    aai_cli.steps
     aai_cli.stream_exec
     aai_cli.streaming
     aai_cli.sync_stt
     aai_cli.telemetry
     aai_cli.theme
+    aai_cli.timeparse
     aai_cli.transcribe_batch
     aai_cli.transcribe_exec
     aai_cli.transcribe_render
+    aai_cli.tts
+    aai_cli.typer_patches
+    aai_cli.update_check
     aai_cli.webhook_listen
     aai_cli.wer
     aai_cli.ws
@@ -64,30 +75,11 @@ forbidden_modules =
 [importlinter:contract:2]
 name = Command modules are independent
 type = independence
+; Wildcard so every module under aai_cli/commands/ is covered automatically —
+; the previous enumerated list had silently drifted (onboard and speak were
+; missing, so nothing forbade them from importing sibling commands).
 modules =
-    aai_cli.commands.account
-    aai_cli.commands.agent
-    aai_cli.commands.audit
-    aai_cli.commands.caption
-    aai_cli.commands.clip
-    aai_cli.commands.deploy
-    aai_cli.commands.dev
-    aai_cli.commands.dictate
-    aai_cli.commands.doctor
-    aai_cli.commands.dub
-    aai_cli.commands.evaluate
-    aai_cli.commands.init
-    aai_cli.commands.keys
-    aai_cli.commands.llm
-    aai_cli.commands.login
-    aai_cli.commands.sessions
-    aai_cli.commands.setup
-    aai_cli.commands.share
-    aai_cli.commands.stream
-    aai_cli.commands.telemetry
-    aai_cli.commands.transcribe
-    aai_cli.commands.transcripts
-    aai_cli.commands.webhooks
+    aai_cli.commands.*
 
 [importlinter:contract:3]
 name = Library layers do not depend on Rich rendering