From 96ab6bb1db12c4197159ba8fb95fa30b2f1f1b2c Mon Sep 17 00:00:00 2001 From: Vladimir Date: Tue, 18 Aug 2026 12:32:03 +0800 Subject: [PATCH] Split CONTRIBUTING into public and harness tracks. Why: A first-time public contributor was told to run agent:context and create a Codex session directory before editing. That blocked small patches that only need Node 20 and the Node test suites. Changed: CONTRIBUTING.md now leads with a public-patches track: Node.js 20 and npm run test:broker-core, test:client, and test:harness-adoption, with no harness session required. The maintainer and agent track still documents agent:context, agent:verify, and agent:complete. Front-door tests read the shipped page for both tracks. Specs and README record the split. Harness enforcement is unchanged. Verification: node --test docs/test/front-door.test.mjs npm run agent:verify -- --profile spec-only --paths CONTRIBUTING.md,docs/test/front-door.test.mjs,README.md,docs/getting-started.md,spec/agents.md,spec/build-and-test.md,spec/README.md --session-dir task-sessions/20260818-contributing-tracks Affected: CONTRIBUTING.md docs/test/front-door.test.mjs README.md docs/getting-started.md spec/agents.md spec/build-and-test.md spec/README.md Refs: https://github.com/fiveonecode/simulator-broker spec/agents.md Session: task-sessions/20260818-contributing-tracks --- CONTRIBUTING.md | 70 +++++++++++++++++++++++------------ README.md | 5 ++- docs/getting-started.md | 2 + docs/test/front-door.test.mjs | 49 ++++++++++++++++++++++++ spec/README.md | 1 + spec/agents.md | 6 +++ spec/build-and-test.md | 7 ++++ 7 files changed, 114 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6580e93..e0a2b1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,56 +2,78 @@ Thanks for taking the time to improve Simulator Broker. -## Setup +This page has two tracks: + +1. **Public patches** — Node.js 20 and the Node test suites. You do not need + the agent harness or a Codex session directory. +2. **Maintainers and agent runs** — the existing `agent:context` / + `agent:verify` / `agent:complete` flow. + +## Public patches + +Use this track for a small public change: a spec tweak, a CLI or broker-core +fix, a doc edit, or a focused app patch. Requirements: -- macOS with Xcode and iOS Simulator support -- Node.js LTS -- `xcodegen` on `PATH` +- Node.js 20 or newer on `PATH` +- macOS with Xcode and iOS Simulator support for work that talks to simulators +- `xcodegen` on `PATH` only if you change or build the macOS app -Install and verify from the repo root: +From the repo root, run the Node suites that match what you changed. These +commands do not go through `agent:*`: ```bash -npm install --package-lock-only -npm run agent:catalog -- --format md -npm test +npm run test:broker-core +npm run test:client +npm run test:harness-adoption ``` -The macOS app project is generated locally and is not checked in: +App work also needs XcodeGen and `npm run test:app`. The full suite is +`npm test`. -```bash -npm run build:app -``` +You do not need to run `agent:context`, `agent:verify`, or `agent:complete`, +and you do not need to create a task session directory. -## Development Workflow +### Pull requests + +- Keep changes focused and reviewable. +- Include tests or explain why a deterministic test is not available. +- Keep private or local context out of committed files. +- Do not commit generated Xcode projects, derived data, local broker state, + credentials, machine-specific paths, or task-session artifacts. + +## Maintainers and agent runs + +Use this track for maintainer work and agent runs that follow the product +harness. Harness enforcement is unchanged: `agent:complete` still requires +structured commits, selected verification profiles, and session artifacts. Before editing, identify the changed paths and create a task session: ```bash -npm run agent:context -- --paths --session-dir "$HOME/.codex/agent-harness/simulator-broker-app/" +npm run agent:context -- --paths --session-dir ``` Run every verification profile reported by the context command. Specs and -harness-only changes normally require: +docs normally require: ```bash -npm run agent:verify -- --profile spec-only --paths --session-dir "$HOME/.codex/agent-harness/simulator-broker-app/" +npm run agent:verify -- --profile spec-only --paths --session-dir ``` Implementation changes normally require: ```bash +npm run agent:verify -- --profile implementation --paths --session-dir npm test ``` -## Pull Requests +Close the session with: -- Keep changes focused and reviewable. -- Include tests or explain why a deterministic test is not available. -- Keep private/local context out of committed files. -- Do not commit generated Xcode projects, derived data, local broker state, - credentials, machine-specific paths, or task-session artifacts. +```bash +npm run agent:complete -- --session-dir +``` -Meaningful task commits should use the structured sections documented in -`AGENTS.md`. +Meaningful task commits use the structured sections documented in +[AGENTS.md](AGENTS.md). diff --git a/README.md b/README.md index d5c138c..ce4acd2 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,9 @@ npm run build:app `install:local` builds the Debug app, installs the CLI, and copies `Simulator Broker.app` to `~/Applications`. -Contributor setup, verification, and pull-request expectations are in -[CONTRIBUTING.md](CONTRIBUTING.md). +Contributor setup is in [CONTRIBUTING.md](CONTRIBUTING.md). A small public +patch uses Node.js 20 and the Node test suites. Maintainers and agent runs +keep the `agent:context` / `agent:verify` / `agent:complete` track. ## Five-minute hello world diff --git a/docs/getting-started.md b/docs/getting-started.md index a387b64..54bfe48 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,6 +5,8 @@ Related: [README](../README.md), [Concepts](concepts.md), [Current capabilities] This page is the newcomer install and first-run guide. Specs under `spec/` remain the implementation contract. `simbroker` help and `simbroker doctor` print human-readable text by default; pass `--json` for machine-readable payloads. +A small public patch follows the public-patches track in +[CONTRIBUTING.md](../CONTRIBUTING.md); it does not require the agent harness. ## Prerequisites diff --git a/docs/test/front-door.test.mjs b/docs/test/front-door.test.mjs index 234c87e..f434646 100644 --- a/docs/test/front-door.test.mjs +++ b/docs/test/front-door.test.mjs @@ -54,6 +54,55 @@ test("README separates use-versus-develop install guidance and includes a hello- assert.ok(readme.includes("simbroker lease acquire")); }); +function headingSection(markdown, heading) { + const marker = `\n## ${heading}\n`; + const start = markdown.indexOf(marker); + if (start === -1) { + return ""; + } + const bodyStart = start + marker.length; + const next = markdown.indexOf("\n## ", bodyStart); + return markdown.slice(bodyStart, next === -1 ? markdown.length : next); +} + +test("CONTRIBUTING leads with a public Node-20 patch track that does not require the harness", () => { + const contributing = readRepoFile("CONTRIBUTING.md"); + const human = headingSection(contributing, "Public patches"); + const firstHeading = contributing.split(/\r?\n/).find((line) => line.startsWith("## ")); + + assert.equal(firstHeading, "## Public patches"); + assert.ok(human.length > 0, "CONTRIBUTING must have a Public patches section"); + assert.ok( + contributing.includes("Node.js 20") || contributing.includes("Node 20") || contributing.includes(">=20"), + "CONTRIBUTING must name Node 20", + ); + assert.ok( + human.includes("npm run test:broker-core") + || human.includes("npm run test:client") + || human.includes("npm run test:harness-adoption") + || human.includes("npm test"), + "public track must name a Node test command that is not agent:*", + ); + assert.equal(human.includes("You do not need to run `agent:context`"), true); + assert.equal(human.includes("$HOME/.codex"), false); + assert.equal(human.includes("npm run agent:context --"), false); + assert.equal(human.includes("npm run agent:verify --"), false); + assert.equal(human.includes("npm run agent:complete --"), false); +}); + +test("CONTRIBUTING keeps a labeled maintainer harness track", () => { + const contributing = readRepoFile("CONTRIBUTING.md"); + const harness = headingSection(contributing, "Maintainers and agent runs"); + + assert.ok(harness.length > 0, "CONTRIBUTING must have a Maintainers and agent runs section"); + assert.ok(harness.includes("agent:context")); + assert.ok(harness.includes("agent:verify")); + assert.ok(harness.includes("agent:complete")); + assert.ok(harness.includes("npm run agent:context --")); + assert.ok(harness.includes("npm run agent:verify --")); + assert.ok(harness.includes("npm run agent:complete --")); +}); + test("README links newcomer docs and embeds a real screenshot file", () => { const readme = readRepoFile("README.md"); const imageMatch = /!\[.*?]\((.*?)\)/.exec(readme); diff --git a/spec/README.md b/spec/README.md index 3c302ff..cea5cb3 100644 --- a/spec/README.md +++ b/spec/README.md @@ -53,6 +53,7 @@ This repo exists to develop a reusable local simulator broker: - app unit tests and the local XcodeGen-driven build/test flow now support build-only reruns, focused `-only-testing` filters, and stable `xcresult` output for runtime triage - local install, local-debug portable packaging, Release distribution packaging, and onboarding flows now exist through `install_local.sh`, `install_local.sh --cli-only`, `package_local.sh`, `package_distribution.sh`, `test:install-smoke`, `test:package-smoke`, `host init --bootstrap-config`, and `project init` - the published onboarding docs now distinguish CLI-only install, repo-local contributor app+CLI install, local-debug portable bundling, and signed distribution packaging; a new login shell should resolve `simbroker` after install without sourcing `env.sh` +- `CONTRIBUTING.md` publishes a public-patch track (Node.js 20 and the Node test suites, no harness session) and a labeled maintainer/agent harness track; `agent:complete` enforcement is unchanged - `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 7a7dbce..b65fa3e 100644 --- a/spec/agents.md +++ b/spec/agents.md @@ -5,6 +5,12 @@ Related: `spec/README.md`, `spec/harness-integration.md`, `spec/build-and-test.m This file defines the intended agent workflow for the bootstrap phase of this repo. +`CONTRIBUTING.md` publishes two tracks. Public patches use Node.js 20 and the +Node test suites (`test:broker-core`, `test:client`, `test:harness-adoption`, +or `npm test`) and do not require `agent:context` or a task session directory. +Maintainers and agent runs still use `agent:context` / `agent:verify` / +`agent:complete`. Harness enforcement in this repository is unchanged. + ## Current routing - `harness-contract` exclusively owns `WORKFLOW.md`, `.agents/`, agent diff --git a/spec/build-and-test.md b/spec/build-and-test.md index 88313fe..81e15fe 100644 --- a/spec/build-and-test.md +++ b/spec/build-and-test.md @@ -77,6 +77,13 @@ The public front door is `README.md` plus `docs/getting-started.md`, `docs/concepts.md`, and `docs/status.md`. Those pages are newcomer guidance. This file remains the contributor and verification contract. +`CONTRIBUTING.md` splits public patches from maintainer and agent runs. A +public patch names Node.js 20 and the Node test suites and does not require +`agent:context` or a Codex session directory. The maintainer track still +documents `agent:context`, `agent:verify`, and `agent:complete`. Harness +enforcement (`agent:complete` structured commits, selected profiles, and +session artifacts) is unchanged. + ## Contributor onboarding contract Use the repo-local contributor flow when the engineer already has this checkout on the target Mac.