@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/docs/reference/DELIVERY_ONBOARDING.md

@@ -0,0 +1,198 @@
+# Repository delivery configuration
+
+Build initializes the current directory or Git checkout; it does not create a
+remote repository. Provider setup remains machine-level. Runtime initialization
+creates only the state needed to run commands. Explicit `build init` completes
+repository onboarding and can record a delivery policy.
+
+Initialization reports local setup, available verification commands, recorded CI
+intent, and declared services separately. It does not run tests, publish files,
+install review apps, grant permissions, or change billing or branch protection.
+A missing prerequisite is pending setup, not a successful verification. An
+explicit deferral stays quiet; blocked setup is offered again when the relevant
+local prerequisite changes. Remote outages are retried through explicit inspection.
+
+## Declaring stages
+
+Delivery policy lives in `.build-project/config/delivery-policy.json`, with its own
+`schemaVersion: 1`. Existing `.build-project/config/ci-integration.json` keeps its v1
+meaning. Existing repositories need no migration. New features require a Build
+version that supports delivery plans; older versions do not activate them.
+
+Profiles are `existing`, `verified`, and `fast`. They declare owner intent; they
+do not rewrite workflows or weaken host requirements. Stages are `gate`,
+`background`, and `release`. Choose the actual commands and checks for each
+repository rather than inferring that a short test list proves full coverage.
+
+Example owner policy for existing hosted workflows:
+
+```json
+{
+  "schemaVersion": 1,
+  "profile": "fast",
+  "repository": { "host": "github.com", "fullName": "owner/project" },
+  "landingOwner": "native-host",
+  "reviewTiming": "before-merge",
+  "stages": {
+    "gate": {
+      "owner": "github-actions",
+      "scope": "Essential PR checks",
+      "githubActions": {
+        "workflows": [".github/workflows/ci.yml"],
+        "selectedChecks": ["tests"],
+        "events": ["pull_request"]
+      }
+    },
+    "background": {
+      "owner": "github-actions",
+      "scope": "Full compatibility matrix",
+      "githubActions": {
+        "workflows": [".github/workflows/full.yml"],
+        "selectedChecks": ["full"],
+        "events": ["push", "workflow_dispatch"],
+        "ref": "refs/heads/main"
+      }
+    }
+  },
+  "services": {
+    "reviewer": { "id": "selected-reviewer", "recipe": "greptile" }
+  },
+  "repair": { "enabled": false, "maxCandidateAttempts": 2 }
+}
+```
+
+Use your repository identity, workflow paths, check names, events and branch.
+Preview and apply with `build ci plan --delivery-policy <file> --output <plan>`
+and `build ci apply --plan <plan>`. A pending greenfield profile may have an
+empty `stages` object and no repository association. It remains unconfigured
+until the relevant workflows or Local CI configuration exist.
+
+Hosted stage evidence must match the exact commit, event, ref, workflow and
+selected check identities. A gate evaluates its selected checks; background and
+release stages additionally require successful completion of the declared
+workflows. Neutral, skipped or incomplete results are not full validation.
+`--ref` currently supports branch refs. A tag binding is not attested by this
+observer; publishing still requires owner verification of the release commit.
+
+A local stage uses `"local": { "source": "resolved-ci-config" }`. The delivery
+observer does not relabel old Local CI results as new stage proofs. Use ordinary
+`build ci status` for existing Local CI evidence; an unobserved delivery-stage
+proof is explicitly unverified.
+
+`landingOwner` is `native-host`, `build-local-ci`, or `unmanaged`. This records
+the chosen owner; it does not enable a new merge path. Build's existing merge
+handoff still requires Local CI as primary and rejects independently armed
+auto-merge. Review timing is `before-merge`, `background`, or `off`. Verify that
+a background reviewer actually continues after merge before relying on it.
+
+## Service bindings
+
+`services` can name a `reviewer`, `prFixer`, and `mainIncidentExecutor`. Each has
+an owner-selected `id`, optional `recipe`, and optional role. Recipes describe
+documented capabilities and limitations; they do not prove installation,
+entitlement, write access, billing eligibility, or live settings. Inspect them
+with `build ci services --json`.
+
+Recipes currently cover Gitar, Greptile, CodeRabbit, Bugbot and an external
+executor. A review finding, a generated patch, a completed review check and a
+validated merge are different outcomes. Only one executor should write a repair
+branch. Confirm all native recovery paths, not merely an auto-apply switch.
+
+## Background failure intake
+
+After declaring an existing hosted background workflow:
+
+```bash
+build ci plan --incident-intake --output incident-plan.json
+build ci apply --plan incident-plan.json
+```
+
+The reviewed plan creates `.build-project/ci/incident-intake.mjs` and
+`.github/workflows/build-ci-incidents.yml`. Existing differing files are
+preserved and require an owner review. The plan also pins the delivery policy
+and source workflow definitions; changed inputs require a new preview.
+
+Commit the generated files and policy through the repository's normal review
+path. If repository or global ignore rules hide `.build-project`, explicitly stage the
+named generated files; do not change global ignore rules. Publishing activates
+record-only intake, which can create and update issues. No provider is invoked
+merely by generating or applying these files locally.
+
+The host runs the standalone Node script; Build need not be installed on the
+runner. It verifies the source repository, default branch, declared workflow,
+event and failed run before recording an incident. Repeated evidence is grouped
+by workflow and failed job/step scope; that is an operational grouping, not proof
+that every occurrence has the same root cause. The executor must establish the
+cause before editing. Late obsolete failures are not dispatched against newer
+main. A verified resolved episode does not consume a future incident's budget.
+New incident bodies keep the original failure, latest evidence, reservations,
+budgets and verified resolution. Repeated deliveries do not grow comment history.
+Relevant legacy comments are read once and compacted; unrelated closed histories
+are not hydrated. Complete bot-issue pagination has no fixed 2,000-record cutoff.
+
+An incident closes only when its original failing step scope is observed passing
+in a newer run on main's history, after the retained first and latest failure
+revisions. The resolution names the tested commit and observed default-branch
+head; it does not attest later commits. Unknown or skipped
+scope remains awaiting verification. Unrelated failing steps do not keep an
+already resolved scope open. Incident records, not pending workflow jobs, retain
+the queue. GitHub's `queue: max` permits up to 100 waiting jobs; overflow requires
+owner redelivery. Already-recorded issues remain durable; overflow can drop an
+unrecorded intake event, which must be redelivered.
+
+### Optional executor activation
+
+The kit does not provision a coding agent or a merge identity. An owner-provided
+GitHub workflow must accept these string inputs:
+
+- `incident_number`
+- `failure_run_id`
+- `failed_sha`
+- `attempt`
+
+It must implement the approved isolated repair, causal validation, review and
+landing policy. The intake does not infer those capabilities from an identifier.
+Activate only after verifying its permissions, CI triggers, writer ownership and
+billing. Record the service binding, set `repair.enabled: true`, and configure:
+
+- `BUILD_REPAIR_WORKFLOW`: its `.github/workflows/<file>.yml` path.
+- `BUILD_REPAIR_DISPATCH_ENABLED`: `true`.
+- `BUILD_REPAIR_CALLBACK_CONFIGURED`: `true`, only after the completion path is verified.
+
+The generated dispatcher alone has `actions: write`; record-only intake has
+`actions: read`, `contents: read`, and `issues: write`. The completion callback
+also has `pull-requests: read` and `checks: read` to inspect private repair PRs.
+Intake, dispatch and completion callbacks share one repository concurrency group.
+Dispatch rechecks the open incident and current branch before reserving the attempt
+and requesting execution. An unknown
+dispatch outcome is needs-attention, not an automatic retry. A blocked active
+incident prevents another writer from starting.
+
+After an executor run has completed, an authorized completion workflow can
+dispatch `build-ci-incidents.yml` with `incident_number`, `expected_attempt`,
+`executor_run_id`, `outcome` (`retry`, `needs-decision` or `candidate`), and optional
+`repair_pr`. A `candidate` outcome also requires `repair_sha`, matching the open
+repair PR's exact head, and a successfully completed executor. It enters
+`awaiting-verification` without reserving another paid attempt. Dispatch stores
+the GitHub run ID and callbacks must match that bound run and attempt.
+It cannot be sent from inside the still-running executor itself. Successful
+repairs are resolved by the source validation evidence on main. Failed candidates
+return to pending only within the preserved budget; exhaustion needs attention.
+No issue comment can directly dispatch a repair.
+
+To include a post-completion relay, preview incident intake with
+`--executor-workflow-name "Repair executor"`. The name must be explicit and
+distinct from the selected background workflows. The relay records a completed
+executor without a callback as `needs-attention`, including cancellation and
+failure. Its later exact callback can still reconcile the same reservation.
+This opt-in adds one job to the existing incident workflow; record-only plans
+keep three jobs. No additional required merge check is created.
+
+If a merged candidate remains red for the same failure scope, a newer main run
+that contains its merge commit returns the incident to `pending` only while its
+existing attempt budget remains; otherwise it requires attention. A new
+candidate or a completed executor never establishes recovery by itself.
+
+The attempt limit controls dispatch count, not monetary cost. Account-level caps
+and an explicitly approved executor remain the owner's responsibility. There is
+no provider fallback or paid execution from `init`, `doctor`, or status queries.

