Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .cargo/audit.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,11 @@ ignore = [
# rustyclawd-tools → octocrab → jsonwebtoken → rsa.
# Tracked upstream: https://github.com/RustCrypto/RSA/issues/19
"RUSTSEC-2023-0071",
# RUSTSEC-2026-0204: invalid pointer dereference in the `fmt::Display` impl
# for `Atomic`/`Shared` in `crossbeam-epoch`. Issued 2026-07-06 with no
# fixed upstream release. Transitive dep via
# simard → rustyclawd-tools → moka → crossbeam-epoch. Only reachable by
# `Display`-formatting a null crossbeam `Atomic`/`Shared`, which Simard
# never does. Tracked upstream: https://rustsec.org/advisories/RUSTSEC-2026-0204
"RUSTSEC-2026-0204",
]
7 changes: 7 additions & 0 deletions deny.toml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,13 @@ ignore = [
# exemption in .cargo/audit.toml. Tracked:
# https://github.com/RustCrypto/RSA/issues/19
{ id = "RUSTSEC-2023-0071", reason = "rsa Marvin timing side-channel; no upstream fix; transitive JWT-verify only (rustyclawd-tools->octocrab->jsonwebtoken). Tracked: https://github.com/RustCrypto/RSA/issues/19" },
# crossbeam-epoch — invalid pointer dereference in the `fmt::Display` impl
# for `Atomic`/`Shared` when the pointer is null. Issued 2026-07-06 with NO
# fixed upstream release, so it fails by default and must be exempted here.
# Transitive: simard -> rustyclawd-tools -> moka -> crossbeam-epoch. Only
# reachable by `Display`-formatting a null crossbeam `Atomic`/`Shared`, which
# Simard never does, so the dereference is unreachable in our usage.
{ id = "RUSTSEC-2026-0204", reason = "crossbeam-epoch fmt::Display null-pointer deref; no upstream fix (issued 2026-07-06); transitive via simard->rustyclawd-tools->moka; unreachable (Simard never Display-formats crossbeam Atomic/Shared). Tracked: https://rustsec.org/advisories/RUSTSEC-2026-0204" },
]

# ── Licenses ─────────────────────────────────────────────────────────────────
Expand Down
128 changes: 128 additions & 0 deletions docs/reference/ci-health-sweep.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
title: CI-Health Sweep — Governed-Fleet Reference
description: Reference for simard::ci_health and the `simard ci-health` subcommand — the codified, reproducible governed-fleet CI-health sweep that classifies each default-branch workflow as green, actionable_failure, or ignored(reason).
last_updated: 2026-07-06
review_schedule: as-needed
owner: simard
doc_type: reference
status: implemented
related:
- ./stewardship-api.md
- ../concepts/stewardship-mode.md
- ./cross-repo-merge-authority.md
- ../../src/ci_health/mod.rs
- ../../src/operator_cli/ci_health.rs
---

# CI-Health Sweep — Governed-Fleet Reference

Module: `simard::ci_health`
Source: `src/ci_health/`
CLI: `simard ci-health`

The CI-health sweep is a precise, reproducible check of whether every **active**
default-branch workflow across the amplihack ecosystem (Simard + its governed
sibling repos) is green. It exists so the standing *CI-health stewardship* goal
produces verifiable, re-runnable evidence instead of hand-rolled `gh run list`
claims.

## Why a codified sweep

A naive `gh run list --branch main` sweep cannot distinguish an **actionable
active-CI failure** from a **non-actionable non-green signal**. Two real cases
made that ambiguity concrete:

- **azlin** has seven agentic scheduled workflows (Code Quality Tracker, CI/CD
Workflow Health Monitor, …) whose *latest* default-branch run is `failure` —
but every one is `disabled_manually`. A disabled workflow cannot run again, so
its stale failure is not active CI.
- **agent-kgpacks** "Build Knowledge Pack" latest run is `cancelled`/`skipped` —
a non-failure conclusion, not a broken build.

