Merge pull request #406 from githubnext/codex/install-evergreen

Install Evergreen agentic workflow

Author: mrjf

.github/workflows/evergreen.lock.yml

@@ -0,0 +1,15 @@
+# Evergreen CI Activation Policy
+
+Use existing CI as the source of truth. Readiness requires configured gates to
+pass on the current PR head in GitHub.
+
+Default order:
+
+1. Wait for pending checks.
+2. Rerun failed or stale checks when supported and allowed.
+3. Dispatch configured workflows when allowed.
+4. Use an empty trigger commit only when repo policy requires a push event and
+   the configured token may push to the PR branch.
+
+Do not rerun green checks. Do not count empty trigger commits as semantic repair
+attempts.

.github/workflows/evergreen.md

@@ -0,0 +1,13 @@
+# Evergreen Labels
+
+Default labels:
+
+| Label | Owner | Meaning |
+| --- | --- | --- |
+| `evergreen` | Human | Persistent opt-in for greenkeeping work. |
+| `evergreen-ready` | Deterministic controller | Configured gates pass for the current PR head. |
+| `evergreen-blocked` | Orchestrator | A blocker exists, but future work may still be useful. |
+| `evergreen-human-needed` | Orchestrator | A human decision, credential, review, or protected edit is needed. |
+| `evergreen-exhausted` | Orchestrator | Per-PR quota is exhausted. |
+
+Update labels only when underlying state changes.

.github/workflows/shared/evergreen/ci-activation.md

@@ -0,0 +1,18 @@
+# Evergreen Memory Policy
+
+Memory is for future-useful facts, not run logs.
+
+Store:
+
+- merge gates and branch protection expectations
+- label meanings
+- CI failure signatures
+- known flaky checks and rerun policy
+- reusable accepted fixes
+- review patterns that affect mergeability
+- skill outcomes
+- velocity metrics
+- per-PR blockers and attempts to avoid
+
+Do not store secrets, raw logs, large diffs, or stale speculation. Write small,
+structured, source-aware entries.

.github/workflows/shared/evergreen/labels.md

@@ -0,0 +1,20 @@
+# Evergreen Orchestrator Policy
+
+The orchestrator removes merge blockers; it does not perform general code
+review. The deterministic readiness controller owns readiness state. The
+orchestrator may repair, wait, report blockers, request human input, update
+non-ready state labels, write memory, dispatch workflows, and push to the PR
+branch only when the installed repo policy allows those actions.
+
+Order work by current evidence:
+
+1. Trust and label eligibility.
+2. Current-head gate state.
+3. Branch freshness or merge conflicts.
+4. Deterministic commands.
+5. Targeted repair skills.
+6. Safe output verification.
+7. Memory and concise reporting.
+
+Stop rather than improvising when a gate depends on a human-owned decision,
+credential, protected edit, ambiguous policy, or repeated failure signature.

.github/workflows/shared/evergreen/memory-policy.md

@@ -0,0 +1,17 @@
+# Evergreen Quota Policy
+
+Quota is per PR and per continuous application of the opt-in label.
+
+Quota starts when the label is applied, continues across runs while the label
+remains, and stops when the PR becomes ready, the label is removed, or exhausted
+state is reached. New commits do not reset quota by themselves.
+
+On exhaustion:
+
+1. Stop work immediately.
+2. Request removal of the opt-in label.
+3. Request addition of the exhausted label.
+4. Leave one terse comment.
+5. Record future-useful memory.
+
+Hard-cap errors from the AI engine are terminal for the current quota window.

.github/workflows/shared/evergreen/orchestrator-policy.md

