Skip to content
agentOS

Verification

Run from the repo root or an assigned parallel worktree.

Standard Gates

Section titled “Standard Gates”
Terminal window
bun run check
bun run docs:check
bun run effect-manifests:check
bun run check:public-api
bun run typecheck
bun run test
effect-skill-scan /Users/yansir/code/52/agentOS --strict --json --profile
git diff --check

bun run check includes formatting, generated docs validation, public API intent validation, typecheck, and package tests. The explicit commands are still useful when isolating failures.

Release Gate

Section titled “Release Gate”
Terminal window
bun run check:release
bun run check:full

bun run check:release adds internal package distribution validation to the standard gate. Use it before publishing or when changing package exports, release metadata, or distribution tooling. bun run check:full adds the docs site build and runtime harnesses for release-level integration.

Documentation Gate

Section titled “Documentation Gate”

Documentation facts follow two rules:

  • every fact has exactly one writer;
  • do not derive intent from actual.

docs/surface.json owns declaration facts such as release posture, package status, role, and holds. docs/packages/*.md owns package explanations. Manual docs/api/*.md pages own intended public and experimental exports for unmigrated packages. For packages with apiSourceMode: "source-tsdoc", exported TSDoc owns the API fact and docs/api/*.md is generated. defineCarrier declarations own generated carrier reference facts. docs/effect-skill.json owns Effect scanner package and adapter declarations.

Package README.md, package PUBLIC_API.md, generated API pages, carrier reference pages, runtime package tables, and skill package maps are generated projections. Root and package-local .effect-skill.json files are generated scanner input projections. Change the source fact and run:

Terminal window
bun run docs:generate
bun run effect-manifests:generate

Public API Gate

Section titled “Public API Gate”

Every package with a public surface has an API intent source. Unmigrated packages use manual docs/api/*.md. Migrated packages use exported TSDoc with exactly one status tag: @public, @experimental, @internal, or @deprecated. This is an accidental-export gate, not an API freeze. The checker reads intent, actual exports from package.json.exports and the TypeScript AST, and fails when:

  • an exported symbol is missing from the manifest;
  • an internal-only symbol is exported;
  • a manifest-listed symbol no longer exists.
  • a migrated exported symbol lacks a TSDoc summary or has zero or multiple status tags.

Live Provider Tests

Section titled “Live Provider Tests”

Live tests are opt-in. Source root .dev.vars only through the parallel agent environment. Do not print secrets.

Use prefixed resources:

Terminal window
source "$PARALLEL_AGENT_DIR/env.sh"
set -a
. /Users/yansir/code/52/agentOS/.dev.vars
set +a

Live evidence must prove cleanup and redaction. Scan claims, ledger events, projections, run-stream frames, and error payloads for resolved provider material.