package/docs/reference/PROVIDER_RELEASE_TIERS.md

@@ -0,0 +1,34 @@
+# Provider Release Tiers
+
+This table is the public-release provider confidence contract. Command tiers
+(`Beta`, `Advanced`, `Internal`) describe CLI surface area; provider release
+tiers describe which local AI providers are expected to carry first-user
+workflows.
+
+`release_status` in `.build-project/config/providers.yaml` is the source of truth.
+`build doctor --matrix` renders the same status next to CLI/auth/runtime
+health, so local readiness can be checked before a run.
+
+## Tier Criteria
+
+| Release status | Criteria |
+| --- | --- |
+| Primary validated | Release-blocking provider path for first-user workflows; validated for the public-release path and expected to carry normal usage. |
+| Supported validated | Validated provider path for supported workflows; ready to use when its local CLI and auth are configured. |
+| Supported beta | Supported provider path with beta caveats; requires local readiness checks and a small runtime smoke before relying on it. |
+| Experimental | Available for exploration but excluded from the validated supported-surface claim. |
+
+## Provider Matrix
+
+| Provider ID | Provider | Release status | Runtime tier | Public-release role |
+| --- | --- | --- | --- | --- |
+| claude | Claude | Primary validated | Supported | Primary workhorse for coding, review, and judge/synthesis workflows. |
+| codex | Codex | Primary validated | Supported | Primary workhorse for coding and CLI-first release workflows. |
+| grok | Grok | Supported validated | Supported | Validated supported path for Grok CLI users with local auth configured. |
+| cursor | Cursor | Supported validated | Supported | Validated supported path for Cursor CLI users with local auth configured. |
+| opencode | OpenCode | Supported validated | Supported | Validated supported path for OpenCode users with upstream auth configured. |
+| gemini | Gemini | Experimental | Experimental | Build's Gemini integration is experimental and no longer being extended; check the vendor's current CLI availability and entitlements before relying on it. Opt-in via provider id or `--include-experimental`. `antigravity` is the better-supported path. |
+| copilot | GitHub Copilot | Experimental | Experimental | Available, but outside the validated public-release matrix. |
+| kiro | Kiro | Experimental | Experimental | Experimental headless provider. |
+| antigravity | Antigravity | Supported validated | Supported | The better-supported alternative to the experimental `gemini` provider; validated 2026-08-27 against authenticated `agy` 1.1.22 with model selection and structured usage telemetry. Passive auth readiness reports `unknown` (no non-interactive `agy` probe); auth errors surface at execution time. |
+| pi | Pi | Supported validated | Supported | Validated supported path for Pi CLI users with a configured backend. Pi is a backend-agnostic host, so cost and capability depend on the operator-configured backend; ratings are deliberately conservative. Validated 2026-07-26 against `pi` 0.82.1 with a cloud Anthropic backend, exercised through `build run` and `build run competition` with incremental streaming. Passive auth readiness reports `unknown` (a local endpoint may need no credential); auth errors surface at execution time and are classified for retry. The local OpenAI-compatible (self-hosted) backend is not yet validated. |

