Task
Session
Run
Attempt
Step
ToolCall
Artifact
Patch
VerificationReport
JudgeReport
Verdict

User: Upgrade dependency ini.
Agent: Done, ini PR-nya.

Apa intent awalnya?
Run mana yang mengeksekusi?
Attempt mana yang crash?
Step mana yang mengedit file?
Tool apa yang dipakai?
Artifact mana yang membuktikan test lulus?
Patch mana yang dikirim ke PR?
Verdict siapa yang menyatakan layak?

One Task can have many Runs.
One Run can have many Attempts.
One Attempt can have many Steps.
One Step can have zero or many ToolCalls.
One Run can produce zero or one final Patch.
One Run can have multiple Artifacts.
One Run ends with one effective Verdict.

Task: upgrade Jackson in payments-service
Run 1: execution spec for base commit abc123
Attempt 1: worker crash after clone
Attempt 2: worker re-runs and completes

Apa pekerjaan yang diminta?
Untuk repository atau target apa?
Dengan scope apa?
Siapa pemiliknya?
Autonomy level apa?
Kenapa pekerjaan ini ada?

{
  "taskId": "task_01J...",
  "createdBy": "user_123",
  "source": "cli",
  "taskType": "dependency_upgrade",
  "title": "Upgrade Jackson to 2.17.x in payments-service",
  "instruction": "Upgrade Jackson from 2.15.x to 2.17.x and fix compile/test failures.",
  "repository": "payments-service",
  "baseRef": "main",
  "autonomyLevel": "supervised_pr",
  "status": "accepted"
}

public record Task(
    TaskId id,
    TaskSource source,
    ActorId createdBy,
    TaskType type,
    String title,
    String instruction,
    RepositoryRef repository,
    GitRef baseRef,
    AutonomyLevel autonomyLevel,
    TaskStatus status,
    Instant createdAt,
    Map<String, String> labels
) {}

public enum TaskStatus {
    DRAFT,
    ACCEPTED,
    POLICY_DENIED,
    READY_FOR_RUN,
    RUNNING,
    COMPLETED,
    FAILED,
    CANCELLED,
    ARCHIVED
}

Task instruction cannot be empty.
Task repository must be resolved before READY_FOR_RUN.
Task policy denial must include reason.
Task cancellation must stop scheduling new runs.
Task does not store raw step logs.

User: Upgrade Jackson.
System: Repo mana?
User: payments-service dulu.
System: Boleh auto-PR kalau test lulus?
User: Ya, tapi jangan ubah infra.

Session: migrate logging across backend services
Task 1: migrate payments-service
Task 2: migrate invoice-service
Task 3: migrate identity-service

Session A: task dibuat
Session B: user approve scope tambahan
Session C: reviewer minta run ulang setelah base branch update

public record Session(
    SessionId id,
    ActorId owner,
    SessionSource source,
    List<TaskId> relatedTasks,
    Instant createdAt,
    Instant lastActivityAt,
    SessionStatus status
) {}

public record SessionMessage(
    SessionId sessionId,
    MessageId id,
    MessageRole role,
    String content,
    Instant createdAt,
    Map<String, String> metadata
) {}

Session text may be messy.
Task must be structured.
Session can contain discussion.
Task must contain executable intent.

Untuk task ini, dengan base commit ini, policy ini, budget ini, dan verifier ini,
apakah agent berhasil menghasilkan patch yang layak?

public record Run(
    RunId id,
    TaskId taskId,
    RunNumber number,
    RunStatus status,
    ExecutionSpecSnapshot executionSpec,
    PolicyDecisionSnapshot policyDecision,
    GitCommit baseCommit,
    Budget budget,
    Instant createdAt,
    Instant startedAt,
    Instant completedAt,
    FailureSummary failureSummary
) {}

public enum RunStatus {
    CREATED,
    QUEUED,
    LEASED,
    PREPARING_WORKSPACE,
    RUNNING_AGENT,
    VERIFYING,
    JUDGING,
    COMPLETED,
    FAILED,
    CANCELLED,
    EXPIRED,
    NEEDS_APPROVAL
}