A sweep that reads only run conclusions either (a) mislabels those as failures,
or (b) glosses over them and claims "every workflow is `success`" — which is
literally false for those latest runs. Carrying the workflow *enablement state*
alongside the run conclusion is what lets the sweep be both correct and honest.

## Classification

For each workflow, the sweep reads its enablement state and the latest run on
the repo's default branch, then classifies it:

| Verdict | Condition |
|---|---|
| `green` | workflow **active** and latest run concluded `success` |
| `actionable_failure` | workflow **active** and latest run concluded `failure`, `timed_out`, or `startup_failure` |
| `ignored` | any of: workflow disabled (`workflow_disabled`); non-failure conclusion such as cancelled/skipped/neutral/action_required/stale (`non_failure_conclusion:<c>`); no default-branch run (`no_default_branch_run`); run not completed (`run_in_progress`) |

The **fleet is green iff it contains zero actionable failures.** Disabled
workflows, cancelled/skipped runs, and in-progress runs never fail the fleet;
an active workflow whose latest run genuinely failed always does.

Classification ([`classify::build_report`]) is a total, pure function over the
[`FleetSnapshot`] — no I/O, no `gh`, no clock — so the verdict is deterministic
and exhaustively unit-tested.

## Module layout

```
src/ci_health/
├── mod.rs public entrypoint, GOVERNED_REPOS, sweep_live/sweep_fixture/report_to_json
├── types.rs WorkflowState, RunConclusion, WorkflowRun/Snapshot, RepoSnapshot, FleetSnapshot
├── classify.rs WorkflowVerdict, IgnoreReason, build_report, FleetReport (serializable DTOs)
├── gh.rs GhWorkflowClient trait, RealGhWorkflowClient, pure parse/join helpers, fixture loader
├── report.rs render_human
└── tests.rs unit tests
```

## `simard ci-health`

```
simard ci-health [--json] [--from-json <path>]

--json Emit the FleetReport as JSON (default: human table).
--from-json <path> Classify an offline snapshot fixture instead of calling
`gh` (the fixture shape mirrors the live snapshot).
```

- Without `--from-json`, the sweep reads live GitHub state via `gh` for every
slug in [`ci_health::GOVERNED_REPOS`]: the repo's default branch
(`gh repo view`), workflow states + ids (`gh workflow list --json name,state,id`), and
the latest default-branch run per workflow
(`gh run list --branch <default> --json workflowName,workflowDatabaseId,status,conclusion,event,createdAt,databaseId`).
Runs are matched to workflows by the unique `workflowDatabaseId`, not the
(non-unique) display name, so two workflow files sharing a `name:` never
collapse onto one run.
Because that branch-wide run list is windowed, any **active** workflow with no
run inside the window is queried directly (`gh run list --workflow <id> --limit 1`)
so a stale failing run of an infrequently-triggered workflow can never be
silently dropped and reported as green.
- **Exit code** follows the verdict: `0` when the fleet is green, non-zero when
any actionable failure exists (mirrors `simard self-health`).

The human report leads with a greppable banner (`CI-HEALTH: GREEN` /
`CI-HEALTH: FAILING`) and a per-repo breakdown; each actionable failure is
hoisted to the top with a direct run URL. The `--json` report is the same data
as a stable `FleetReport` object.

### Governed fleet

`GOVERNED_REPOS` is the source of truth in code for the swept slugs; it mirrors
the ecosystem table in `prompt_assets/simard/engineer_system.md` (note
`amplihack` → `amplihack-rs` on GitHub).

## Reproducing a captured sweep

The offline path makes any sweep reproducible without network access: capture a
snapshot fixture in the shape under `tests/gadugi/fixtures/ci-health-*.json`,
then `simard ci-health --from-json <fixture>`. The gadugi scenario
`tests/gadugi/ci-health-sweep.yaml` uses two committed fixtures to assert that
disabled/cancelled/in-progress signals stay green while a genuine active-CI
failure turns the fleet red.

## Related

