Date: 2026-08-20

Status: In progress; Gates 0–11 complete locally, Gate 12 cloud and live cleanup proof pending

Status: In progress; Gates 0–11 complete locally, Gate 12 cloud proof pending,

Gate 13 live deployment pending, and the Gate 14 harness complete locally

## Outcome

every failed first attempt has a documented cause and successful corrective

verification.

### Gate 14 implementation status

Implemented locally on 2026-08-20:

- Added a versioned matrix with 69 uniquely identified cases across all 10

  Gate 14 groups. Every case declares whether its execution is automated,

  hybrid, or manual.

- Added a private report generator that binds the complete result set to one

  candidate Git SHA, application and builder manifest digest, release, SBOM,

  and exact-SHA local gate receipt.

- Added a bounded public staging smoke runner for health, status, favicon,

  public pages, CSP nonce binding, and the microphone permissions policy. Its

  receipt retains only status codes, content types, byte counts, policy

  booleans, and hashes—not response bodies or header values.

- Added a fail-closed evidence scanner, append-only attempt recorder, report

  validator, and atomic state finalizer. Failed attempts remain in the report

  after a successful retry. Evidence must remain inside the report directory,

  match its checksum, use owner-only permissions, and pass the private-content

  scan.

- Added contract tests and included shell syntax plus the harness suite in the

  owned contracts stage. The local dry run proves all 69 cases are present,

  unsafe evidence is refused without echoing its value, and a draft cannot pass

  regression validation.

- Added the [staging regression runbook](operations/staging-regression.md) and

  [evidence report contract](operations/staging-report-template.md), including

  persistent-session handling, revision binding, fake-media voice checks,

  exact-window operational truth, retries, finalization, and manifest-scoped

  cleanup.

The harness dry run and focused tests pass without a network request. Gate 14

itself remains open until Gate 12 isolation and Gate 13 deployment complete and

all applicable cases pass live on one candidate. No staging or production

resource changed while implementing the harness.

## Gate 15: Run failure injection and soak staging

After functional regression passes, test the system under controlled failure.

- [x] Boot convergence controls readiness.

- [ ] Relup and rolling replacement pass their staging drills.

- [x] Owned local gates produce exact-SHA receipts.

- [x] The versioned staging matrix, private evidence report, scanner, recorder,

      validator, and network-free harness dry run exist.

- [ ] Web and distributed staging are isolated from production.

- [ ] Staging has a separate database instance and failure domain.

- [ ] The migration lineage is mapped and rehearsed for every nonempty target.

# Run the staging regression and retain safe evidence

Date: 2026-08-20

Status: Harness implemented and locally proven; live Gate 14 execution pending

Use this runbook to test one immutable candidate on the isolated staging

environment and produce one checksummed report. The harness covers every Gate

14 case, preserves failed attempts, refuses incomplete reports, and keeps raw

product content and credentials out of retained evidence.

This runbook never authorizes a production action. Its only network target is

`https://staging.openagents.com`.

## Understand the harness boundary

The harness provides these controls:

- `regression-matrix.json` defines 69 cases in 10 groups.

- `regression.sh check` validates the matrix, report generator, validator,

  evidence scanner, and public-smoke preflight without making a network request.

- `new-report.sh` binds a report to the exact candidate manifest and its image,

  release, SBOM, and release-gate digests.

- `run-public-smoke.sh` makes bounded anonymous requests and retains only status,

  type, size, policy booleans, and response hashes.

- `record-result.sh` appends attempts and copies sanitized, hashed evidence into

  the private report directory.

- `finalize-report.sh` changes report state only after strict validation passes.

The scripts do not claim that browser, account, data-rights, voice, database,

forge, log, failure-injection, or accessibility checks happened. An operator or

owned test runner must execute those cases and attach bounded proof.

## Meet the prerequisites

Start only after Gates 12 and 13 produce all of the following:

- A dedicated staging project, network, database instance, web lane,

  distributed fleet, deployer, identities, secrets, buckets, and registry.

- A clean `main` commit with an exact local release-gate receipt.

- An immutable candidate directory produced by `publish-candidate.sh`.

- A completed migration classification, snapshot, copy rehearsal, migration

  receipt, and rollback-compatibility receipt for the actual staging target.

- Web and distributed nodes reporting the same candidate Git SHA and digest.

- A manifest-scoped disposable test run registered for every account,

  repository, recording, and product machine that the regression creates.