Run belongs to exactly one Task.
Run must have immutable execution spec.
Run must bind to a base commit before execution.
Run must not be completed without final verdict.
Run can fail without patch.
Run can complete with patch but still be not eligible for PR.

Run 12
- Attempt 1: worker node died
- Attempt 2: sandbox startup failed
- Attempt 3: completed, verifier passed

public record Attempt(
    AttemptId id,
    RunId runId,
    int attemptNumber,
    WorkerId workerId,
    LeaseId leaseId,
    AttemptStatus status,
    Instant startedAt,
    Instant lastHeartbeatAt,
    Instant endedAt,
    String failureCode
) {}

public enum AttemptStatus {
    STARTING,
    ACTIVE,
    COMPLETED,
    FAILED,
    LEASE_EXPIRED,
    CANCELLED
}

Only one active attempt per run is allowed.
Every worker event must be associated with current attempt/lease.
Expired attempt cannot complete the run.
Infrastructure failure can create new attempt.
Semantic failure should not be retried blindly.

Apa yang terjadi, urutannya bagaimana, berapa lama, dan hasilnya apa?

public record Step(
    StepId id,
    RunId runId,
    AttemptId attemptId,
    int sequenceNumber,
    StepType type,
    StepStatus status,
    String title,
    Instant startedAt,
    Instant endedAt,
    Map<String, Object> attributes,
    List<ArtifactRef> artifacts
) {}

public enum StepType {
    PREPARE_WORKSPACE,
    CLONE_REPOSITORY,
    LOAD_CONTEXT,
    MODEL_PLANNING,
    TOOL_CALL,
    APPLY_PATCH,
    RUN_VERIFIER,
    SUMMARIZE_LOG,
    JUDGE_DIFF,
    COLLECT_ARTIFACTS,
    FINALIZE
}

public enum StepStatus {
    STARTED,
    SUCCEEDED,
    FAILED,
    SKIPPED,
    DENIED,
    TIMED_OUT
}

Step sequence number increases within an attempt.
Step status is append-only or transition-validated.
Failed step must include failure code or artifact.
Tool call step must reference ToolCall record.
Long output must be artifact, not only attribute.

public record ToolCall(
    ToolCallId id,
    StepId stepId,
    String toolName,
    String argumentsJson,
    ToolDecision decision,
    String denialReason,
    ToolResult result,
    Instant requestedAt,
    Instant completedAt
) {}

public enum ToolDecision {
    ALLOWED,
    DENIED_BY_POLICY,
    DENIED_BY_PATH_GUARD,
    DENIED_BY_COMMAND_GUARD,
    DENIED_BY_BUDGET,
    REQUIRES_APPROVAL
}

No side effect without ToolCall.
Every ToolCall must be validated before execution.
Denied ToolCall is still recorded.
Tool output must be bounded, redacted, and attributable.
ToolCall arguments must not contain secrets unless explicitly allowed.

Mana bukti konkret dari klaim agent?

public enum ArtifactType {
    PATCH_UNIFIED_DIFF,
    PATCH_SUMMARY,
    TOUCHED_FILES,
    COMMAND_LOG,
    TEST_REPORT,
    BUILD_REPORT,
    STATIC_ANALYSIS_REPORT,
    MODEL_TRANSCRIPT_SUMMARY,
    VERIFIER_REPORT,
    JUDGE_REPORT,
    COST_REPORT,
    FAILURE_REPORT,
    PR_BODY_DRAFT
}

public record Artifact(
    ArtifactId id,
    RunId runId,
    AttemptId attemptId,
    StepId producedByStep,
    ArtifactType type,
    String uri,
    String sha256,
    long sizeBytes,
    RedactionStatus redactionStatus,
    ArtifactVisibility visibility,
    Instant createdAt,
    Map<String, String> metadata
) {}

