docs: align skills and architecture with ADR 41 dispatch

Update architecture, installation guides, and agent skills for synchronous
dispatch and fullsend_ai_ref version pinning.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ifireball

docs/ADRs/0035-layered-content-resolution.md

@@ -58,8 +58,10 @@ In both cases the main dirs (`agents/`, `skills/`, etc.) are not committed —
 they are populated at runtime from upstream.
 
 **B. Runtime layering via reusable workflows.** Each reusable workflow adds a
-"Prepare workspace" step that sparse-checkouts upstream defaults from
-`fullsend-ai/fullsend@v0`, copies them into the main dirs (`agents/`, `skills/`,
+"Prepare workspace" step that checks out upstream defaults from
+`fullsend-ai/fullsend` at the ref supplied via `fullsend_ai_ref` (PR #1278
+replaced the earlier checkout at `@v0` with a checkout at a
+caller-controlled ref), copies them into the main dirs (`agents/`, `skills/`,
 etc.), then copies customizations on top so override files replace upstream
 defaults. The workflow inspects `install_mode` to resolve the correct
 customization base:
@@ -89,7 +91,7 @@ File categories after this change:
   scaffold creates the structure, orgs add real files.
 - **Upstream defaults** (~60 files): agents, skills, schemas, harness,
   policies, scripts, env — authoritative in `fullsend-ai/fullsend`, provided
-  at runtime via sparse checkout of the release tag.
+  at runtime via checkout of the release tag.
 - **Upstream infrastructure** (~5 files): composite actions,
   `setup-agent-env.sh` — referenced directly from upstream, never in `.fullsend`.
 
@@ -114,7 +116,7 @@ File categories after this change:
 - Overrides are explicit and auditable: in `customized/` for per-org, in
   `.fullsend/customized/` for per-repo.
 - Requires a public upstream repo (`fullsend-ai/fullsend` is already public).
-- Runtime availability: sparse checkout of upstream defaults requires
+- Runtime availability: checkout of upstream defaults requires
   github.com to be reachable at workflow execution time. GitHub Actions already
   depends on github.com, so this adds no new availability boundary.
 - Migration for existing orgs: orgs that customized files in top-level dirs

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:**
 
@@ -334,10 +328,10 @@ See [ADR 0003](ADRs/0003-org-config-repo-convention.md) for the config repo conv
 **Decided:**
 
 - Layered content resolution: upstream defaults (agents, skills, schemas,
-  harness, policies, scripts) are provided at runtime via reusable workflow
-  sparse-checkout of `fullsend-ai/fullsend@v0`. The scaffold installs only
-  org-specific files and a `customized/` directory for org overrides. Org files
-  in `customized/` overwrite upstream defaults at runtime
+  harness, policies, scripts) are provided at runtime via a full checkout of
+  `fullsend-ai/fullsend` at the ref passed via `fullsend_ai_ref`. The scaffold
+  installs only org-specific files and a `customized/` directory for org
+  overrides. Org files in `customized/` overwrite upstream defaults at runtime
   ([ADR 0035](ADRs/0035-layered-content-resolution.md)).
 
 ## Multi-org deployment model