Keep the candidate directory private under `.git`. Confirm its checksum before

each use. Install `curl`, `jq`, `sha256sum`, `strings`, and a current browser test

runner on the owned test machine.

Do not start Gate 14 if the candidate changed, staging shares any production

failure domain, or the retained authenticated browser session cannot be safely

recovered.

## Prove the local harness

Run the complete network-free dry check:

```sh

ops/staging/regression.sh check

```

Expected result:

```text

Staging regression harness dry run passed (69 cases; no network requests sent).

```

Also run `mix precommit` and the exact-SHA release gate for the candidate. Do

not turn a failed local check into a staging-only exception.

## Create one report for the candidate

Choose a unique lowercase run ID. Point the generator at the exact candidate

directory:

```sh

candidate_sha=$(git rev-parse HEAD)

candidate_dir=".git/openagents/staging-candidates/$candidate_sha"

run_id="gate14-20260820-0001"

ops/staging/new-report.sh "$candidate_dir" "$run_id"

```

The report is created with mode `0600` at:

```text

.git/openagents/staging-reports/<candidate-sha>/<run-id>/

  report.json

  report.sha256

```

Do not move the working report into the source tree. Retain the final sanitized

report and evidence in the staging-only versioned evidence bucket after its

scanner and checksum pass.

Verify the draft before testing:

```sh

report=".git/openagents/staging-reports/$candidate_sha/$run_id/report.json"

ops/staging/validate-report.sh --draft "$report"

```

Confirm that the target, Git SHA, application and builder image digests,

release, SBOM, and release-gate digest match the candidate under test.

## Preserve browser and revision state

Use an incognito or isolated browser context for anonymous checks. Keep the

owned persistent staging browser profile for authenticated checks. Do not log

out that profile unless the operator has separately proved that it can be

restored without exposing a user credential.

After every deployment, hard-reload each persistent tab before testing. An

open LiveView can remain connected to a draining old revision, which makes a

new feature appear broken and invalidates revision-bound evidence. Confirm the

new revision from `/status` before the first authenticated action.

Record one UTC test window for each attempt. Do not combine evidence from an old

revision, a different image digest, or a different database state.

## Run the bounded public smoke

Write the smoke receipt outside the report, then attach it through the recorder:

```sh

smoke_root=$(mktemp -d /tmp/openagents-public-smoke.XXXXXX)

smoke_receipt="$smoke_root/public-smoke.json"

ops/staging/run-public-smoke.sh --run "$candidate_dir" "$smoke_receipt"

ops/staging/record-result.sh \

  "$report" public-001 passed public-smoke "$smoke_receipt"

```

The smoke checks `/healthz`, `/status`, `/api/status`, `/favicon.ico`, `/`,

`/leaderboard`, `/changelog`, `/docs`, and `/components`. JSON endpoints must

report the candidate SHA. The home response must bind the CSP nonce to the

theme bootstrap and publish the microphone permissions policy. The receipt

contains no response bodies or header values.

The receipt proves all of `public-001` and only the automated portions of

`public-002` and `public-005`. Complete the configured forge, browser-policy,

cookie, origin, image, microphone, and manual browser checks before marking

those hybrid cases passed.

## Record every attempt

Attach one sanitized evidence file to each passed attempt:

```sh

ops/staging/record-result.sh \

  "$report" chat-001 passed browser-assertions /path/to/sanitized-receipt.json

```

For a failure or block, put the bounded explanation in a mode-`0600` text file.

Do not include a prompt, message, transcript, memory value, credential, raw

request, or personal data:

```sh

reason_file=$(mktemp /tmp/openagents-staging-reason.XXXXXX)

chmod 600 "$reason_file"

# Write a short operational cause into $reason_file with an editor.

ops/staging/record-result.sh \

  "$report" chat-001 failed browser-assertions \

  /path/to/sanitized-receipt.json "$reason_file"

```

After correction, record a new passed attempt. The first failure and its proof

remain in the attempt list:

```sh

ops/staging/record-result.sh \

  "$report" chat-001 passed browser-assertions \

  /path/to/corrective-verification.json

```

Mark a case not applicable only when the architecture makes the case genuinely

inapplicable, not when a dependency is unavailable or a check is inconvenient:

```sh

ops/staging/record-result.sh \

  "$report" CASE_ID not_applicable /path/to/bounded-reason.txt

```

The recorder scans the source, copies it as mode `0600`, computes its SHA-256,

