docs: align skills and architecture with ADR 41 dispatch

Update architecture.md and agent skills for synchronous workflow_call:
finding-agent-runs and retro-analysis trace runs on the enrolled-repo
shim (not separate .fullsend dispatch runs). Restore code-implementation
API contract checklist dropped during rebase.

Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: Barak Korren <bkorren@redhat.com>

Author: ifireball

docs/architecture.md

@@ -39,12 +39,11 @@ Infrastructure platform choice and configuration are specified in the adopting o
 
 - Forge abstraction: all forge operations go through the `forge.Client` interface, keeping the rest of the codebase forge-agnostic ([ADR 0005](ADRs/0005-forge-abstraction-layer.md)).
 - Installation model: ordered layer stack (install forward, uninstall reverse, analyze for status reporting) with idempotent operations. Current stack: config-repo → workflows → secrets → inference → dispatch → enrollment ([ADR 0006](ADRs/0006-ordered-layer-model.md)).
-- Cross-repo dispatch: enrolled repos call `.fullsend` via `workflow_call`; a dispatch workflow mints OIDC tokens exchanged at a central token mint (GCP Cloud Function) for scoped GitHub App installation tokens per agent role. App PEM secrets are stored in Secret Manager, not the config repo ([ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md)).
+- Cross-repo dispatch: enrolled repos call `.fullsend` via `workflow_call`; dispatch routes events to upstream reusable workflows via synchronous `workflow_call` jobs. Each reusable workflow mints OIDC tokens exchanged at a central token mint (GCP Cloud Function) for scoped GitHub App installation tokens per agent role. App PEM secrets are stored in Secret Manager, not the config repo ([ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md), [ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md)).
 - Shim workflow security: `pull_request_target` prevents PR authors from modifying the shim workflow. No long-lived secrets flow through the shim — OIDC tokens are issued by the GitHub runtime and scoped to the workflow run ([ADR 0009](ADRs/0009-pull-request-target-in-shim-workflows.md)).
 - Repo maintenance: a workflow in `.fullsend` (`.github/workflows/repo-maintenance.yml`) reconciles enrollment shims in target repos when `config.yaml` changes or on manual dispatch. The CLI's `EnrollmentLayer.Install()` dispatches this workflow via `workflow_dispatch` and monitors it for completion, then reports any enrollment PRs created in target repos.
 - Installer scaffold: the `WorkflowsLayer` deploys content from an embedded scaffold (`internal/scaffold/`), keeping deployable files as real files under version control rather than Go string constants.
-- Reusable workflows: agent workflows in `.fullsend` are thin callers (~40-70 lines) that delegate infrastructure logic to upstream reusable workflows (`fullsend-ai/fullsend/.github/workflows/reusable-*.yml`) via `workflow_call`. Infrastructure patches ship once upstream and propagate to all orgs without re-install ([ADR 0031](ADRs/0031-reusable-workflows-for-action-installed-distribution.md)).
-- Event-driven stage dispatch: eliminate `workflow_dispatch` + `gh workflow run` fan-out from `dispatch.yml` in favor of synchronous `workflow_call` so the dispatched run stays linked to the caller ([ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md)).
+- Reusable workflows: `dispatch.yml` in `.fullsend` calls upstream reusable workflows (`fullsend-ai/fullsend/.github/workflows/reusable-*.yml`) directly via `workflow_call` jobs (no per-stage thin callers). Infrastructure patches ship once upstream and propagate to all orgs without re-install ([ADR 0031](ADRs/0031-reusable-workflows-for-action-installed-distribution.md), [ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md)).
 
 **Open questions:**
 