public enum ArtifactVisibility {
    INTERNAL_ONLY,
    VISIBLE_TO_REQUESTER,
    SAFE_FOR_PR,
    SAFE_FOR_PUBLIC_LOG
}

Artifact must have content hash.
Artifact must have type.
Artifact must have producer.
Large data must be stored outside primary DB.
Artifact visibility must be explicit.
Unsafe artifact must not be copied into prompt or PR body.

public record Patch(
    PatchId id,
    RunId runId,
    GitCommit baseCommit,
    ArtifactRef unifiedDiffArtifact,
    List<FileChange> fileChanges,
    PatchStats stats,
    PatchBoundaryCheck boundaryCheck,
    PatchApplyStatus applyStatus,
    Instant createdAt
) {}

public record FileChange(
    String path,
    ChangeType changeType,
    int additions,
    int deletions,
    boolean generated,
    boolean binary,
    boolean lockfile,
    boolean testFile,
    boolean forbiddenByPolicy
) {}

public enum ChangeType {
    ADDED,
    MODIFIED,
    DELETED,
    RENAMED,
    COPIED
}

public record PatchBoundaryCheck(
    boolean passed,
    List<String> allowedPathViolations,
    List<String> forbiddenPathViolations,
    List<String> unexpectedGeneratedFiles,
    List<String> unexpectedLockfileChanges
) {}

Patch must be tied to base commit.
Patch must have boundary check before PR.
Patch with forbidden path violation cannot be auto-PR.
Patch that cannot apply cleanly is not eligible.
Patch stats must be computed deterministically from diff.

public record VerificationReport(
    VerificationReportId id,
    RunId runId,
    VerificationStatus status,
    List<VerificationCheck> checks,
    ArtifactRef fullReportArtifact,
    Instant startedAt,
    Instant endedAt
) {}

public record VerificationCheck(
    String name,
    String command,
    VerificationCheckStatus status,
    int exitCode,
    Duration duration,
    ArtifactRef logArtifact,
    String summarizedFailure,
    boolean required
) {}

public enum VerificationStatus {
    NOT_RUN,
    PASSED,
    FAILED,
    PARTIAL,
    TIMED_OUT,
    INFRA_FAILURE,
    SKIPPED_BY_POLICY
}

Required verifier failure blocks auto-PR.
Verifier command must come from verification plan.
Verifier output must be captured as artifact.
Verifier summary must cite concrete failing command/check.
Infra failure is not the same as code failure.

public record JudgeReport(
    JudgeReportId id,
    RunId runId,
    JudgeStatus status,
    List<JudgeFinding> findings,
    double confidence,
    ArtifactRef reportArtifact,
    Instant createdAt
) {}

public record JudgeFinding(
    Severity severity,
    String category,
    String message,
    String filePath,
    Integer lineNumber,
    boolean blocksAutoPr
) {}

public enum JudgeStatus {
    NOT_RUN,
    PASSED,
    PASSED_WITH_WARNINGS,
    FAILED,
    NEEDS_HUMAN_REVIEW,
    INCONCLUSIVE
}

Judge cannot override deterministic policy failure.
Judge report must be stored as artifact.
Low confidence judge cannot enable auto-PR.
Judge should evaluate diff against task intent and patch boundary.
Judge must not see secrets or unsafe artifacts.

public record Verdict(
    VerdictId id,
    RunId runId,
    VerdictStatus status,
    PrEligibility prEligibility,
    List<String> reasons,
    List<ArtifactRef> evidence,
    Instant decidedAt
) {}

public enum VerdictStatus {
    SUCCESS,
    SUCCESS_NEEDS_REVIEW,
    FAILED_AGENT_COULD_NOT_COMPLETE,
    FAILED_VERIFICATION,
    FAILED_POLICY,
    FAILED_INFRASTRUCTURE,
    CANCELLED,
    INCONCLUSIVE
}