updates the report atomically, and reruns draft validation. It refuses edits to

a regression-passed or complete report. Adding a corrective attempt to a

`recorded` report returns it to `draft` and preserves the previous attempts.

## Execute groups in dependency order

Run the groups in this order so a lower-level failure does not contaminate a

higher-level result:

| Order | Group | Cases | Primary proof |

| --- | --- | ---: | --- |

| 1 | Public and browser | 6 | Public smoke, anonymous browser, policy and accessibility receipts |

| 2 | Authentication | 5 | OAuth boundary tests, retained-session checks, account-state receipts |

| 3 | Typed chat and Markdown | 6 | Browser assertions, persisted turn receipts, bounded failure checks |

| 4 | Memory and data rights | 6 | UI assertions, export/reset/delete receipts, scoped database counts |

| 5 | Voice and recording | 12 | Fake-media results, request statuses, generation and recording receipts |

| 6 | Leaderboard and admin | 6 | Anonymous field checks, authorization checks, operator receipts |

| 7 | Issues and Projects | 6 | API and LiveView checks, cross-repository refusal receipts |

| 8 | Machines and work | 5 | Pairing lifecycle, real harmless job, restart and cleanup receipts |

| 9 | Forge and deployment | 11 | Git, WAL, build, rollback, relup, and rolling-replacement receipts |

| 10 | Logs and truth | 6 | Exact-window log summary, content scan, and bounded database truth |

Use `ops/staging/regression-matrix.json` as the canonical case inventory. Never

delete, rename, or merge cases in a report. Change the versioned matrix and its

contract tests in a dedicated source commit if the product contract changes.

## Exercise authenticated and destructive flows safely

Use only staging-owned accounts and resources registered to the current run.

Confirm the authenticated owner before export, reset, or deletion. Verify the

reset through `#reset-conversation-form`, then confirm one greeting and no

remaining message or memory rows for that owner. Never infer deletion from the

UI alone.

Run cross-account and cross-repository checks with two staging-owned identities.

Prove refusal with statuses and bounded row counts. Do not capture access tokens,

session cookies, OAuth codes, CSRF values, response bodies, or database values.

For machine tests, keep claim and machine credentials only in process memory.

Use a harmless disposable project, revoke the machine, prove replay refusal,

and remove its ephemeral controller home and project before cleanup.

## Exercise voice with fake media

Use an owned browser harness with a synthetic audio fixture and fake-media

browser flags. Store authentication in the private browser profile, not in the

script or evidence. Only one tab may own the active voice call.

Assert these observable outcomes:

- `#voice-start`, `#voice-status`, and `#voice-end` remain usable.

- The call progresses through listening, speaking, interruption, and clean end.

- Call creation returns `201` and final deletion returns `204`.

- Typed input during voice persists without ending the call or starting a

  competing typed response.

- The next spoken response can use the injected typed content.

- Recording disclosure exists before microphone access.

- Recording chunks and completion use the admitted generation.

- An operator can play the assembled recording and an unauthorized account

  cannot.

- Recorder failure leaves both live voice and typed chat usable.

Refresh chat after the harness exits and verify durable transcript items and

interruption markers. Evidence should contain selector states, request status

codes, timestamps, sizes, generations, and hashes—not audio, transcript text,

SDP, provider events, or cookies. Retry a transient harness failure at most once

and preserve both attempts.

## Bind operational truth to the test window

Query logs for the exact candidate revision and UTC attempt window. Inspect

both severity errors and application error text because they can use different

log severities. Separate deployment-overlap connection noise from candidate

regressions by revision and timestamp; do not dismiss unexplained errors as

expected noise.

Export only a bounded summary with counts, revision, query window, and content

scan result. Run the evidence scanner before attachment:

```sh

ops/staging/scan-evidence.sh /path/to/sanitized-log-summary.json

```

Use direct staging database queries when the UI, cache, and persistence disagree.

Retain schema names, bounded counts, booleans, row ownership IDs hashed for the

run, and transaction timestamps. Never retain raw product columns.

## Complete the report-level evidence

Copy sanitized global receipts under the report's `evidence/` directory with

mode `0600`. Scan and hash each file, then add an evidence reference of this

shape to the matching `staging_evidence` field:

```json

{

  "path": "evidence/migration-rehearsal.json",

  "sha256": "64-lowercase-hex-characters",

  "kind": "migration-rehearsal"

}

```

Populate every field described in the