package/docs/reference/SECURITY.md

@@ -0,0 +1,291 @@
+# Security Reference
+
+This reference summarizes Build's public-release security policy and the main
+runtime security boundaries that affect users of the public npm package.
+
+Build telemetry is local-first but can include prompts, repository paths,
+provider metadata, output and error tails, token usage, and costs. See
+[Telemetry And Privacy Reference](TELEMETRY_PRIVACY.md) for storage,
+retention, disable, cleanup, and deletion details. This reference ships with the npm package.
+
+## Reporting Vulnerabilities
+
+Do not open public issues for security vulnerabilities. Report them privately
+through GitHub Security Advisories once the repository is public, or while you
+have access to the private repository:
+
+https://github.com/ebrindley/build/security/advisories/new
+
+The form is unavailable to public package users while the repository is private.
+No public email intake is provided. Bug reports can use repository issues once
+the repository is public; keep sensitive vulnerability details out of public issues.
+
+Include the Build version from `build --version`, your operating system, the
+provider or command involved, and the smallest reproduction you can share
+privately.
+
+The canonical project policy lives in [.github/SECURITY.md](../../.github/SECURITY.md).
+Only the latest published release receives security fixes.
+
+## User Responsibilities
+
+- Keep provider API keys and tokens out of the repository.
+- Prefer provider-native authentication stores over committed environment files.
+- Review generated code and commands before applying changes from untrusted
+  prompts or third-party repositories.
+- Run release and package checks before publishing a build.
+- Report suspicious provider output or sandbox bypass behavior through the
+  private advisory channel.
+
+## Runtime Security Boundaries
+
+Build orchestrates external provider CLIs. Those CLIs may read project files,
+spawn subprocesses, and access the network according to the active provider and
+platform configuration. Treat provider execution as delegated code execution
+inside the configured workspace, not as a confidentiality boundary.
+
+### macOS Sandbox
+
+On macOS, Build can wrap provider CLI processes with `sandbox-exec`. This
+boundary is intended to reduce unintended writes outside approved locations and
+to protect selected credential paths from filesystem access.
+
+HOME is resolved to its filesystem identity before rendering home-relative
+paths. Credential protections use the operator's HOME; an isolated child HOME
+controls provider state and does not replace those operator credential denies.
+
+Important limits:
+
+- It is not an outbound network filter.
+- It is not a complete confidentiality boundary for every readable file.
+- Provider processes may still receive credentials from inherited environment
+  variables or provider authentication stores.
+- Custom sandbox profiles replace the generated profile, so review them before
+  use.
+
+Use `build sandbox status` and the telemetry commands documented in the CLI
+reference to confirm whether a provider run was sandboxed or authorized by
+Linux host class.
+
+Runtime sandbox settings:
+
+- `BUILD_SANDBOX_ENABLED=0` is an incomplete emergency hatch. It disables
+  Build's sandbox wrapper for that process. It does not authorize provider
+  internal-sandbox bypass. Host class is the Linux write path; do not use this
+  variable as the Linux write opt-in.
+- `BUILD_SANDBOX_<PROVIDER>_ENABLED=0` disables the wrapper for one provider,
+  such as `BUILD_SANDBOX_CLAUDE_ENABLED=0` or
+  `BUILD_SANDBOX_COPILOT_ENABLED=0`. Same hatch limits as the global flag.
+- `BUILD_SANDBOX_PROFILE_PATH=/path/to/profile.sb` uses a custom macOS
+  sandbox profile. A custom profile fully replaces Build's generated profile.
+- `BUILD_SANDBOX_BOUNDARY_POLICY` sets boundary acceptance policy. The default
+  (`attested_outer_ok`) accepts a self-generated seatbelt, an attested
+  container, an attested inherited-outer boundary, or a Linux host class on
+  Linux. `strict` still rejects an inherited-outer boundary, but Linux host
+  class remains accepted on Linux under both policies. Host class is a Seatbelt
+  substitute, not an inherited-outer. Darwin ignores a forged linux proof pair.
+  Every boundary decision consults the policy uniformly: the provider bypass
+  gate, the wrapper path, and the will-be-active predicate.
+- `BUILD_SANDBOX_LINUX_HOST_CLASS=isolated|desktop` is the Linux-only launch
+  declaration. `isolated` is the supported empty-home / cloud-agent contract.
+  `desktop` forces the desktop consent path even inside a container. Ignored on
+  macOS. Provider children never inherit this variable.
+- `BUILD_SANDBOX_CONTAINER_ATTESTED` and
+  `BUILD_SANDBOX_PROVENANCE=container` are container-boundary claims. Build
+  accepts them only when the host also provides a runtime-created container
+  signal; environment variables alone cannot attest a container. Existing
+  attested containers remain a valid isolated-class signal.
+- `BUILD_SANDBOX_FORCE_INHERITED_OUTER` is a deprecated legacy test key. It is
+  ignored by sandbox policy and retained as deprecated compatibility metadata.
+  Provider child environments independently scrub all Build sandbox-authority
+  variables. Do not use it to configure a runtime boundary.
+
+### Supported write-capable provider boundaries
+
+Write-capable provider automation needs an accepted sandbox/policy boundary.
+On macOS that is still a confinement boundary plus proof that required state
+paths are writable under it. On Linux, host class is the write policy: it
+authorizes writes without claiming a Seatbelt-equivalent filesystem allowlist.
+
+Supported paths:
+
+- **macOS Seatbelt** — Build's generated seatbelt profile (`sandbox-exec`) is
+  the default self-authored boundary on macOS and proves the policy allowlist by
+  construction. With no accepted boundary at all (no Seatbelt, container,
+  inherited outer, or Linux host class), write-capable automation fails closed.
+- **Attested container** — container provenance is accepted only when a
+  container-boundary claim is paired with a runtime-created container signal
+  (`BUILD_SANDBOX_CONTAINER_ATTESTED` / `BUILD_SANDBOX_PROVENANCE=container`
+  above). Container acceptance still requires the provider's required write
+  paths to be writable under that outer boundary. Existing attested containers
+  remain valid.
+- **Linux host class** — Linux has no self-generated Seatbelt. Isolated or
+  acknowledged Linux means provider CLIs can write anywhere `$USER` can. That
+  is not Seatbelt-sandboxed. All three write gates honor `linux_isolated` /
+  `linux_acknowledged` plus `linux_host_class` on Linux only. Accepted under
+  both `strict` and `attested_outer_ok`.
+  - **isolated** (VM, container, cloud, CI): writes just work. Classify with
+    `build sandbox trust linux --host isolated` or launch env
+    `BUILD_SANDBOX_LINUX_HOST_CLASS=isolated` (supported empty-home /
+    cloud-agent contract). Isolated never expires except
+    `build sandbox trust linux --revoke`. Auto-isolate on container OS
+    markers, well-known CI vendor vars, and Codespaces/Gitpod. Not DMI /
+    hypervisor. Not `CI=true` alone. Not unverified `CURSOR_AGENT`.
+  - **desktop**: warn plus informed override
+    (`build sandbox trust linux --ack-desktop` or a TTY prompt). Never a
+    platform ban. Missing consent fails this run with
+    `linux_desktop_consent_required`. WSL is treated as a desktop.
+  - Consent is user-scoped (`getStateDir()` /
+    `~/.build/state/linux-host-policy.json`), never repo `.build-project/`.
+  - When host class is what authorizes turning a provider's own internal sandbox
+    off, the launch prints one line to stderr naming the provenance, for example
+    `Info: Codex internal sandbox is bypassed for this run because the Linux host
+    class provides the boundary (provenance=linux_isolated).` macOS Seatbelt and
+    inherited-outer provenance print nothing.
+
+Analysis-intent write denial (the no-writes guarantee for analysis runs) is
+enforced by the macOS Seatbelt. On Linux host classes, including auto-detected
+container, CI, and cloud-agent hosts, and on attested containers, runs are
+unwrapped, so only providers with a native read-only posture keep the checkout
+unmodified.
+
+```bash
+build sandbox status [--json] [--probe] [--provider] [--all]
+build sandbox classify [--json]
+build sandbox trust linux --host isolated
+build sandbox trust linux --ack-desktop
+build sandbox trust linux --revoke
+```
+
+`status --json` includes `linuxHost`. `--ack-desktop` always prints the full
+risk paragraph to stderr (the flag is the consent; the paragraph is the
+record). `build doctor` keeps `sandboxCapable` as a path-writability probe;
+desktop-unacked is a warning, not sandbox-blocked.
+
+Install, readiness (`provider list`, `doctor`), orientation (`plan next`),
+telemetry/cost reads, and other read-only or non-provider-write CLI commands
+remain available on Linux without host-class consent.
+
+The write-capable subprocess paths — headless provider automation through the
+shared base runner and the tmux transport — honor the same contract (macOS
+Seatbelt / attested container / inherited outer, or Linux host class). Other
+sandbox-wrapped subprocesses — auth, model discovery, `doctor`, and readiness
+probes — are still wrapped but are not refused when no confinement boundary is
+available, which is what keeps them usable on Linux without host-class consent
+(some of them, such as provider auth, do write provider configuration).
+
+Direct API inference transport, including its in-process `write_file` /
+`edit_file` tools and sandboxed `bash` tool, has been removed. Legacy API
+selections fail closed with the CLI-only migration error and do not execute.
+
+### Running Build from another agent's sandbox
+
+A host agent's sandbox blocks writes under `.build-project` and `~/.build` (data, state,
+the storage worktree), so a sandboxed `build` fails with a raw EPERM. Where the host
+can exempt a command, run `build` outside the host sandbox: Build's own Seatbelt
+profile is then the boundary for the providers it launches.
+
+| Host | Setting |
+|---|---|
+| Claude Code | `"build:*"` in `sandbox.excludedCommands` |
+| Codex | a `prefix_rule` allow for `build` in the user's Codex rules |
+| Cursor CLI | `Shell(build)` in `permissions.allow` of `cli-config.json`, Cursor's sandbox enabled, no `--force` |
+| Grok, OpenCode | none: they run under AgentGuard, which cannot exempt one command |
+
+Claude Code matches only plain invocations: a pipe, `cd x &&`, an env prefix or a
+redirect keeps the call sandboxed. Under AgentGuard, Build runs inside the host's
+boundary and treats it as an inherited outer sandbox; add Guard List ALLOW entries
+for `~/.build/data` and `~/.build/state` so Build can keep its state. Those
+entries do not cover Local CI: `build ci submit` (which the pre-push hook runs) and
+the validation that `build ci merge` starts also write host publication evidence
+under `~/.local/build-secrets`, which is not among the allowed paths. From
+inside AgentGuard the hook blocks the push and a merge validation it starts ends in
+`needs_attention`. Run Local CI from a host that runs `build` outside its sandbox
+(Claude Code, Codex, or Cursor).
+
+An exemption is a trust decision: an exempted `build` runs with the user's rights,
+and the host no longer constrains what Build itself does. Under an inherited
+boundary Build does not wrap the provider in a Seatbelt, so read-only runs
+(`build ask`, analysis) work only for providers with native read-only
+enforcement; other providers are refused rather than run unconfined.
+
+When Build detects a host sandbox and a write on a Build-owned path fails with
+EPERM (initialization, its lock files, or any command that reaches the top-level
+error handler), the failure prints one line naming this fix.
+
+### Project Verification Executes Target-Repository Code
+
+Build's verification path runs the target repository's own test, build, lint, and
+typecheck commands. The build, flywheel, competition post-apply and Local CI
+verification steps run those commands, native build tools and ordinary test runners
+alike, under the `project-verification` sandbox wherever Build can apply one.
+On macOS that is the generated `sandbox-exec` profile: it allows writes to the
+worktree, temporary directories and the package-manager and toolchain caches, and
+denies Git metadata writes. Some test commands the judge's test gate runs do not
+use this sandbox yet and run as ordinary child processes. On Linux, where Build has no
+sandbox for verification, or when the sandbox is explicitly disabled, verification
+runs as an ordinary child process with your permissions; when Build already runs
+under an accepted outer boundary, verification is subject to that boundary only.
+
+Without an active boundary, code reached through a verification command can write
+anywhere your user account can write, including `$HOME`, and can read credential
+paths. With the generated macOS profile, filesystem effects are confined to the
+worktree, approved runtime state, caches, and temporary directories.
+
+Mitigations that do apply, and what each does not cover:
+
+- Verification children receive a narrow environment allowlist rather than the
+  parent environment. AI and provider API keys, cloud credentials, `GIT_*`
+  routing, and `GH_*` and `GITHUB_*` tokens are excluded. This is credential
+  scrubbing, not filesystem isolation; `HOME` and `PATH` are preserved. The two
+  callers differ: the local CI gate excludes ambient `BUILD_*` authority
+  variables, forces `CI=1`, and injects only authority-derived values, while
+  orchestrator verification inherits ambient `CI`. Verified code can therefore
+  tell the two contexts apart.
+- A command-safety allowlist rejects shell metacharacters, `sh`/`bash`/`zsh` and
+  similar shell executables, inline `node -e`, install and remote-exec verbs such
+  as `npm ci`, and `npx` without `--no-install` or `--offline`. It constrains the
+  command string, not what the invoked script does. `npm test`, `pytest`,
+  `cargo test`, and `make test` are all accepted, and each then runs whatever the
+  repository defines. Some interpreters are admitted for a specific narrow verb,
+  such as `pwsh` limited to `Invoke-Pester`, which still executes the
+  repository's own test code.
+- Dependency materialization passes `--ignore-scripts` for npm, pnpm, and bun, so
+  install lifecycle scripts are suppressed. Yarn is excluded because Yarn Berry
+  rejects the flag, the Python path uses `pip install`, which can execute build
+  backends, and `--ignore-scripts` has no effect on what a test script runs
+  later.
+
+Realistic exposure paths are a compromised dependency pulled into the target
+project, or agent-authored or prompt-injected code that reaches a verification
+script. Neither requires a hostile third-party contribution.
+
+This is not limited to the local CI gate. Orchestrator verification also uses the
+same runner as local CI (wrapped when a boundary is available), including
+progress validation, the typecheck gate, post-execution checks, and
+competition verification.
+
+Treat running Build against an untrusted or unfamiliar repository as running
+that repository's code on your machine.
+
+### Package Contents
+
+The public npm package uses an explicit `package.json#files` allowlist.
+User docs are included by path instead of shipping the whole
+`docs/` tree, and package guards reject internal security session notes,
+validation reports, and audit artifacts.
+
+Relevant local checks:
+
+```bash
+npm run -s check:package-docs
+npm run -s verify:dist
+npm run -s release:pack-smoke
+```
+
+## Security Review Scope
+
+Security audit notes, validation reports, and investigation drafts belong in
+internal planning or security-audit locations, not in the public npm package
+or its reference docs. Packaged docs should describe
+shipped behavior, reporting channels, and user-facing security boundaries.