public enum PrEligibility {
    ELIGIBLE_FOR_AUTO_PR,
    ELIGIBLE_AFTER_HUMAN_APPROVAL,
    DRAFT_ONLY,
    NOT_ELIGIBLE
}

Every terminal run must have verdict.
Verdict must list reasons.
Verdict must reference evidence artifacts.
Auto-PR eligibility requires deterministic checks to pass.
Human approval can allow PR, but cannot erase audit reasons.

PR bukan bagian dari execution plane.
PR adalah downstream action berdasarkan Verdict.

{
  "type": "dependency_upgrade",
  "repository": "payments-service",
  "instruction": "Upgrade Jackson to 2.17.x and fix compile/test failures.",
  "autonomyLevel": "supervised_pr"
}

{
  "runId": "run_001",
  "taskId": "task_001",
  "baseCommit": "abc123",
  "status": "RUNNING_AGENT",
  "executionSpec": {
    "allowedPaths": ["pom.xml", "src/**", "test/**"],
    "forbiddenPaths": ["infra/**", ".github/**"],
    "verificationCommands": ["mvn -q test"]
  }
}

1. clone repository
2. inspect pom.xml
3. patch dependency version
4. run mvn test
5. read compile error
6. patch failing imports
7. run mvn test again
8. collect diff
9. generate final summary

- patch.diff
- mvn-test-attempt-1.log
- mvn-test-attempt-2.log
- touched-files.json
- verifier-report.json
- judge-report.json

Changed:
- pom.xml
- src/main/java/.../ObjectMapperConfig.java
- src/test/java/.../SerializationTest.java
Boundary: passed
Stats: +18 / -9

mvn -q test: passed

passed_with_warnings
Warning: changed one production config class; reviewer should inspect serialization behavior.

SUCCESS_NEEDS_REVIEW
PR eligibility: ELIGIBLE_FOR_AUTO_PR or ELIGIBLE_AFTER_HUMAN_APPROVAL depending policy
Evidence: patch.diff, verifier-report.json, judge-report.json

{
  "passed": false,
  "forbiddenPathViolations": [".github/workflows/deploy.yml"]
}

FAILED_POLICY
PR eligibility: NOT_ELIGIBLE
Reason: patch touches forbidden path .github/workflows/deploy.yml

{
  "name": "mvn-test",
  "status": "INFRA_FAILURE",
  "exitCode": 1,
  "summarizedFailure": "Dependency download failed with repository timeout."
}

FAILED_INFRASTRUCTURE
PR eligibility: NOT_ELIGIBLE
Retry: allowed with backoff

FAILED_VERIFICATION
Reason: unit test failed due to assertion mismatch after code change
Retry: not automatic unless agent has remaining repair budget

task_01JZ9T...
run_01JZ9V...
attempt_01JZ9W...
step_01JZ9X...
artifact_01JZ9Y...
patch_01JZ9Z...

{
  "taskId": "task_01JZ9T",
  "runId": "run_01JZ9V",
  "attemptId": "attempt_01JZ9W",
  "stepId": "step_01JZ9X",
  "event": "tool_call_denied",
  "tool": "shell.run",
  "reason": "command_not_allowed"
}

TaskSubmitted
TaskAccepted
RunCreated
RunQueued
LeaseAcquired
WorkspacePrepared
StepStarted
ToolCallRequested
ToolCallDenied
ToolCallCompleted
PatchProduced
VerifierStarted
VerifierCompleted
JudgeCompleted
VerdictDecided
PrRequested
PrCreated
RunCompleted

libs/domain/src/main/java/dev/agent/domain/
  ids/
  task/
  session/
  run/
  attempt/
  step/
  tool/
  artifact/
  patch/
  verification/
  judge/
  verdict/
  event/