[staging evidence report contract](staging-report-template.md). Run draft

validation after each reviewable edit. The validator recomputes every referenced

file hash, rejects links and path escapes, requires mode `0400` or `0600`, and

rescans the content.

## Finalize without erasing failures

After the first complete pass, seal a report with failures or blocks as

`recorded`:

```sh

ops/staging/finalize-report.sh --recorded "$report"

```

The command refuses pending cases. Record corrective attempts as needed; each

new attempt returns the report to draft while preserving history.

When every applicable Gate 14 case passes and every common evidence field is

complete, seal the regression result:

```sh

ops/staging/finalize-report.sh --regression "$report"

```

Do not edit a regression-passed report. Gate 15 adds failure-injection timeline,

soak, and known-issue evidence to a reviewed copy, then seals it with:

```sh

ops/staging/finalize-report.sh --final "$report"

```

Verify `report.sha256`, scan the complete report directory, and upload only the

sanitized set to staging evidence storage. A passed Gate 14 report does not

authorize production.

## Clean up the disposable run

Quiesce the harness so it cannot create more resources. Preview the exact

manifest-scoped cleanup:

```sh

ops/staging/cleanup-run.sh "$run_id" check

```

Apply cleanup only after the bounded counts match the run:

```sh

ops/staging/cleanup-run.sh "$run_id" --apply

```

Prove the run manifest is empty, machine credentials no longer work, the

ephemeral controller files are gone, and retained evidence still validates.

Cleanup never converts a failed regression into a pass.

# Staging evidence report contract

Date: 2026-08-20

Status: Current Gate 14 and Gate 15 evidence contract

`ops/staging/new-report.sh` generates the machine-readable report template from

one immutable candidate and the versioned 69-case regression matrix. Keep the

working report private under `.git/openagents/staging-reports/`; retain only a

sanitized, checksummed result in staging evidence storage.

## Report identity

The generator fixes these values. Do not edit them:

- Schema and matrix revision.

- Run ID, creation time, staging target, project, and region.

- Git SHA and `main` branch.

- Candidate-manifest checksum.

- Application and builder image references and manifest digests.

- Release version and checksum.

- SBOM and exact-SHA release-gate checksums.

The application and builder references must end in their recorded manifest

digests. Tags alone are not evidence.

## Result contract

The generator creates one result for each matrix case. Each result keeps its

group, title, execution class, status, reason, attempts, and aggregate evidence.

Allowed statuses are:

- `pending`: no attempt or reason exists.

- `passed`: the last attempt passed and evidence exists.

- `failed`: the last attempt failed, evidence exists, and a reason exists.

- `blocked`: the last attempt was blocked, evidence exists, and a reason exists.

- `not_applicable`: a bounded architectural reason exists.

Attempt ordinals start at 1 and remain contiguous. Every retry appends an

attempt; it never replaces the failed observation. Each attempt records UTC

start and completion timestamps, outcome, retry classification, bounded

explanation, and evidence references.

Use `record-result.sh` instead of hand-editing result arrays.

## Common staging evidence

Gate 14 regression finalization requires all of these fields:

| Field | Required value |

| --- | --- |

| `migration.classification` | `empty_current`, `known_prior`, or `already_baselined` |

| `migration.snapshot_receipt` | Sanitized pre-migration snapshot receipt |

| `migration.rehearsal_receipt` | Disposable-copy rehearsal receipt |

| `migration.migration_versions_receipt` | Exact applied-version receipt |

| `migration.rollback_compatibility_receipt` | Last-known-good compatibility receipt |

| `configuration_readiness_receipt` | Redacted staging-only configuration result |

| `local_gate.default_test_count` | Positive default-suite test count |

| `local_gate.cluster_test_count` | Positive cluster-suite test count |

| `local_gate.javascript_test_count` | Positive browser JavaScript test count |

| `local_gate.coverage_summary_receipt` | Merged bounded coverage receipt |

| `deployment.web_revision` | Exact staging web revision name |

| `deployment.web_image_digest` | Candidate application manifest digest |

| `deployment.distributed_node_release_receipt` | Same-SHA fleet identity receipt |

| `forge.build_receipt` | Immutable builder input and artifact receipt |

| `forge.deployment_receipt` | Transactional fleet deployment receipt |

| `forge.rollback_receipt` | Complete rollback receipt |

| `forge.relup_receipt` | Upgrade, downgrade, and re-upgrade receipt |

