From 5865547bd3e2efdbc9656d80eec1367dc2ec831b Mon Sep 17 00:00:00 2001 From: Vladimir Date: Thu, 3 Sep 2026 19:36:44 +0800 Subject: [PATCH] Document the public tap hosted CI contract Why: - Product specs still described the Homebrew tap as having only a Formula/Cask sync, after the tap gained pull-request style and audit CI. Changed: - Record tap script/verify.sh, brew style/audit, and known Alpha --online findings. - Keep product Autopilot verify.command as npm test. - Lock the contract in the front-door docs tests. Verification: - npm run agent:verify -- --profile spec-only passed. Affected: - spec/build-and-test.md - spec/project-structure.md - spec/agents.md - spec/README.md - docs/status.md - docs/test/front-door.test.mjs - CHANGELOG.md Refs: - https://github.com/fiveonecode/simulator-broker/issues/54 - https://github.com/fiveonecode/homebrew-simulator-broker/pull/3 Session: - task-sessions/tap-hosted-ci-20260903 Co-authored-by: Cursor --- CHANGELOG.md | 6 ++++++ docs/status.md | 3 ++- docs/test/front-door.test.mjs | 24 ++++++++++++++++++++++++ spec/README.md | 4 +++- spec/agents.md | 18 ++++++++++++++++++ spec/build-and-test.md | 8 +++++++- spec/project-structure.md | 3 ++- 7 files changed, 62 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0161e56..30b4fff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- The public Homebrew tap now runs hosted `brew style` / `brew audit` + verification on pull requests and `main`, using the same command as its + Autopilot origin contract. + ## [0.1.0-alpha.7] - 2026-09-01 Alpha 7 keeps the Alpha 6 install and four-custom-asset contract while fixing diff --git a/docs/status.md b/docs/status.md index 5bef1cb..68c552b 100644 --- a/docs/status.md +++ b/docs/status.md @@ -49,7 +49,8 @@ This Alpha already includes: - Homebrew formula `fiveonecode/simulator-broker/simbroker` for the Alpha CLI tarball. Homebrew clones `fiveonecode/homebrew-simulator-broker` for that tap name; `Formula/` and `Casks/` in this repository stay the source of - truth. Packable `simbroker` npm CLI (`npm run package:npm`), and a + truth. That tap runs hosted `script/verify.sh` on pull requests and + `main`. Packable `simbroker` npm CLI (`npm run package:npm`), and a Homebrew cask that installs `Simulator Broker.app` from the signed, notarized GitHub Release zip when that zip is attached - local-debug packaging through `npm run package:local` diff --git a/docs/test/front-door.test.mjs b/docs/test/front-door.test.mjs index 73c6018..fcdf523 100644 --- a/docs/test/front-door.test.mjs +++ b/docs/test/front-door.test.mjs @@ -832,6 +832,30 @@ test("Homebrew one-liner is documented against the homebrew-simulator-broker tap assert.ok(syncScript.includes("Formula/simbroker.rb")); }); +test("public tap hosted CI and Autopilot contract are documented", () => { + const buildAndTest = readRepoFile("spec/build-and-test.md"); + const structure = readRepoFile("spec/project-structure.md"); + const agents = readRepoFile("spec/agents.md"); + const status = readRepoFile("docs/status.md"); + const specIndex = readRepoFile("spec/README.md"); + + for (const body of [buildAndTest, structure, specIndex, status]) { + assert.ok( + body.includes("script/verify.sh"), + "product docs must name the tap verify script", + ); + } + + assert.ok(buildAndTest.includes("brew style")); + assert.ok(buildAndTest.includes("brew audit --strict")); + assert.ok(buildAndTest.includes("empty-livecheck")); + assert.ok(agents.includes("SB-TAP-CI-001")); + assert.ok(agents.includes("SB-TAP-AP-001")); + assert.ok(agents.includes("bash script/verify.sh")); + assert.ok(agents.includes("verify.command` remains `npm test")); + assert.ok(structure.includes("autopilot.yml")); +}); + test("sync_homebrew_tap.sh copies Formula and Casks into a tap checkout", () => { const tapDir = fs.mkdtempSync(path.join(os.tmpdir(), "simbroker-homebrew-tap-")); const init = spawnSync("git", ["init", tapDir], { encoding: "utf8" }); diff --git a/spec/README.md b/spec/README.md index 039df0e..28f2f94 100644 --- a/spec/README.md +++ b/spec/README.md @@ -65,7 +65,9 @@ This repo exists to develop a reusable local simulator broker: - Homebrew formula `Formula/simbroker.rb` and packable npm CLI `packages/simbroker` install the Alpha CLI; cask `Casks/simulator-broker.rb` names the signed, notarized GitHub Release app zip. The tap GitHub name - is `fiveonecode/homebrew-simulator-broker` + is `fiveonecode/homebrew-simulator-broker`. That tap runs hosted + `script/verify.sh` on pull requests and `main` and keeps its own + Autopilot origin contract. - `host init --bootstrap-config` warns that it creates real Simulator devices before provisioning them - broker-aware sample consumer repo artifacts now cover manual human, interactive agent, unattended agent build-and-test, and CI patterns under `examples/harness-adoption/` - broker-aware build/test leases now support downstream process registration, memory ceiling containment, evidence bundles, and forced-abort cleanup for detached simulator-like processes diff --git a/spec/agents.md b/spec/agents.md index 1056aa5..1b150f3 100644 --- a/spec/agents.md +++ b/spec/agents.md @@ -91,6 +91,24 @@ In scope: origin Autopilot verification command, protected verifier paths, and ` Missing origin `autopilot.yml` → Autopilot `waiting_external_prereq` / `external_prereq.missing`. Uncovered or overlapping `autopilot.yml` → spec-only / config-contract fail. +## Public tap Autopilot and CI contract +Related: `fiveonecode/homebrew-simulator-broker` `autopilot.yml`, `script/verify.sh`, `.github/workflows/ci.yml` + +The Homebrew tap is a separate GitHub repository. It does not use this +repository's `autopilot.yml` or `npm test`. + +| ID | Requirement | Verifier | +|----|-------------|----------| +| SB-TAP-AP-001 | Tap origin default branch contains regular-file `autopilot.yml` whose `verify.command` is `bash script/verify.sh` | Tap hosted CI; tap `script/verify.sh` | +| SB-TAP-CI-001 | Tap pull requests and `main` pushes run `script/verify.sh` | Tap `.github/workflows/ci.yml`; tap hosted CI | +| SB-TAP-CI-002 | `script/verify.sh` runs `brew style`, `brew audit --strict` for formula and cask, formula `--online` audit, and cask `--online` audit that fails on any finding other than Alpha GitHub pre-release or empty livecheck | `bash script/verify.sh`; tap hosted CI | +| SB-TAP-AP-002 | Product `autopilot.yml` `verify.command` remains `npm test` | SB-AP-002; `verify:spec-only` | + +Installing the Autopilot or Connector GitHub App on the tap is an operator +org action. This contract does not authorize a product-repo App install to +cover the tap. The reviewer of record for tap pull requests is Bugbot until +those Apps actually run on the tap. + ## Verification model Use `npm run agent:verify -- --profile --paths --session-dir ` for deterministic checks. diff --git a/spec/build-and-test.md b/spec/build-and-test.md index 250e9f0..7978895 100644 --- a/spec/build-and-test.md +++ b/spec/build-and-test.md @@ -87,7 +87,13 @@ A first extracted implementation slice now exists: `fiveonecode/homebrew-simulator-broker`. `scripts/sync_homebrew_tap.sh` copies `Formula/` and `Casks/` into a tap checkout only when `Formula/simbroker.rb` exists. `--check-remote` compares this tree to - the published tap formula and is not part of `spec-only` + the published tap formula and is not part of `spec-only`. The tap's + pull-request and `main` workflow runs `script/verify.sh`: `brew style`, + `brew audit --strict` for the formula and cask, formula `--online` + audit, and cask `--online` audit that may report only the known Alpha + GitHub pre-release and empty-livecheck findings. That script is also + the tap `autopilot.yml` verify command. Product `spec-only` does not + execute the tap workflow. - `scripts/package_npm.sh` (`npm run package:npm`) packs `packages/simbroker` with a `bin` field; the repo-root package stays `private` - `Casks/simulator-broker.rb` installs `Simulator Broker.app` from diff --git a/spec/project-structure.md b/spec/project-structure.md index d974c36..fae3b8c 100644 --- a/spec/project-structure.md +++ b/spec/project-structure.md @@ -15,7 +15,8 @@ Related: `spec/README.md`, `spec/global-simulator-broker.md`, `references/README - `Formula/` — Homebrew CLI formula for the tagged Alpha tarball. Source of truth for the tap; Homebrew clones `fiveonecode/homebrew-simulator-broker` when a stranger runs - `brew install fiveonecode/simulator-broker/simbroker` + `brew install fiveonecode/simulator-broker/simbroker`. That tap owns + its pull-request CI, `script/verify.sh`, and origin `autopilot.yml`. - `Casks/` — Homebrew cask for the signed, notarized operator app zip. Synced to the same tap. - `packages/simbroker/` — packable npm CLI metadata and `bin` wrapper; the