domain/
  ids/
    TaskId.java
    RunId.java
    AttemptId.java
  task/
    Task.java
    TaskStatus.java
    TaskType.java
  run/
    Run.java
    RunStatus.java
    ExecutionSpecSnapshot.java
  step/
    Step.java
    StepType.java
    StepStatus.java
  artifact/
    Artifact.java
    ArtifactType.java
  patch/
    Patch.java
    FileChange.java
    PatchBoundaryCheck.java
  verdict/
    Verdict.java
    VerdictStatus.java
    PrEligibility.java

public record SubmitTaskRequest(
    String repository,
    String baseRef,
    String taskType,
    String instruction,
    List<String> allowedPaths,
    List<String> forbiddenPaths,
    String autonomyLevel
) {}

public record Task(
    TaskId id,
    TaskSource source,
    ActorId createdBy,
    TaskType type,
    String title,
    String instruction,
    RepositoryRef repository,
    GitRef baseRef,
    AutonomyLevel autonomyLevel,
    TaskStatus status,
    Instant createdAt,
    Map<String, String> labels
) {}

public record ExecutionSpec(
    RunId runId,
    RepositoryRef repository,
    GitRef baseRef,
    PatchBoundary patchBoundary,
    ToolPolicy toolPolicy,
    VerificationPlan verificationPlan,
    Budget budget
) {}

public final class RunFactory {
    public Run createRun(Task task, PolicyDecision policy, RepositorySnapshot repo) {
        if (task.status() != TaskStatus.READY_FOR_RUN) {
            throw new IllegalStateException("Task is not ready for run");
        }
        if (!policy.allowed()) {
            throw new IllegalStateException("Policy denied task");
        }
        return Run.created(
            RunId.newId(),
            task.id(),
            policy.toExecutionSpecSnapshot(repo),
            policy.snapshot(),
            repo.baseCommit(),
            Instant.now()
        );
    }
}

public final class VerdictDecider {
    public Verdict decide(
        Run run,
        Patch patch,
        VerificationReport verification,
        JudgeReport judge
    ) {
        if (!patch.boundaryCheck().passed()) {
            return Verdict.failedPolicy(run.id(), patch.boundaryCheck().reasons());
        }
        if (verification.status() != VerificationStatus.PASSED) {
            return Verdict.failedVerification(run.id(), verification.failureReasons());
        }
        if (judge.status() == JudgeStatus.FAILED) {
            return Verdict.needsReview(run.id(), judge.blockingReasons());
        }
        return Verdict.success(run.id(), PrEligibility.ELIGIBLE_FOR_AUTO_PR);
    }
}

Task without repository cannot become READY_FOR_RUN.
Policy denied task cannot create run.
Run cannot complete without verdict.
Expired attempt cannot submit successful result.
Patch touching forbidden path produces FAILED_POLICY verdict.
Required verifier failure blocks auto-PR.
Judge warning changes eligibility to needs review if policy requires strict judge.
Artifact without hash is rejected.
ToolCall denied by command guard is recorded but not executed.

Migrate all uses of oldFeatureFlagClient.isEnabled(flag) to newFeatureFlags.evaluate(flag, context) in payments-service. Add or update tests. Do not touch infra, deployment, or workflow files. Open PR only if mvn test passes.

Task:
- type: api_migration
- repo: payments-service
- instruction: migrate oldFeatureFlagClient usage
- autonomy: supervised_pr

PatchBoundary:
- allowed: src/**, test/**, pom.xml if needed
- forbidden: infra/**, .github/**, deployment/**

VerificationPlan:
- mvn -q test

Artifacts:
- patch.diff
- touched-files.json
- mvn-test.log
- verifier-report.json
- final-summary.md

SUCCESS:
- patch exists
- boundary passed
- mvn test passed
- judge passed or warning allowed

FAILED_POLICY:
- patch touches forbidden path

FAILED_VERIFICATION:
- required mvn test fails because of code/test failure

SUCCESS_NEEDS_REVIEW:
- tests pass but judge flags semantic risk or broad API behavior change

Session -> Task -> Run -> Attempt -> Step -> ToolCall/Artifact
Run -> Patch -> VerificationReport -> JudgeReport -> Verdict -> PR decision