| `forge.rolling_replacement_receipt` | Drain-bounded replacement receipt |

| `sanitized_artifacts` | One or more sanitized screenshots, recordings, or UI receipts |

An evidence reference contains only a relative `evidence/` path, SHA-256, and

short kind. Referenced files must be regular, unlinked, mode `0400` or `0600`,

inside the report directory, checksum-correct, no larger than 50 MiB, and safe

under `scan-evidence.sh`.

## Gate 15 evidence

Final completion adds:

- One or more evidence references in `failure_injection_timeline`.

- A 48-hour `soak_receipt` that includes candidate identity, start, end,

  scheduled canary counts, bounded resource summaries, and post-soak smoke.

- Every known issue with ID, owner, severity, and disposition.

An empty known-issue list is valid only when review found no issues. A failure,

retry, crash, stale row, divergent node, leak, or content-bearing log must not

disappear from the timeline because it was later corrected.

## Report states

The validator recognizes four states:

| State | Validator | Meaning |

| --- | --- | --- |

| `draft` | `--draft` | Work is in progress; pending and failed cases may exist |

| `recorded` | `--recorded` | Every case has an outcome; failures or blocks may remain |

| `regression_passed` | `--regression` | Every applicable Gate 14 case passed and common evidence is complete |

| `complete` | `--final` | Gate 14, failure injection, and the 48-hour soak all passed |

Only `finalize-report.sh` should change the state and completion timestamp. It

validates a temporary copy before replacing the report and recomputes

`report.sha256`.

## Prohibited content

Never retain session cookies, OAuth codes, access or refresh tokens, database

passwords, machine credentials, provider keys, private keys, authenticated

database URLs, raw prompts, messages, transcripts, memory values, tool payloads,

SDP, audio, or private administrative content.

Prefer counts, booleans, status codes, timestamps, bounded IDs, digests, and

content hashes. A passing scanner reduces accidental disclosure; it does not

replace human review.

After this boundary exists, use the

[immutable candidate runbook](../../docs/operations/staging-candidate-artifacts.md)

to publish the exact application image, builder image, release archive, SBOM,

and candidate manifest for Gate 13.

and candidate manifest for Gate 13. Use the

[staging regression runbook](../../docs/operations/staging-regression.md) only

after the candidate and selected migration path are proven on this isolated

target.

## Prerequisites

ops/ci/reference-check.sh

sh -n rel/overlays/bin/migration-lineage

sh -n ops/staging/cleanup-run.sh

sh -n ops/staging/finalize-report.sh

sh -n ops/staging/new-report.sh

sh -n ops/staging/publish-candidate.sh

sh -n ops/staging/record-result.sh

sh -n ops/staging/regression.sh

sh -n ops/staging/run-public-smoke.sh

sh -n ops/staging/scan-evidence.sh

sh -n ops/staging/validate-report.sh

elixir ops/ci/docs-check.exs

MIX_ENV=test mix test --warnings-as-errors \

  test/openagents/log_safety_test.exs \

  test/openagents/runtime_config_test.exs \

  test/openagents/staging_cleanup_test.exs \

  test/openagents/staging_candidate_contract_test.exs \

  test/openagents/staging_regression_contract_test.exs \

  test/openagents_web/icon_affordances_test.exs \

  test/openagents_web/icons_test.exs \

  test/openagents_web/ui_test.exs

#!/bin/sh

set -eu

script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

mode=${1:-}

report=${2:-}

case "$mode" in

  --recorded) state=recorded ;;

  --regression) state=regression_passed ;;

  --final) state=complete ;;

  *)

    echo "usage: ops/staging/finalize-report.sh [--recorded|--regression|--final] REPORT" >&2

    exit 64

    ;;

esac

if [ "$#" -ne 2 ] || [ ! -f "$report" ] || [ -L "$report" ]; then

  echo "REPORT must be a regular, unlinked file" >&2

  exit 1

fi

for command_name in jq sha256sum; do

  if ! command -v "$command_name" >/dev/null 2>&1; then

    echo "$command_name is required to finalize a staging report" >&2

    exit 1

  fi

done

report_dir=$(CDPATH= cd -- "$(dirname -- "$report")" && pwd)

report_temp=$(mktemp "$report_dir/.report.XXXXXX")

cleanup() {

  unlink "$report_temp" 2>/dev/null || true

}

trap cleanup EXIT INT TERM

completed_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)

