Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: key-files entry for check-dynamic-ci guard

garrytan5cd27ad6dfa5
diff --git a/docs/architecture/key-files/ci-health-and-test-guards.md b/docs/architecture/key-files/ci-health-and-test-guards.md
index 5cb2517c5d..72c1785390 100644
--- a/docs/architecture/key-files/ci-health-and-test-guards.md
+++ b/docs/architecture/key-files/ci-health-and-test-guards.md
@@ -36,4 +36,5 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `scripts/check-skill-refs.mjs` + `scripts/portable-skill-links.ts` + `scripts/skills-commit-gate.sh` — skills-tree integrity gate (`bun run check:skill-refs`, in verify and the skills commit gate). Fails on dangling backtick `skills/` refs, `./`/`../` links, `composes:` and RESOLVER dispatcher slugs; donor-workspace paths outside the shrink-only allowlist; any `gbrain <cmd>` in a fenced line or inline code span (command position only: line/span start, after a shell separator, `nohup`/env prefixes) that is not a real command (union of `--tools-json`, `CLI_FLAG_REGISTRY`, `src/cli.ts` dispatch, the command table and op `cliHints`), plus curated known-bad subcommands (`embed refresh`); and a relative link that resolves outside the skills root, in `skills/` and in the generated `plugin/skills` and `plugin-variants/*/skills` trees (`skills/migrations/**` exempt). W4.7: a tools-json load failure FAILS the CLI lane (`--no-cli-refs` skips it deliberately); links are read in every form (`](./x)`, bare `](x.md)` unless a placeholder, `](<x>)`, titled, `[id]: x` definitions); a `[paid-consent]` lane, migrations included, fails a paid `gbrain` command carrying `--yes`/`--max-usd`/`--max-cost[-usd]` with no ask/agree/approve/consent/confirm/permission wording on its line or the 8 before. `portable-skill-links.ts` is that rule's fix: it points `docs/protocol/AGENT_OPERATOR_v1.md` links at the bundled `skills/conventions/agent-operator-protocol.md` and other repo files at absolute blob URLs derived from `LLMS_REPO_BASE` (raw.githubusercontent base → github.com blob base; default `garrytan/gbrain/blob/master`; a non-https or credentialed value throws via `repoBaseOrThrow`, as in `scripts/llms-config.ts`), retargeting default-base links for forks; `--check` reports pending rewrites. Tests: `test/check-skill-refs.test.ts`, `test/skills-portable-links.test.ts` (scaffold `--all` into a tmp host: 0 broken local links).
- `scripts/check-file-url-pathname.sh` — `check:file-url-pathname` (in verify, #6845): no `.pathname` of a file URL (`import.meta.url).pathname`, `pathToFileURL(...).pathname`) in test/, which keeps `%20` and breaks a checkout under a path with a space; use `fileURLToPath` or `import.meta.dir`. Self-tested via `GBRAIN_GUARD_ROOT` fixtures; skips `test/fixtures/guards/`.
+- `scripts/check-dynamic-ci.ts` — `check:dynamic-ci` (in verify): wiring guard for the Trunk Dynamic CI filter (`dynamic-ci` job in `test.yml` and `scale-tier.yml`; rules in [docs/ci-event-parity.md](../../ci-event-parity.md#trunk-dynamic-ci)). `checkWorkflow()` (pure, over parsed YAML) flags a filter job that can run on an event other than `pull_request`, sits in a workflow without that trigger, is not SHA-pinned, lacks `continue-on-error: true` or a step timeout below the job's, or whose `job-keys` differ from its `outputs`; a gated job whose `if` does not start `!cancelled() && needs.<filter>.outputs.<key> != 'false' &&`, lacks `needs.<other>.result == 'success'` for another need, or has a top-level `||` after the prefix; and a gated merge or release aggregate. `scripts/ci-cheap-tier.sh` accepts a gated lane that skipped only on an exact `false` verdict. Self-tested via `GBRAIN_GUARD_ROOT` fixtures in `test/fixtures/guards/check-dynamic-ci.ts/` (`good`, `bad`, `bad-every-event`, `bad-other-needs`, `bad-top-level-or`).
- `spec/tla/` + `scripts/spec/{tlc.sh,tla-jar.sh,tla-tools.env,mutants.ts}` + `.github/workflows/tla-spec.yml` — TLA+ models checked exhaustively by TLC within small bounds; `spec/tla/drain-lease` models the managed-sync drain lease (`sync-lease.ts` over `db-lock.ts`, plus the pass stamp's fences in `sync-pass-fold.ts` and `sync-prepare.ts`). `tlc.sh` runs every config on a private copy and fails `TLC_VIOLATION`, `TLC_TIMEOUT` or `TLC_ERROR`; `tla-jar.sh` fetches the pinned tla2tools.jar and refuses a sha256 mismatch. `mutants.ts` checks `mutants.json`: each guard mutant's model edit must break its named property, and its code edits (every engine branch), applied in a scratch copy of the tree, must fail each named test on its own assertions; assumption mutants document what liveness rests on, survivors stay defense in depth. `bun run test:tla` runs both; the workflow runs them nightly and on changes to anything a mutant names (`test/spec-drain-lease-constants.test.ts` pins that path filter and the configs' timing to the code's constants). Guard tests: `test/drain-lease-guards.test.ts`, `test/drain-lease-stamp-fence.test.ts` (Postgres twins in `test/e2e/`), `test/e2e/drain-lease-fence-postgres.test.ts`. Docs: `spec/tla/README.md`.