- Concept: [Goal Stewardship Mode](../concepts/stewardship-mode.md)
- [Stewardship API](./stewardship-api.md) — orchestrator-failure → issue routing
- [Cross-Repo Merge Authority](./cross-repo-merge-authority.md)
- Source: `src/ci_health/`, `src/operator_cli/ci_health.rs`
30 changes: 25 additions & 5 deletions docs/reference/dependency-trust-policy.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Dependency trust policy
description: "Reference for cargo-vet transitive-dependency trust certification, the supply-chain/ baseline, trusted-crate and exemption criteria, and the advisory-resolution workflow."
last_updated: 2026-06-28
last_updated: 2026-07-06
review_schedule: as-needed
owner: simard
doc_type: reference
Expand Down Expand Up @@ -216,7 +216,7 @@ flowchart TD

### The `rsa` exemption (RUSTSEC-2023-0071)

The one standing exemption is `rsa` / **RUSTSEC-2023-0071** (the "Marvin"
One standing exemption is `rsa` / **RUSTSEC-2023-0071** (the "Marvin"
timing side-channel):

- **No fixed release exists** upstream.
Expand All @@ -231,6 +231,26 @@ It is exempted **once per tool**, with identical justification, in
`.cargo/audit.toml` (existing) and `deny.toml` (added for #2260), and is
re-checked whenever a fixed `rsa` release ships.

### The `crossbeam-epoch` exemption (RUSTSEC-2026-0204)

The second standing exemption is `crossbeam-epoch` / **RUSTSEC-2026-0204**
(invalid pointer dereference in the `fmt::Display` impl for `Atomic`/`Shared`):

- **No fixed release exists** upstream (issued 2026-07-06 with empty
*Patched*/*Unaffected* fields), so it fails `cargo deny check advisories`
and `cargo audit` by default and must be exempted explicitly.
- It reaches the graph **transitively**:
`rustyclawd-tools → moka → crossbeam-epoch`.
- The dereference only occurs when `Display`-formatting a **null** crossbeam
`Atomic`/`Shared`; Simard never formats crossbeam pointers, so the faulty
path is unreachable in Simard's usage.
- Tracked upstream: <https://rustsec.org/advisories/RUSTSEC-2026-0204>.

Like `rsa`, it is exempted **once per tool** with identical justification in
`.cargo/audit.toml` and `deny.toml`, and is re-checked whenever a fixed
`crossbeam-epoch` release (or a `moka`/`rustyclawd-tools` bump that drops it)
ships.

### Transitive unmaintained / unsound advisories

These advisories are *not* vulnerabilities and reach the graph only
Expand Down Expand Up @@ -259,9 +279,9 @@ start failing — a *new* unmaintained advisory landing on a *direct* dependency
or one of these being re-classified as a vulnerability or pulled in directly —
the `workspace` scope forces an explicit decision: carry a *temporary* justified
`ignore` (ID + "via `<upstream>`, no upgrade yet" + tracking link) in `deny.toml`
and `.cargo/audit.toml` until the bump lands. The only **permanent** `ignore` in
the policy remains `rsa` (RUSTSEC-2023-0071), the one advisory with no upstream
fix.
and `.cargo/audit.toml` until the bump lands. The **permanent** `ignore`s in
the policy are `rsa` (RUSTSEC-2023-0071) and `crossbeam-epoch`
(RUSTSEC-2026-0204), the two advisories with no upstream fix.

## Workflow: vetting a crate or resolving an advisory

Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -277,6 +277,7 @@ nav:
- Goal Coverage Allocation: reference/goal-coverage-allocation.md
- spawn_agent_for_goal API: reference/spawn-agent-for-goal.md
- Stewardship API: reference/stewardship-api.md
- CI-Health Sweep: reference/ci-health-sweep.md
- Simard Whisperer API: reference/simard-whisperer-api.md
- Maximum Safe Parallelism: reference/maximum-safe-parallelism.md
- Concurrent Engineer Dispatch: reference/concurrent-engineer-dispatch.md
Expand Down
Loading
Loading