jq --arg state "$state" --arg completed_at "$completed_at" '

  .state = $state |

  .completed_at = $completed_at

' "$report" >"$report_temp"

chmod 600 "$report_temp"

"$script_dir/validate-report.sh" "$mode" "$report_temp" >/dev/null || {

  echo "report remains unchanged because $mode validation failed" >&2

  exit 1

}

mv "$report_temp" "$report"

report_temp=

report_sha256=$(sha256sum "$report" | cut -d ' ' -f 1)

printf '%s  report.json\n' "$report_sha256" >"$report_dir/report.sha256"

chmod 600 "$report_dir/report.sha256"

echo "Staging report finalized as $state."

#!/bin/sh

set -eu

script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

repo_root=$(CDPATH= cd -- "$script_dir/../.." && pwd)

matrix="$script_dir/regression-matrix.json"

mode=${1:-}

umask 077

usage() {

  echo "usage: ops/staging/new-report.sh CANDIDATE_DIRECTORY RUN_ID" >&2

  echo "       ops/staging/new-report.sh --dry-run OUTPUT" >&2

  exit 64

}

for command_name in git jq sha256sum; do

  if ! command -v "$command_name" >/dev/null 2>&1; then

    echo "$command_name is required to create a staging report" >&2

    exit 1

  fi

done

generated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)

write_report() {

  candidate_manifest=$1

  candidate_manifest_sha256=$2

  run_id=$3

  synthetic=$4

  output=$5

  jq -n \

    --slurpfile matrix "$matrix" \

    --slurpfile candidate "$candidate_manifest" \

    --arg run_id "$run_id" \

    --arg created_at "$generated_at" \

    --arg candidate_manifest_sha256 "$candidate_manifest_sha256" \

    --argjson synthetic "$synthetic" '

    ($matrix[0]) as $matrix |

    ($candidate[0]) as $candidate |

    {

      schema: "openagents.staging-report.v1",

      matrix_revision: $matrix.revision,

      state: "draft",

      synthetic: $synthetic,

      run_id: $run_id,

      created_at: $created_at,

      completed_at: null,

      target: {

        environment: "staging",

        base_url: "https://staging.openagents.com",

        project: $candidate.target.project,

        region: $candidate.target.region

      },

      candidate: {

        git_sha: $candidate.git_sha,

        branch: $candidate.branch,

        candidate_manifest_sha256: $candidate_manifest_sha256,

        application_image: $candidate.images.application.reference,

        application_manifest_digest: $candidate.images.application.manifest_digest,

        builder_image: $candidate.images.builder.reference,

        builder_manifest_digest: $candidate.images.builder.manifest_digest,

        release_version: $candidate.release.version,

        release_sha256: $candidate.release.sha256,

        sbom_sha256: $candidate.sbom.sha256,

        release_gate_sha256: $candidate.receipts.release_gate_sha256

      },

      staging_evidence: {

        migration: {

          classification: null,

          snapshot_receipt: null,

          rehearsal_receipt: null,

          migration_versions_receipt: null,

          rollback_compatibility_receipt: null

        },

        configuration_readiness_receipt: null,

        local_gate: {

          default_test_count: null,

          cluster_test_count: null,

          javascript_test_count: null,

          coverage_summary_receipt: null

        },

        deployment: {

          web_revision: null,

          web_image_digest: null,

          distributed_node_release_receipt: null

        },

        forge: {

          build_receipt: null,

          deployment_receipt: null,

          rollback_receipt: null,

          relup_receipt: null,

          rolling_replacement_receipt: null

        },

        sanitized_artifacts: [],

        failure_injection_timeline: [],

        soak_receipt: null,

        known_issues: []

      },

      results: [

        $matrix.groups[] as $group |

        $group.cases[] |

        {

          id: .id,

          group: $group.id,

          title: .title,

          execution: .execution,

          status: "pending",

          reason: null,

          attempts: [],

          evidence: []

        }

      ]

    }

  ' >"$output"

}

