# Feedback Pipeline Explainer

Durable architecture reference for the report -> issue -> agent-session -> PR pipeline, including fork-aware execution and governance controls.

## Formal Pipeline

1. Capture and validate report payload.
2. Resolve issue via dedupe markers (create or update/comment).
3. Plan follow-up: issue-only, issue+PR, or issue+fork.
4. Execute direct SCM operations or spawn agent session for code changes.
5. Link issue/fork/PR and update operation journal.

## Execution Boundaries

- Orchestrator is the only component allowed to perform SCM side effects.
- Optional subagent skill can provide recommendation signals only.
- Policy fallback remains deterministic when subagent output is invalid.

### Trigger Conditions

- Valid report in `mode=scm`.
- Confidence thresholds met.
- Governance allows attempted mutation path.

### Target Selection

- Prefer upstream when writable and policy allows.
- Use fork path when upstream writes are blocked.
- Downgrade to issue-only when neither path is permitted.

### Idempotency

- `dedupeKey` for issue identity.
- `operationKey` per mutation stage.
- Find-or-create semantics before every mutation.

## Consent Gates (Default Policy)

- Outside AO dogfooding, human consent is required for fork creation.
- Outside AO dogfooding, human consent is required for PR creation.
- Outside AO dogfooding, human consent is required before upstream/fork target switch.
- Project-level bypass is allowed only when owner explicitly enables it.

## Journal (Plain Language)

- The journal is a progress log for every report.
- Each mutation updates one tracked record, not separate duplicates.
- Retries keep the same keys and increment attempt metadata.
- Consent outcomes are stored for auditability.

    {
      "dedupeKey": "f4d7dbe5b0f8...",
      "stage": "create_pr",
      "status": "failed",
      "attempt": 2,
      "issueUrl": ".../issues/399",
      "prUrl": null
    }

## PR Requirements

- Issue reference must exist in PR metadata/body.
- Stable lineage markers link issue, session, and PR.
- Existing PR for same dedupe context must be linked, not duplicated.

## Governance Hooks

- canCreateIssue / canCreateFork / canCreatePR / canSpawnSession checks.
- Per-fork-owner allow/deny and optional approval gates.
- Denied operations are journaled with explicit reason codes.