@@ -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,8 +600,8 @@ 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) |
-| Agent runner | GitHub Actions job → `fullsend run` CLI (via `fullsend-ai/fullsend@v0` composite action) | |
+| Dispatcher | Shim workflow (`fullsend.yml`) in enrolled repo → `workflow_call` to `.fullsend/dispatch.yml` → synchronous `workflow_call` to upstream reusable workflows at `fullsend_ai_ref` | [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@<version>` 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) | |
 | Agent runtime | Claude Code (`claude --agent --dangerously-skip-permissions`) | |

docs/guides/README.md

@@ -34,4 +34,5 @@ Guides for developers working in repositories where fullsend is active.
 Guides for contributors developing and testing fullsend itself.
 
 - [Local development](dev/local-dev.md) — Run fullsend agents locally on macOS and Linux (amd64 + arm64)
+- [Testing workflow changes](dev/testing-workflows.md) — Point a live GitHub org at a branch to test workflow, action, and agent changes before release
 - [CLI internals](dev/cli-internals.md) — Command structure, installation pipeline, and sandbox runtime

docs/guides/dev/testing-workflows.md

@@ -0,0 +1,54 @@
+# Testing workflow changes
+
+This guide explains how to test changes to Fullsend's GitHub Actions workflows.
+
+## Per-repo mode
+
+In your repository modify the dispatch job at `.github/workflows/fullsend.yaml` to
+use the ref you want to test. Change the reference `uses` and
+`fullsend_ai_ref` to the same value.
+
+```yaml
+# .github/workflows/fullsend.yaml
+# [...]
+jobs:
+  dispatch:
+    # [...]
+    uses: fullsend-ai/fullsend/.github/workflows/reusable-dispatch.yml@<YOUR_VERSION>
+    with:
+      # [...]
+      fullsend_ai_ref: <YOUR_VERSION>
+      # [...]
+```
+
+Then push this change and trigger a Fullsend action: `/fs-triage`, `/fs-code`, ... When the ref is
+deleted from fullsend-ai/fullsend (branch deleted or commit amended), revert this back to the
+desired reference.
+
+## Per-org mode
+
+**WARNING**: this impacts all repositories, so proceed with care. You can install your test repository
+using the repository install mode to avoid this problem.
+
+For org installs, the shim passes `fullsend_ai_ref` from the `FULLSEND_AI_REF` org variable (default
+`v0`). To test a branch across the org without editing every enrolled repo, set the org variable
+(for example via `gh variable set FULLSEND_AI_REF --org <ORG> --body <YOUR_VERSION>`) and ensure
+selected repos include your test repo.
+
+Alternatively, edit `.fullsend/.github/workflows/dispatch.yml` and change both the `uses:` ref on
+each `reusable-<stage>.yml` call and the `fullsend_ai_ref` input passed to it:
+
+```yaml
+# .fullsend/.github/workflows/dispatch.yml
+# [...]
+  triage:
+    uses: fullsend-ai/fullsend/.github/workflows/reusable-triage.yml@<YOUR_VERSION>
+    with:
+      # [...]
+      fullsend_ai_ref: <YOUR_VERSION>
+      # [...]
+```
+
+Then push this change and trigger a Fullsend action on your test repository: `/fs-triage`, `/fs-code`, ...
+When the ref is deleted from fullsend-ai/fullsend (branch deleted or commit amended), revert this back
+to the desired reference.

docs/guides/getting-started/installation.md

@@ -352,10 +352,10 @@ Per-repo mode installs fullsend for a single repository without requiring an org
 > **Installing fullsend in the `fullsend-ai` org:** When installing fullsend for
 > `fullsend-ai/fullsend` itself, prefer **per-org mode** (`fullsend admin install fullsend-ai`).
 > Per-repo mode technically works but creates a circular reference: the per-repo
-> shim workflow calls `fullsend-ai/fullsend/.github/workflows/reusable-dispatch.yml@v0`,
-> which in turn calls reusable stage workflows in the same repo, which check out
-> `fullsend-ai/fullsend@v0` again for upstream defaults and use
-> `fullsend-ai/fullsend@v0` as the composite action. The repo ends up
+> shim workflow calls `fullsend-ai/fullsend/.github/workflows/reusable-dispatch.yml@<ref>`,
+> which resolves stage workflows via relative paths in the same ref, which in
+> turn check out `fullsend-ai/fullsend` at `fullsend_ai_ref` for upstream
+> defaults and load the composite action from that checkout. The repo ends up
 > simultaneously serving as the source of reusable workflows, the source of the
 > composite action, the caller repo, and the target repo being acted on. Per-org
 > mode avoids this by placing the shim in `fullsend-ai/fullsend` and the agent

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