if [ "$mode" = "--dry-run" ]; then

  [ "$#" -eq 2 ] || usage

  output=$2

  if [ -e "$output" ]; then

    echo "dry-run report output already exists" >&2

    exit 1

  fi

  dry_root=$(mktemp -d /tmp/openagents-staging-report-dry-run.XXXXXX)

  cleanup() {

    find "$dry_root" -depth -delete 2>/dev/null || true

  }

  trap cleanup EXIT INT TERM

  git_sha=$(git -C "$repo_root" rev-parse --verify HEAD)

  zero_digest=0000000000000000000000000000000000000000000000000000000000000000

  candidate_manifest="$dry_root/candidate-manifest.json"

  jq -n \

    --arg git_sha "$git_sha" \

    --arg digest "sha256:$zero_digest" \

    --arg sha256 "$zero_digest" '

    {

      schema: "openagents.staging-candidate.v1",

      git_sha: $git_sha,

      branch: "main",

      target: {environment: "staging", project: "openagents-staging-dry-run", region: "us-central1"},

      images: {

        application: {

          reference: ("us-central1-docker.pkg.dev/openagents-staging-dry-run/openagents-staging/openagents@" + $digest),

          manifest_digest: $digest

        },

        builder: {

          reference: ("us-central1-docker.pkg.dev/openagents-staging-dry-run/openagents-staging/openagents-builder@" + $digest),

          manifest_digest: $digest

        }

      },

      release: {version: "dry-run", sha256: $sha256},

      sbom: {sha256: $sha256},

      receipts: {release_gate_sha256: $sha256}

    }

  ' >"$candidate_manifest"

  write_report "$candidate_manifest" "$zero_digest" dry-run true "$output"

  chmod 600 "$output"

  exit 0

fi

[ "$#" -eq 2 ] || usage

candidate_dir=$1

run_id=$2

case "$run_id" in

  [a-z0-9]*[a-z0-9]) ;;

  [a-z0-9]) ;;

  *) echo "RUN_ID must use lowercase letters, digits, and interior hyphens" >&2; exit 1 ;;

esac

case "$run_id" in

  *[!a-z0-9-]* | *--* | *- | -* )

    echo "RUN_ID must use lowercase letters, digits, and single interior hyphens" >&2

    exit 1

    ;;

esac

if [ "${#run_id}" -gt 63 ]; then

  echo "RUN_ID must contain at most 63 characters" >&2

  exit 1

fi

candidate_manifest="$candidate_dir/candidate-manifest.json"

candidate_checksum="$candidate_dir/candidate-manifest.sha256"

if [ ! -f "$candidate_manifest" ] || [ ! -f "$candidate_checksum" ]; then

  echo "candidate directory must contain the manifest and its checksum" >&2

  exit 1

fi

(cd "$candidate_dir" && sha256sum --check --strict candidate-manifest.sha256 >/dev/null)

jq -e '

  . as $manifest |

  .schema == "openagents.staging-candidate.v1" and

  (.git_sha | test("^[0-9a-f]{40}$")) and

  .branch == "main" and

  .target.environment == "staging" and

  (.target.project | test("stag"; "i")) and

  (.target.region | type == "string" and length > 0) and

  (.images.application.manifest_digest | test("^sha256:[0-9a-f]{64}$")) and

  (.images.builder.manifest_digest | test("^sha256:[0-9a-f]{64}$")) and

  (.images.application.reference | endswith("@" + $manifest.images.application.manifest_digest)) and

  (.images.builder.reference | endswith("@" + $manifest.images.builder.manifest_digest)) and

  (.release.sha256 | test("^[0-9a-f]{64}$")) and

  (.sbom.sha256 | test("^[0-9a-f]{64}$")) and

  (.receipts.release_gate_sha256 | test("^[0-9a-f]{64}$"))

' "$candidate_manifest" >/dev/null || {

  echo "candidate manifest does not satisfy the staging report contract" >&2

  exit 1

}

git_sha=$(jq -r '.git_sha' "$candidate_manifest")

candidate_manifest_sha256=$(sha256sum "$candidate_manifest" | cut -d ' ' -f 1)

evidence_root="$repo_root/.git/openagents/staging-reports/$git_sha"

report_root="$evidence_root/$run_id"

report_temp=

if [ -e "$report_root" ]; then

  echo "staging report already exists for this candidate and run ID" >&2

  exit 1

fi

umask 077

mkdir -p "$evidence_root"

report_temp=$(mktemp -d "$evidence_root/.report.$run_id.XXXXXX")

cleanup() {

  if [ -n "$report_temp" ] && [ -d "$report_temp" ]; then

    find "$report_temp" -depth -delete 2>/dev/null || true

  fi

}

trap cleanup EXIT INT TERM

write_report \

  "$candidate_manifest" \

  "$candidate_manifest_sha256" \

  "$run_id" \

  false \

  "$report_temp/report.json"

