# Auto Oncall Services Goal And Boundary

Date: 2026-06-30

## Goal

Build `auto-oncall-services` as an independently deployable TypeScript service
inside this repo.

The service must expose an API that dry-runs analysis for one Jira ticket case.
The MVP API must generate:

- a UUID run id;
- an internal-only analysis markdown result;
- a planned run/workspace link;
- a minimal backend-owned safety decision.

The generated content is internal-only. It must not be sent to customers, close
tickets, or execute production actions without human review.

The current session is staging-only. Production deployment and release flow are
out of scope for this iteration.

## Isolation Boundary

`auto-oncall-services` is a fully isolated subrepo/service.

Required isolation:

- owns its own package manifest, lockfile, source, tests, Dockerfile, and
  deployment manifests;
- does not import code from existing services;
- does not share business logic with `ticket-manager`, `oncall`, or
  `investibook`;
- communicates with other systems only through explicit APIs or events;
- can be deployed independently. The current iteration only validates
  `devops-staging`.

Shared repo infrastructure such as GitHub Actions, app-delivery registration,
ECR, and Kubernetes conventions may be reused as deployment patterns, but not
as business/runtime coupling.

## Investibook Boundary

Investibook may be used only as a design reference.

Allowed:

- compare interaction patterns;
- reuse high-level concepts such as "workspace", "case context", and
  "evidence requests";
- inspect implementation ideas locally when designing this service.

Forbidden:

- importing Investibook code;
- calling Investibook APIs from `auto-oncall-services`;
- requiring `INVESTIBOOK_*` environment variables;
- using Investibook domains as default workspace URLs;
- naming runtime concepts as Investibook-specific when the concept belongs to
  auto-oncall.

The workspace link must be owned by the `auto-oncall-services` boundary. If a
real workspace backend is needed later, it should be exposed through an
auto-oncall-owned interface or adapter, not by making Investibook the default
runtime dependency.

## API Contract

The first API surface is:

- `POST /v1/tickets/analyze`

Input may be either:

- `issueKey`, where the service fetches Jira context itself;
- a full ticket snapshot, for dry runs, tests, and callers that already fetched
  Jira data.

The response must include:

- UUID `runId`;
- normalized `issueKey`;
- `mode=dry_run`;
- `result.decision`;
- `result.summaryMarkdown`;
- `result.workspaceUrl`;
- `result.requestedEvidence`;
- `safety.humanRequired`;
- `safety.blockedReason`.

The MVP response must not expose prototype internals such as `automatable`,
`tLevel`, `dispatchLane`, `scenario`, `confidence`, or detailed risk/rationale
fields as stable API contract.

## Safety Boundary

The service may automate only internal analysis preparation.

Allowed automation:

- read or accept one ticket context through the backend;
- create a UUID run workspace;
- run Codex in dry-run mode over prepared local files;
- prepare an internal-only analysis summary;
- identify missing context at a coarse level;
- produce a planned run/workspace link.

Forbidden automation:

- bulk ticket scan or full backfill;
- metrics/config/log/Clinic/Kubernetes skills;
- agent direct access to Jira or production credentials;
- customer-visible replies;
- Jira writes;
- ticket closure;
- production operations;
- destructive or non-standard actions;
- final conclusions for high-risk cases without human review.

High-risk cases must route to human-led handling. Examples include P0/P1,
critical incidents, data risk, customer escalation, suspected product bugs, and
non-standard or production operations.

## Non-Conforming Items

The implementation must not contain these coupling points when the goal is
considered complete.

Forbidden items:

- `INVESTIBOOK_*` environment variable fallbacks;
- optional Investibook workspace API creation;
- Investibook-specific response names and internal-comment wording;
- staging workspace URL pointing to an Investibook domain.

These are not part of the accepted target architecture.

## Completion Criteria

The goal is complete only when current evidence proves:

- the API exists and analyzes one Jira ticket case;
- the response uses the simple dry-run contract with a UUID `runId`;
- low-risk cases return internal-only markdown and a planned run/workspace link;
- high-risk cases return `human_required` and do not produce customer-ready
  conclusions;
- the service has no direct Investibook runtime dependency;
- the agent runner does not directly access Jira, skills, production
  credentials, or production systems;
- local tests cover the ticket snapshot path, Jira issue-key path, UUID run id,
  and high-risk gating;
- staging deployment runs the expected image and passes a live API smoke test;
- deployment config follows the independent service boundary.