@@ -0,0 +1,178 @@
+# Evergreen Repo Policy
+
+Confirmed install-time decisions for `githubnext/tsessebe`. The deterministic
+readiness controller and the agentic orchestrator must both respect this file.
+
+## Merge Gates
+
+- Required checks: none are enforced by branch protection (`main` is not
+  protected). The following CI checks are treated as configured merge gates:
+  - `Test & Lint`
+  - `Playground E2E (Playwright)`
+  - `Build`
+  - `Validate Python Examples`
+- Non-required checks treated as gates: the four checks above.
+- Not a gate: `OpenEvolve benchmark` — it runs only on `autoloop/*-evolve` PRs,
+  reports `neutral` when there is no fitness, and is not a mergeability blocker.
+- Review requirements: none required (no branch protection, no required reviews).
+- CODEOWNERS requirements: none.
+- Unresolved thread policy: not a merge gate. Do not chase review threads.
+- Draft PR policy: do not mark drafts ready for review. Monitor only.
+- Required labels: `evergreen` opts a PR into the work loop.
+- Blocker labels: `evergreen-blocked`, `evergreen-human-needed`.
+- Deployment/environment gates: none.
+- Auto-merge behavior: GitHub auto-merge is ENABLED on the repository. Evergreen
+  never merges directly, but by making the configured gates pass it can
+  indirectly cause a PR with auto-merge armed to merge. This is accepted by the
+  repository owner.
+
+## Readiness Controller
+
+- Ready label: `evergreen-ready`.
+- Controller owns ready label: yes.
+- Add ready label only when: all four configured gate checks report success for
+  the current PR head SHA, there are no pending/failing checks, and the merge
+  state is not dirty/conflicted.
+- Remove ready label when: the controller state is anything other than `ready`
+  (new head SHA, pending, failing, missing check, conflict, out of scope).
+- Current-head SHA policy: readiness is evaluated only against the current PR
+  head SHA. A new push invalidates prior readiness.
+- Pending check policy: `waiting` — do not repair pending or in-progress checks.
+- Missing/stale check policy: `needs_ci` — reactivate the latest `CI` run for the
+  head SHA once (see CI/CD Activation). Never rerun green checks.
+- Branch freshness ready criterion: not required to be up to date with `main`;
+  freshness is only enforced when the branch is conflicted (`DIRTY`/`UNKNOWN`).
+- Additional deterministic ready criteria: PR open, has `evergreen`, not
+  `evergreen-exhausted`, allowed by the trust model.
+
+## Branch Updates
+
+- Base branch: `main`.
+- Freshness requirement: not a standalone gate; only merge `main` when the branch
+  is behind and conflicted or CI requires a fresh merge.
+- Merge-main policy: allowed. Prefer ordinary merge commits from `main`.
+- Rebase or force-push policy: force-push is DISABLED. No rebasing history.
+- Fork PR behavior: do not merge `main` into or push to fork branches unless a
+  trusted maintainer has approved the current head (see Trust Model).
+
+## Trust Model
+
+- Repository visibility: public.
+- Fork PR policy: fork PRs are accepted.
+- Are PR branch pushers trusted: not for fork PRs.
+- Default trust level:
+  - Same-repo branches (e.g. `autoloop/*`, maintainer branches): `trusted-branch`.
+  - Fork PRs: `metadata-only` until a trusted maintainer approves the current
+    head SHA.
+- Current-head approval policy: for fork PRs, run PR code / push repairs only
+  after a trusted maintainer approves via `workflow_dispatch` bound to the
+  current head SHA. A new head SHA returns the PR to metadata-only monitoring.
+- Authorized `/evergreen` users: slash commands are not wired in v1. Trusted
+  activation for fork PRs is via manual `workflow_dispatch`.
+- What invalidates approval: any new commit / head SHA change on the PR branch.
+
+## Event Fast Paths
+
+- `pull_request` activity types: `labeled`, `synchronize`, `reopened`,
+  `ready_for_review`.
+- Default-branch `push` policy: `push` to `main` wakes the reconciliation loop
+  because it can make labeled PRs stale or conflicted.
+- `workflow_run` policy: not wired in v1; the schedule + `synchronize` cover CI
+  state changes.
+- Review event policy: not wired (reviews are not merge gates here).
+- Deployment event policy: not wired (no deployment gates).
+- Slash-command policy: not wired in v1.
+- Schedule interval: every 15 minutes (reconciliation and fork-PR fallback).
+
+## CI/CD Activation
+
+- Workflows/checks Evergreen may rerun: the `CI` workflow run for the current
+  head SHA (via `gh run rerun --failed`, falling back to a full rerun).
+- Workflows/checks Evergreen may dispatch: none by name in v1; activation is
+  rerun-based only.
+- Stale check policy: reactivate the latest `CI` run for the head SHA once per
+  head; never rerun green checks; never re-trigger an already in-progress run.
+- Missing check policy: if no `CI` run exists for the head SHA, wait for the
+  normal `pull_request`/schedule CI to start rather than forcing activation.
+- Empty commit policy: empty trigger commits are a last resort only, requested
+  through safe outputs by the agent (never from preflight) and labeled
+  `evergreen: trigger CI`; they do not count as semantic repair attempts.
+- Token policy: `GITHUB_TOKEN` for reads and control-plane label writes.
+  `GH_AW_CI_TRIGGER_TOKEN` (existing PAT) is used by gh-aw for pushes so that PR
+  branch pushes trigger CI (default-token pushes do not).
+
+## Repair Policy
+
+- Allowed edits: source, tests, playground, config, and workflow files needed to
+  clear a configured gate. Keep changes small and targeted (one feature/fix per
+  commit per repo convention).
+- Protected files: `README.md` and `.autoloop/programs/**` must not be modified
+  unless explicitly requested. `.autoloop/**` and `memory/autoloop` branch state
+  are Autoloop-owned. Issue #1 (program definition) must not be modified.
+- High-risk file policy: dependency manifests and lockfiles (`package.json`,
+  `bun.lock`, `bunfig.toml`) may be edited only when the failing gate requires
+  it; prefer deterministic tooling.
+- Deterministic commands (repo-native, run before agentic edits):
+  - Install: `bun install`
+  - Typecheck: `bun run typecheck`
+  - Lint: `bun run lint`
+  - Test: `bun test`
+  - Cross-validation: `bun test ./tests/xval/`
+  - E2E: `bun run test:e2e`
+  - Golden snapshots: `python golden/generate.py`
+  - Workflow compile: `gh aw compile` (and `apm compile` when APM sources change)
+- Generated file policy: recompile committed lockfiles/snapshots when their
+  sources change. After editing any `.github/workflows/*.md` workflow, recompile
+  and commit the generated `.lock.yml`.
+- Signed commit policy: signed commits are not required. Use the token's natural
+  identity; add Evergreen context in the commit body.
+
+## Review Policy
+
+- Reviewer request policy: do not request or re-request reviewers.
+- Review thread policy: do not resolve threads. Comment only when a thread maps
+  to a configured merge gate.
+- Human-needed cases: protected-file edits, credential/permission needs, fork-PR
+  code execution before approval, and disallowed operations.
+- Comment style: terse. Comment only for meaningful work, blockers, human-needed
+  decisions, or quota exhaustion. Do not comment on unchanged state.
+
+## Skills
+
+- Vendored generic skills: all files under
+  `.github/workflows/shared/skills/`.
+- Existing repo skills to reuse: none dedicated to mergeability were found;
+  respect `AGENTS.md`/`CLAUDE.md` conventions.
+- Conditional skills enabled: `playground-e2e-diagnoser` (Playwright E2E gate),
+  `autoloop-coordinator` (Autoloop branches), `lint-policy-review`,
+  `docs-release-gate-repair`, `dependency-gate-repair`, and other conditional
+  skills when evidence identifies the matching gate.
+- Skills not to use: none disabled.
+
+## Quotas
+
+- Per-PR AIC/token/cost budget: 50000 AI credits per continuous application of
+  the `evergreen` label.
+- Max runs: bounded by the per-PR budget; cheap deterministic monitoring should
+  consume little or no quota.
+- Max repeated attempts per failure signature: do not retry the same failure
+  signature indefinitely; record it in memory and stop.
+- Wall-clock limit: none beyond the per-PR budget and schedule cadence.
+- Exhaustion behavior: remove `evergreen`, add `evergreen-exhausted`, leave one
+  terse comment. A human may reapply `evergreen` for a fresh quota.
+
+## Discovered Repo Context
+
+- Agent guidance: `AGENTS.md` and `CLAUDE.md` — Bun + strict TypeScript, zero
+  core deps, 100% coverage, one feature per commit, never modify `README.md` or
+  `.autoloop/programs/**`, recompile gh-aw/apm after workflow edits.
+- Existing workflow conventions: gh-aw workflows (`autoloop`, `goal`,
+  `ci-doctor`, `agentics-maintenance`) use `engine: copilot` with
+  `COPILOT_GITHUB_TOKEN`; `GH_AW_CI_TRIGGER_TOKEN` PAT is used for CI-triggering
+  pushes. CI workflow name is `CI`.
+- Last 50 closed PR process scan: PRs merge without auto-merge requests or
+  required reviews; many are Autoloop/goal automation PRs labeled
+  `automation`/`autoloop`. No CODEOWNERS or required-review process observed.
+- Uncertainties: `main` has no branch protection, so gate enforcement relies on
+  this policy's configured checks rather than platform-required checks. If branch
+  protection is added later, sync `REQUIRED_CHECKS_JSON` in `evergreen.md`.

.github/workflows/shared/evergreen/quota-policy.md

@@ -0,0 +1,13 @@
+# Evergreen Report Template
+
+Use short reports. Prefer no comment when state has not changed.
+
+Required fields when commenting:
+
+- Current blocker or action.
+- Evidence source.
+- What changed, if anything.
+- What happens next.
+
+Avoid broad narration. Do not say a fix landed, a check is green, or a PR is
+ready unless the relevant GitHub state proves it.

.github/workflows/shared/evergreen/repo-policy.md

@@ -0,0 +1,21 @@
+# Evergreen Safe Output Policy
+
+Allowed safe outputs in v1:
+
+- PR comments for meaningful work, blockers, human-needed decisions, quota
+  exhaustion, or verified state changes.
+- Non-ready state labels.
+- PR branch pushes for PRs that still have the opt-in label and satisfy trust
+  policy.
+- Workflow dispatch or rerun according to repo policy.
+- Pull request reviews or review comments only when configured.
+
+Disallowed safe outputs in v1:
+
+- Direct PR merge.
+- Base-branch writes.
+- Adding or removing the ready label from the agentic workflow.
+- Secret disclosure in comments, logs, commits, generated policy, or memory.
+
+Every safe output must be verified before the orchestrator describes it as
+successful.