Merge pull request #5 from fiveonecode/docs/contributing-tracks

Split CONTRIBUTING into public and harness tracks

Author: VladimirBrejcha

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 <files> --session-dir "$HOME/.codex/agent-harness/simulator-broker-app/<session>"
+npm run agent:context -- --paths <files> --session-dir <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 <files> --session-dir "$HOME/.codex/agent-harness/simulator-broker-app/<session>"
+npm run agent:verify -- --profile spec-only --paths <files> --session-dir <session-dir>
 ```
 
 Implementation changes normally require:
 
 ```bash
+npm run agent:verify -- --profile implementation --paths <files> --session-dir <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 <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).

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
 

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
 

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);

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

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

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.