report_sha256=$(sha256sum "$report_temp/report.json" | cut -d ' ' -f 1)

printf '%s  report.json\n' "$report_sha256" >"$report_temp/report.sha256"

mv "$report_temp" "$report_root"

report_temp=

echo "Created staging report for $git_sha"

echo "Report: .git/openagents/staging-reports/$git_sha/$run_id/report.json"

#!/bin/sh

set -eu

script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

usage() {

  echo "usage: ops/staging/record-result.sh REPORT CASE_ID passed EVIDENCE_KIND EVIDENCE_FILE" >&2

  echo "       ops/staging/record-result.sh REPORT CASE_ID failed EVIDENCE_KIND EVIDENCE_FILE REASON_FILE" >&2

  echo "       ops/staging/record-result.sh REPORT CASE_ID blocked EVIDENCE_KIND EVIDENCE_FILE REASON_FILE" >&2

  echo "       ops/staging/record-result.sh REPORT CASE_ID not_applicable REASON_FILE" >&2

  exit 64

}

[ "$#" -ge 4 ] || usage

report=$1

case_id=$2

outcome=$3

if [ ! -f "$report" ] || [ -L "$report" ]; then

  echo "REPORT must be a regular, unlinked file" >&2

  exit 1

fi

for command_name in jq sha256sum; do

  if ! command -v "$command_name" >/dev/null 2>&1; then

    echo "$command_name is required to record a staging result" >&2

    exit 1

  fi

done

case "$case_id" in

  [a-z]*-[0-9][0-9][0-9]) ;;

  *) echo "CASE_ID has an invalid shape" >&2; exit 1 ;;

esac

evidence_kind=

evidence_source=

reason_file=/dev/null

case "$outcome" in

  passed)

    [ "$#" -eq 5 ] || usage

    evidence_kind=$4

    evidence_source=$5

    ;;

  failed | blocked)

    [ "$#" -eq 6 ] || usage

    evidence_kind=$4

    evidence_source=$5

    reason_file=$6

    ;;

  not_applicable)

    [ "$#" -eq 4 ] || usage

    reason_file=$4

    ;;

  *) usage ;;

esac

report_state=$(jq -r '.state // empty' "$report")

case "$report_state" in

  draft) "$script_dir/validate-report.sh" --draft "$report" >/dev/null ;;

  recorded) "$script_dir/validate-report.sh" --recorded "$report" >/dev/null ;;

  *)

    echo "only draft or recorded reports accept result changes" >&2

    exit 1

    ;;

esac

if ! jq -e --arg case_id "$case_id" '

  any(.results[]; .id == $case_id)

' "$report" >/dev/null; then

  echo "CASE_ID is not present in the staging matrix" >&2

  exit 1

fi

if [ "$reason_file" != /dev/null ]; then

  if [ ! -f "$reason_file" ] || [ -L "$reason_file" ]; then

    echo "REASON_FILE must be a regular, unlinked file" >&2

    exit 1

  fi

  reason_size=$(wc -c <"$reason_file" | tr -d ' ')

  if [ "$reason_size" -lt 1 ] || [ "$reason_size" -gt 500 ]; then

    echo "REASON_FILE must contain 1 through 500 bytes" >&2

    exit 1

  fi

  "$script_dir/scan-evidence.sh" "$reason_file" >/dev/null

fi

if ! jq -e -Rs 'rtrimstr("\n") | (length >= 0)' "$reason_file" >/dev/null; then

  echo "REASON_FILE is not valid UTF-8 text" >&2

  exit 1

fi

report_dir=$(CDPATH= cd -- "$(dirname -- "$report")" && pwd)

evidence_dir="$report_dir/evidence"

report_temp=

evidence_destination=

cleanup() {

  if [ -n "$report_temp" ] && [ -f "$report_temp" ]; then

    unlink "$report_temp" 2>/dev/null || true

  fi

  if [ -n "$evidence_destination" ] && [ -f "$evidence_destination" ]; then

    unlink "$evidence_destination" 2>/dev/null || true

  fi

}

trap cleanup EXIT INT TERM

umask 077

mkdir -p "$evidence_dir"

ordinal=$(jq -r --arg case_id "$case_id" '

  (.results[] | select(.id == $case_id) | .attempts | length) + 1

' "$report")

started_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)

completed_at=$started_at

evidence_relative=

evidence_sha256=

if [ "$outcome" != not_applicable ]; then