Clarify orchestrator only collects pointer metadata

Round 4 review caught three places where the wording still
described the old read-side model. The Stage 5 purpose text said
the orchestrator "collect[s] failure logs and send[s] them to
Agent A", and the orchestrator-managed-operations section said CI
polling "collect[s] failure details" — both contradict the
pointer-based contract this PR establishes. The TSDoc on
`buildCiInspectionContext` also referred to "the ref for code
scanning queries", which is easy to misread back into the
SHA-as-alert-ref bug from Round 3.

Reword these descriptions to make the bounded-pointer contract
explicit, and clarify in the helper's TSDoc that its `ref` is a
commit SHA and is not the right input for the code-scanning
alerts API.

Part of #316

Author: sehkone

docs/pipeline.md

@@ -566,10 +566,14 @@ subsequent stages depend on the PR.
 ### Stage 5: CI check loop
 
 **Agent:** A (only on failure or findings review)\
-**Purpose:** Wait for CI to pass. If CI fails, collect failure
-logs and send them to Agent A for a fix. If CI passes but check
-runs report findings (annotations), present them to Agent A for
-review.
+**Purpose:** Wait for CI to pass. If CI fails, build a bounded
+pointer-based inspection context (failing run/job IDs, check-run
+IDs, the commit SHA, and incomplete-metadata flags) and send it to
+Agent A so the agent can fetch the failure logs itself. If CI passes
+but check runs report findings (annotations), pass the same pointer
+context to Agent A for review — the agent reads annotation bodies
+and code scanning alerts on demand rather than receiving them
+inlined.
 
 The orchestrator polls CI status at 30-second intervals. The CI
 verdict includes both **workflow runs** (Actions API) and **check
@@ -1870,10 +1874,13 @@ details.
 
 - **PR number extraction:** After Agent A creates a PR, extract
   the number via `gh pr list --head {branch} --json number`.
-- **CI status polling:** Check CI status and collect failure
-  details. A CI check is considered passed when all required
-  checks succeed. `pending` -> wait and re-poll. `skipped` ->
-  ignore. `cancelled` -> treat as failure.
+- **CI status polling:** Check CI status and build a bounded
+  pointer-based inspection context (failing run/job IDs,
+  check-run IDs, ref/SHA, incomplete-metadata flags) — never
+  raw failure logs, annotation bodies, or alert payloads, which
+  the agent fetches itself. A CI check is considered passed
+  when all required checks succeed. `pending` -> wait and
+  re-poll. `skipped` -> ignore. `cancelled` -> treat as failure.
 - **Mergeable status checking:** Query the GitHub API with
   exponential backoff to handle the `UNKNOWN` state that occurs
   while GitHub computes mergeability.

src/ci.ts

@@ -571,10 +571,17 @@ function fetchFailedJobs(
 
 /**
  * Build a small, bounded inspection context that points the agent at
- * the failing CI surfaces (workflow runs/jobs, check runs, the ref
- * for code scanning queries).  The agent uses the pointers to fetch
- * logs, annotations, and alerts itself rather than receiving them
- * inlined in the prompt.
+ * the failing CI surfaces (workflow runs/jobs, check runs, and the
+ * commit SHA used for `commits/{ref}/check-runs`-style lookups).
+ * The agent uses the pointers to fetch logs, annotations, and alerts
+ * itself rather than receiving them inlined in the prompt.
+ *
+ * Note: the `ref` field on the resulting context is a commit SHA and
+ * is **not** the right input for the code-scanning alerts API, which
+ * filters by Git ref (branch / `refs/pull/<n>/merge`).  Code-scanning
+ * alert reads use the branch/PR ref from the stage context instead;
+ * see `buildFetchHints` in `src/stage-cicheck.ts` and the
+ * `CiInspectionContext.ref` TSDoc.
  *
  * **Contract for future edits:** this helper must NOT pull raw step
  * logs, raw alert payloads, or annotation bodies — those are exactly