@@ -131,10 +130,6 @@ The mechanism that assigns work to agents and prevents conflicts. Responsible fo
 
 The existing design principle is that [the repo is the coordinator](problems/agent-architecture.md#interaction-model-the-repo-as-coordinator) — branch protection, CODEOWNERS, status checks, and GitHub events provide coordination without a central orchestrator. The agent dispatch and coordination layer may be nothing more than the glue that connects GitHub webhooks to agent infrastructure. Or it may need to be more.
 
-**Decided:**
-
-- Event-driven stage dispatch runs synchronously via `workflow_call` to preserve run correlation in the GitHub Actions UI (see [ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md)).
-
 **Open questions:**
 
 - Is GitHub's event system sufficient, or do we need additional coordination logic (e.g. to prevent two code agents from picking up the same issue)?
@@ -180,7 +175,6 @@ Observability is a cross-cutting concern that touches every other component. Eac
 **Decided:**
 
 - JSONL reasoning trace exposure: raw JSONL conversation transcripts are extracted from sandboxes and stored with owner-scoped access. Credential scanning acts as an invariant check on [ADR 0017](ADRs/0017-credential-isolation-for-sandboxed-agents.md)'s isolation model. Agents handling data from protected sources beyond the target repo can opt in to JSONL suppression via configuration ([ADR 0021](ADRs/0021-jsonl-reasoning-trace-exposure.md)).
-- Event-driven stage dispatch remains traceable end-to-end in the GitHub Actions UI by using synchronous `workflow_call` dispatch (see [ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md)).
 
 **Open questions:**
 
@@ -518,14 +512,13 @@ GitHub event ──► SHIM WORKFLOW (fullsend.yml in enrolled repo)
                  ╔═══════════════════════════════════════════════════════════════╗
                  ║ DISPATCH WORKFLOW (.fullsend repo, dispatch.yml)              ║
                  ║                                                               ║
-                 ║ Mints OIDC token → Cloud Function (token mint) → scoped      ║
-                 ║ GitHub App installation token per agent role.                  ║
-                 ║ Dispatches per-role agent workflows (code.yml, triage.yml).   ║
+                 ║ Routes to stage; synchronous workflow_call to upstream      ║
+                 ║ reusable-{stage}.yml (or prioritize.yml in .fullsend).        ║
                  ╚═══════════════════════════════════════════════════════════════╝
                        │
                        ▼
                  ╔═══════════════════════════════════════════════════════════════╗
-                 ║ AGENT WORKFLOW (.fullsend repo, e.g. code.yml)               ║
+                 ║ AGENT WORKFLOW (fullsend-ai/fullsend reusable-*.yml)          ║
                  ║                                                               ║
                  ║ Validates source repo is enrolled in config.yaml.             ║
                  ║ Uses scoped GitHub App tokens:                                ║
@@ -607,7 +600,7 @@ GitHub event ──► SHIM WORKFLOW (fullsend.yml in enrolled repo)
 
 | Abstract layer | MVP technology | ADR |
 |---|---|---|
-| Dispatcher | Shim workflow (`fullsend.yml`) in enrolled repo → `workflow_call` to `.fullsend/dispatch.yml` → OIDC mint → per-role agent workflows (thin callers → upstream reusable workflows) | [ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md), [ADR 0031](ADRs/0031-reusable-workflows-for-action-installed-distribution.md) |
+| Dispatcher | Shim workflow (`fullsend.yml`) in enrolled repo → `workflow_call` to `.fullsend/dispatch.yml` → synchronous `workflow_call` to upstream reusable workflows | [ADR 0008](ADRs/0008-workflow-dispatch-for-cross-repo-dispatch.md), [ADR 0031](ADRs/0031-reusable-workflows-for-action-installed-distribution.md), [ADR 0041](ADRs/0041-synchronous-workflow-call-event-dispatch.md) |
 | Agent runner | GitHub Actions job → `fullsend run` CLI (via `fullsend-ai/fullsend@v0` composite action) | |
 | Harness store | YAML files in `.fullsend/harness/` (e.g. `code.yaml`, `triage.yaml`) | |
 | Sandbox | OpenShell with per-agent L7 network policies (endpoint + binary restrictions) | |

internal/scaffold/fullsend-repo/skills/finding-agent-runs/SKILL.md

@@ -13,13 +13,15 @@ Given an issue or PR, find the fullsend agent workflow runs using `gh` CLI.
 ## Setup
 
 ```bash
-ORG=$(echo "${REPO_FULL_NAME:-$(gh repo view --json owner -q .owner.login)}" | cut -d/ -f1)
-DISPATCH_REPO="${ORG}/.fullsend"
+SOURCE_REPO="${REPO_FULL_NAME:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"
+ORG=$(echo "${SOURCE_REPO}" | cut -d/ -f1)
+CONFIG_REPO="${ORG}/.fullsend"
 ```
 
-The shim workflow (`fullsend.yaml`) runs in the source repo on `main`. It
-dispatches to `${DISPATCH_REPO}` which runs the agent workflows
-(`triage.yml`, `code.yml`, `review.yml`, `retro.yml`).
+Per-org installs use synchronous `workflow_call`: the enrolled-repo shim
+(`fullsend.yaml`) calls `${CONFIG_REPO}` `dispatch.yml`, which runs agent
+stages as jobs in the **same** Actions run on `SOURCE_REPO`. There are no
+separate `dispatch.yml` runs in `.fullsend` to look up.
 
 ## Issue → Agent Runs
 
@@ -28,15 +30,15 @@ dispatches to `${DISPATCH_REPO}` which runs the agent workflows
 Triage dispatches from `issue_comment` events (the `/fs-triage` command):
 
 ```bash
-gh run list --workflow=fullsend.yaml \
+gh run list --repo "${SOURCE_REPO}" --workflow=fullsend.yaml \
   --json databaseId,status,conclusion,event,createdAt \
   -q '.[] | select(.event == "issue_comment")'
 ```
 
-Match by timestamp against the `/fs-triage` comment (`gh issue view <N> --json comments`), then confirm `dispatch-triage` succeeded:
+Match by timestamp against the `/fs-triage` comment (`gh issue view <N> --json comments`), then confirm the **Triage** stage job succeeded:
 
 ```bash
-gh run view <RUN_ID> --json jobs \
+gh run view <RUN_ID> --repo "${SOURCE_REPO}" --json jobs \
   -q '.jobs[] | "\(.name) \(.status)/\(.conclusion)"'
 ```
 
@@ -45,47 +47,35 @@ gh run view <RUN_ID> --json jobs \
 Code dispatches from `issues` events when `ready-to-code` is applied:
 
 ```bash
-gh run list --workflow=fullsend.yaml \
+gh run list --repo "${SOURCE_REPO}" --workflow=fullsend.yaml \
   --json databaseId,status,conclusion,event,createdAt \
   -q '.[] | select(.event == "issues")'
 ```
 
-Confirm `dispatch-code completed/success` in the jobs list.
-
-### Find the actual agent run
-
-Match by timestamp in the dispatch repo (runs start within seconds):
-
-```bash
-gh run list --repo "${DISPATCH_REPO}" --workflow=triage.yml --limit 5 \
-  --json databaseId,status,conclusion,createdAt
-
-gh run list --repo "${DISPATCH_REPO}" --workflow=code.yml --limit 5 \
-  --json databaseId,status,conclusion,createdAt
-```
+Confirm the **Code** job completed successfully in that run's job list.
 
 ## PR → Agent Runs
 
 ### Code agent run
 
 The PR branch follows `agent/{issue}-{slug}`. Extract the issue number and
-use the issue recipe above to find the code dispatch.
+use the issue recipe above to find the code dispatch run on `SOURCE_REPO`.
 
 ### Review dispatch
 
 Review dispatches from `pull_request_target` events. Match by `headBranch`:
 
 ```bash
-gh run list --workflow=fullsend.yaml \
+gh run list --repo "${SOURCE_REPO}" --workflow=fullsend.yaml \
   --json databaseId,status,conclusion,event,headBranch,createdAt \
   -q '.[] | select(.event == "pull_request_target")'
 ```
 
-Confirm `dispatch-review completed/success`, then find the run:
+Confirm the **Review** job completed successfully:
 
 ```bash
-gh run list --repo "${DISPATCH_REPO}" --workflow=review.yml --limit 5 \
-  --json databaseId,status,conclusion,createdAt
+gh run view <RUN_ID> --repo "${SOURCE_REPO}" --json jobs \
+  -q '.jobs[] | "\(.name) \(.status)/\(.conclusion)"'
 ```
 
 ### Retro dispatch
@@ -94,29 +84,26 @@ Retro dispatches from `pull_request_target` (on PR close) and from
 `issue_comment` events (the `/fs-retro` command):
 
 ```bash
-gh run list --workflow=fullsend.yaml \
+gh run list --repo "${SOURCE_REPO}" --workflow=fullsend.yaml \
   --json databaseId,status,conclusion,event,createdAt \
   -q '.[] | select(.event == "pull_request_target" or .event == "issue_comment")'
 ```
 
-Find the actual retro agent run:
-
-```bash
-gh run list --repo "${DISPATCH_REPO}" --workflow=retro.yml --limit 5 \
-  --json databaseId,status,conclusion,createdAt
-```
+Confirm the **Retro** job completed successfully in the same run.
 
 ## Reference
 
 ### Logs and artifacts
 
+Use the shim run ID on `SOURCE_REPO` (not `${CONFIG_REPO}`):
+
 ```bash
 # Search logs for errors
-gh run view <RUN_ID> --repo "${DISPATCH_REPO}" --log 2>&1 \
+gh run view <RUN_ID> --repo "${SOURCE_REPO}" --log 2>&1 \
   | grep -i "error\|fail\|exit code"
 
-# Download session artifact
-gh run download <RUN_ID> --repo "${DISPATCH_REPO}"
+# Download session artifact (uploaded by the stage job in this run)
+gh run download <RUN_ID> --repo "${SOURCE_REPO}"
 ```
 
 ### Common failure signatures

internal/scaffold/fullsend-repo/skills/retro-analysis/SKILL.md

@@ -15,67 +15,62 @@ Given the originating PR or issue, reconstruct what agents ran and in what order
 ### Setup
 
 ```bash
-ORG=$(echo "$REPO_FULL_NAME" | cut -d/ -f1)
-DISPATCH_REPO="${ORG}/.fullsend"
+SOURCE_REPO="${REPO_FULL_NAME:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"
+ORG=$(echo "${SOURCE_REPO}" | cut -d/ -f1)
+CONFIG_REPO="${ORG}/.fullsend"
 ```
 
+Per-org installs run shim → `dispatch.yml` → stage jobs synchronously in one
+Actions run on `SOURCE_REPO`. Stage names in the job list include **Route**,
+**Triage**, **Code**, **Review**, **Fix**, **Retro**, and **Prioritize**.
+
 ### From an issue
 
-1. Find triage dispatches (triggered by `/fs-triage` command or `needs-info` label responses):
+1. Find shim runs on the source repo (triage/code triggered by issue events or `/fs-triage`):
 
 ```bash
-gh run list --repo "$REPO_FULL_NAME" --workflow=fullsend.yaml \
+gh run list --repo "$SOURCE_REPO" --workflow=fullsend.yaml \
   --json databaseId,status,conclusion,event,createdAt \
   -q '.[] | select(.event == "issue_comment" or .event == "issues")'
 ```
 
-2. Find the corresponding agent runs in the dispatch repo:
-
-```bash
-gh run list --repo "$DISPATCH_REPO" --workflow=triage.yml --limit 10 \
-  --json databaseId,status,conclusion,createdAt
-```
-
-3. If the issue reached `ready-to-code`, find code dispatches:
+2. Inspect stage jobs inside that run (not separate runs in `.fullsend`):
 
 ```bash
-gh run list --repo "$DISPATCH_REPO" --workflow=code.yml --limit 10 \
-  --json databaseId,status,conclusion,createdAt
+gh run view <RUN_ID> --repo "$SOURCE_REPO" --json jobs \
+  -q '.jobs[] | "\(.name) \(.status)/\(.conclusion) \(.startedAt)"'
 ```
 
 ### From a PR
 
-1. The PR branch follows `agent/{issue}-{slug}`. Extract the issue number to trace the full history.
+1. The PR branch follows `agent/{issue}-{slug}`. Extract the issue number to trace the full history on `SOURCE_REPO`.
 
-2. Find review dispatches:
+2. Find shim runs for review/fix/retro (match by `headBranch` or timestamp):
 
 ```bash
-gh run list --repo "$DISPATCH_REPO" --workflow=review.yml --limit 10 \
-  --json databaseId,status,conclusion,createdAt
-```
-
-3. Find fix dispatches (if review requested changes):
-
-```bash
-gh run list --repo "$DISPATCH_REPO" --workflow=fix.yml --limit 10 \
-  --json databaseId,status,conclusion,createdAt
+gh run list --repo "$SOURCE_REPO" --workflow=fullsend.yaml \
+  --json databaseId,status,conclusion,event,headBranch,createdAt \
+  -q '.[] | select(.event == "pull_request_target" or .event == "issue_comment")'
 ```
 
 ### Reading agent logs and artifacts
 
 ```bash
 # View job outcomes
-gh run view <RUN_ID> --repo "$DISPATCH_REPO" --json jobs \
+gh run view <RUN_ID> --repo "$SOURCE_REPO" --json jobs \
   -q '.jobs[] | "\(.name) \(.status)/\(.conclusion)"'
 
 # Search logs for errors
-gh run view <RUN_ID> --repo "$DISPATCH_REPO" --log 2>&1 \
+gh run view <RUN_ID> --repo "$SOURCE_REPO" --log 2>&1 \
   | grep -i "error\|fail\|exit code"
 
 # Download session artifacts (JSONL traces)
-gh run download <RUN_ID> --repo "$DISPATCH_REPO"
+gh run download <RUN_ID> --repo "$SOURCE_REPO"
 ```
 
+Use `${CONFIG_REPO}` only when reading harness/agent definitions under
+`.fullsend` (files), not for workflow run IDs.
+
 ## Exploration strategy
 
 You have a large amount of context to cover. Use subagents to avoid overflowing your main context window.