docs(rag): close the corpus drift — findings/collision/fast-path/forge/env-ladder coverage (#596)

Seventeen-page sweep of the agent-facing KB against shipped behavior:
required covers_parent_criteria and per-AC criteria_verified reach the
QA/PM/task-tools pages (the QA docs also named non-callable pass_review/
fail_review — the MCP tools are pass/fail); collision_context lands in the
QA/gate/planning evidence docs; the possibilities matrix gets its own
architecture page + config entry; the auditor page gains its missing
waive_finding and playbook-curation verbs; git-pr-types.md is rewritten
off the long-dead is_root_pr model; PR/workspace/git-error pages stop
assuming GitHub (forge-agnostic + env-ladder semantics).

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

docs/rag/architecture/config-reference.md

@@ -189,6 +189,14 @@ Weekly, the Product Owner explores the company's projects and proposes a themed
 
 No dedicated migration — a cycle is marker-backed (`orchestration_markers` on the held exploration task), not a new table.
 
+## Possibilities Matrix
+
+The work-already-done fast path on `i_am_done`. Default-off, transparent to the dev (no verb change, no opt-in call). See `docs/rag/architecture/possibilities-matrix.md`.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ROBOCO_POSSIBILITIES_MATRIX_ENABLED` | `false` | Master switch. Off = `i_am_done` behaves exactly as it always has. On = when a task already has commits, an open PR, every AC addressed, and no open findings, `i_am_done` submits straight to `awaiting_qa`, trusting the PR's own CI-green signal (falling back to the local `make quality` gate when there's no CI signal, and refusing outright on a known-red CI). |
+
 ## Cloud Auth
 
 **Not a panel feature flag** — unlike the flags above, `ROBOCO_CLOUD_AUTH_ENABLED` is env-only (deliberately absent from `roboco/services/settings.py`'s `FEATURE_FLAGS`, so it can't be flipped on for a deployment that isn't behind TLS). Lets the panel/API be exposed beyond localhost without changing the CEO's local no-login flow while off. See `docs/rag/architecture/cloud-auth.md`.

docs/rag/architecture/possibilities-matrix.md

@@ -0,0 +1,57 @@
+# Possibilities Matrix (work-already-done fast path)
+
+A fast path on `i_am_done`: when a dev's work already looks done, the choreographer submits straight to `awaiting_qa` in one call instead of walking the standard verify/journal turn. Gated by `ROBOCO_POSSIBILITIES_MATRIX_ENABLED` (default off — panel-toggleable, Settings → Feature Flags). Fully inert when off: `i_am_done` behaves exactly as it always has.
+
+## You don't opt in — it's transparent
+
+There is no separate verb and no argument that turns this on. A developer always just calls:
+
+```python
+i_am_done(task_id="<task>", notes="...", resolved_findings=None)
+```
+
+`_maybe_i_am_done_fast_path` runs on **every** `i_am_done` call when the flag is armed, checks whether the task already looks done, and silently takes the fast path when it does. Nothing about how you call `i_am_done` changes — you never need to know whether the fast path fired.
+
+The orchestrator's dev spawn prompt sometimes steers a freshly spawned dev straight to a `WORK_ALREADY_DONE` state (when the flag is on and the task already has an open PR + commits at spawn time) that tells you to call `i_am_done` directly rather than re-deriving what's already done — this is a turn-saving nudge for that specific spawn-timing case, not a requirement. A mid-session dev who never saw that prompt still gets the fast path the moment it calls plain `i_am_done`.
+
+## What "already looks done" means
+
+`_work_appears_done` — all of the following, checked against the live task:
+
+- Status is `claimed`, `in_progress`, or `verifying`
+- At least one commit exists
+- A PR is open (`pr_created` or `pr_number` set)
+- Every acceptance criterion is addressed (each AC has a recorded artifact reference)
+- No open finding remains on the revision-findings ledger for this task
+
+Ownership (`assigned_to == you`) is checked separately before the fast path is even considered.
+
+## What still runs — nothing is skipped that matters
+
+The fast path is not a bypass of the non-negotiable guards, only of the standard multi-turn derivation:
+
+1. Substantive-notes check
+2. Video render-preview check, on a `source=video` task (`Requirement.RENDER_VERIFIED`)
+3. `resolved_findings` applied, if given
+4. Commits/PR field gates (`NO_COMMITS` / `NO_PR`)
+5. Branch pushed
+6. Not behind base
+7. Architectural-conventions gate, if enabled
+8. Every open finding re-checked — `FINDINGS_ADDRESSED` still blocks a resubmit that left one unnamed
+9. The quality verdict (below)
+
+What IS skipped versus the standard path: the retroactive rich-plan derivation, and the journal progress/reflect tracing gates.
+
+## The quality verdict — CI trusted, local gate as fallback
+
+`_fast_path_quality_verdict` resolves the assembled PR's own CI status the same way `pr_pass` does:
+
+- **CI green** → trusted outright; no local gate runs at all.
+- **CI red** → the fast path refuses outright: "fast path refused — PR CI is failing; QA reviews working code, not a red build." Fix CI (or route through the standard path) — the fast path will not ship a known-red build to QA.
+- **No CI signal at all** (not configured, pending, or unresolvable) → falls back to the local `make quality`-style gate (plus the toolchain-match guard, when `ROBOCO_TOOLCHAIN_MATCH_ENABLED` is also armed).
+
+## See also
+
+- `docs/rag/roles/developer.md` — the fast path from the dev's seat
+- `docs/rag/roles/pr-reviewer.md` / `docs/rag/architecture/review-findings.md` — the same CI-green trust `pr_pass` applies
+- `CLAUDE.md` "Possibilities matrix" — the canonical feature summary

docs/rag/architecture/review-findings.md

@@ -63,7 +63,11 @@ i_am_done(
 
 ## Verification (the reviewer's side)
 
-When the SAME origin's review passes on a later round, every `addressed` finding of that origin is bulk-promoted to `verified` in the same transaction — `pass` (QA) verifies `qa`-origin findings, `pr_pass` verifies `pr_gate`-origin, `complete` (PM) verifies `pm`-origin. `ceo_approve` does the same for `ceo`-origin findings, best-effort. A finding can also be `waived` (the repository supports it) but no verb currently calls that path — an unaddressed finding cannot yet be dismissed without actually resolving it.
+When the SAME origin's review passes on a later round, every `addressed` finding of that origin is bulk-promoted to `verified` in the same transaction — `pass` (QA) verifies `qa`-origin findings, `pr_pass` verifies `pr_gate`-origin, `complete` (PM) verifies `pm`-origin. `ceo_approve` does the same for `ceo`-origin findings, best-effort.
+
+## Waiving a finding (Auditor only)
+
+A finding can also be `waived` instead of fixed — but only by the Auditor, and only for non-blocking severity. `waive_finding(finding_id, note)` is a flow verb on the Auditor's manifest, severity-scoped: `blocker`/`major` findings are refused outright ("must be fixed, never waived"); only `minor`/`nit` findings still `open` are eligible, and a non-empty `note` explaining why is required. The ledger row moves `open -> waived` (no task status change) and a `task.finding_waived` audit event records the decision. See `docs/rag/roles/auditor.md`.
 
 ## `ceo_reject` specifically
 
@@ -80,6 +84,7 @@ The CEO acts through the panel, not a gateway verb — there is no agent-facing
 - `docs/rag/roles/cell-pm.md` / `docs/rag/roles/main-pm.md` — `request_changes` in practice
 - `docs/rag/roles/developer.md` — resolving a bounce with `resolved_findings`
 - `docs/rag/roles/ceo.md` — `ceo_reject`
+- `docs/rag/roles/auditor.md` — `waive_finding`
 - `docs/rag/lifecycle/intent-verbs.md` — the canonical verb reference
 - `docs/rag/standards/conventions.md` — the unrelated `convention_findings` concept
 - `docs/map/review-findings.md` — the implementation map (code-facing, not agent-facing)

docs/rag/architecture/video-engine.md

@@ -26,7 +26,7 @@ All three open a normal, **assigned** UX/UI authoring task (balanced across the
 
 ## Artifact verification (request_render)
 
-Authoring is gated on the RENDERED artifact, not just its source: the `request_render` do-tool (developer/QA) renders the caller's actual composition through the sidecar and extracts evenly spaced keyframe PNGs to a container-shared `.previews/` path, returning their absolute paths in the envelope's `evidence.frames`. The agent must Read every frame and verify each scene/feature from the brief appears fully and legibly — a 14-second cut that only ever shows its first scene is exactly what this catches. A developer renders their own working tree (worktree-aware, `head_sha`/`dirty` provenance stamped); QA renders a read-only `git archive` export of the assembled branch — never a working tree. A successful render stamps the task's `render_preview` marker, and `i_am_done` on a video-authoring task refuses without it (`Requirement.RENDER_VERIFIED`, mirrored in the possibilities-matrix fast path), so no video task can complete on a source-only self-review. QA's `claim_review` evidence carries a `video_context` block (composition id + the dev's stamped preview + an instruction to re-render the branch state) so the reviewer checks output, not source.
+Authoring is gated on the RENDERED artifact, not just its source: the `request_render` do-tool (developer/QA) renders the caller's actual composition through the sidecar and extracts evenly spaced keyframe PNGs to a container-shared `.previews/` path, returning their absolute paths in the envelope's `evidence.frames`. The agent must Read every frame and verify each scene/feature from the brief appears fully and legibly — a 14-second cut that only ever shows its first scene is exactly what this catches. A developer renders their own working tree (worktree-aware, `head_sha`/`dirty` provenance stamped); QA renders a read-only `git archive` export of the assembled branch — never a working tree. A successful render stamps the task's `render_preview` marker, and `i_am_done` on a video-authoring task refuses without it (`Requirement.RENDER_VERIFIED`, mirrored in the possibilities-matrix fast path — see `docs/rag/architecture/possibilities-matrix.md`), so no video task can complete on a source-only self-review. QA's `claim_review` evidence carries a `video_context` block (composition id + the dev's stamped preview + an instruction to re-render the branch state) so the reviewer checks output, not source.
 
 ## Render loop and the sidecar
 

docs/rag/architecture/workspaces.md

@@ -103,7 +103,7 @@ If `auto_clone=True` and workspace doesn't exist, it's created on first access.
 
 ## Authentication
 
-HTTPS repositories require a GitHub PAT configured on the project:
+HTTPS repositories require a git token configured on the project — the field is historically named for GitHub PATs but works unchanged for a project registered against Gitea or GitLab (`projects.git_provider`):
 
 - **Token configured**: Auto-clone works, git operations succeed
 - **Token missing**: Error "Project requires a git token for HTTPS repositories"