# AgentRegenService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/api/src/docs-pr/agent-regen.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/docs-pr/agent-regen.service.ts#L37)

Rung-2 — behavior-aware regeneration. For a change that alters BEHAVIOR without altering the
public signature (a new guard clause → 409, a changed default, a new error path) — which the
deterministic Rung-1 renderer can't see — an autonomous agent reads the actual changed code and
rewrites the page to reflect current behavior; a verifier then scores confidence.

Guardrails (this writes behavioral claims into real PRs, so it is conservative):
 - OFF by default (env `DOCS_PR_RUNG2` !== 'true') → returns null, caller uses Rung-1.
 - confidence below τ, empty output, or ANY error → returns null (fall back to Rung-1).
Mirrors the proven doc-automation agent-writer/verifier pattern (agent-core AgentSession).

NOT yet wired into the live docs-pr path — that needs Phase A (escalation trigger + a
clone at PR time) and the Phase C eval before turn-on. See docs/rung-2-investigate-spec.md.

`AgentRegenService` provides an optional, behavior-aware documentation regeneration path for docs PRs. When enabled, it uses an autonomous agent to inspect changed implementation code, rewrite documentation for behavior changes that signature-based rendering cannot detect, and verify the generated result against a confidence threshold. It is deliberately fail-safe: disabled mode, low confidence, empty output, or any error returns `null` so callers can fall back to deterministic Rung-1 rendering.

## Methods

| Method | Signature | Returns |
|---|---|---|
| `regenerate` | `regenerate(input: AgentRegenInput, optedIn: unknown)` | `Promise<AgentRegenResult | null>` |

## Dependencies

- `ConfigService`

## Where it refuses work

- `AgentRegenService` stops the work with an early return when `!this.enabled && !optedIn`.
- `AgentRegenService` stops the work with an early return when `!after`.

## When something fails

- `AgentRegenService` handles failure in 1 place: it turns it into a return value in all 1.

## Diagram

```mermaid
sequenceDiagram
  participant Caller as Docs PR Pipeline
  participant Regen as AgentRegenService
  participant Agent as AgentSession Writer
  participant Verifier as AgentSession Verifier
  participant Rung1 as Deterministic Rung-1

  Caller->>Regen: regenerate(...)
  Regen->>Regen: Check DOCS_PR_RUNG2

  alt Rung-2 disabled
    Regen-->>Caller: null
    Caller->>Rung1: Render deterministic docs
  else Rung-2 enabled
    Regen->>Agent: Read changed code and rewrite page
    Agent-->>Regen: Proposed documentation

    alt Empty output or agent error
      Regen-->>Caller: null
      Caller->>Rung1: Render deterministic docs
    else Valid proposal
      Regen->>Verifier: Score generated behavioral claims
      Verifier-->>Regen: Confidence score

      alt Confidence below threshold or verifier error
        Regen-->>Caller: null
        Caller->>Rung1: Render deterministic docs
      else Confidence accepted
        Regen-->>Caller: AgentRegenResult
      end
    end
  end
```

## Usage

```ts
import { AgentRegenService } from './agent-regen.service';

async function regenerateDocs(
  agentRegenService: AgentRegenService,
  input: Parameters<AgentRegenService['regenerate']>[0],
) {
  const rung2Result = await agentRegenService.regenerate(input);

  if (rung2Result) {
    // Use the verified behavior-aware page rewrite.
    return rung2Result;
  }

  // Rung-2 is disabled, failed, or lacked sufficient confidence.
  // Continue with the deterministic renderer.
  return renderRung1Documentation(input);
}
```

## AI Coding Instructions

- Keep `regenerate()` fail-safe: return `null` for disabled configuration, invalid or empty agent output, low verifier confidence, and all unexpected errors.
- Treat generated behavioral claims as untrusted until verification succeeds; do not bypass the confidence threshold for convenience.
- Preserve the Rung-1 fallback contract—callers must be able to continue deterministic rendering whenever this service returns `null`.
- Gate all Rung-2 execution behind `DOCS_PR_RUNG2 === 'true'`; this capability is intentionally off by default.
- Do not wire this directly into the live docs-PR path without the required escalation trigger, PR-time clone support, and Phase C evaluation.

## Relationships

- DEPENDS_ON → `configservice`

## Referenced By

- `DocsPrModule` (MODULE_PROVIDES)
- `DocsPrService` (DEPENDS_ON)