diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..17ad516 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,17 @@ +# Security Policy + +CorpOS is a **company-day simulation** and reference architecture — not a +production-hardened SaaS. See the root [SECURITY.md](../SECURITY.md) for +posture, guarantees, and supply-chain notes. + +## Reporting a Vulnerability + +If you believe you have found a security vulnerability in CorpOS: + +1. **Do not open a public GitHub issue.** +2. Report privately via **[GitHub Security Advisories](https://github.com/SafetyMP/CorpOS/security/advisories/new)** (preferred). +3. If that link returns 404, ask a repo admin to enable **Settings → Code security → Privately report a security vulnerability**, then retry. +4. Include reproduction steps and impact. Do not include secrets or live credentials. +5. We aim to acknowledge within **72 hours** and coordinate a fix under a **90-day responsible disclosure window**. + +Conduct issues belong under [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md), not security advisories. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..f46800f --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,22 @@ +# CorpOS — Copilot / coding-agent instructions + +CorpOS is a **company-day simulation** (firm model, work contracts, PDP/PEP, +humans Approve/Reject/Kill). It is not an agent orchestration framework and +not a production SaaS. + +## Do + +- Keep `./scripts/harness/verify.sh` as the Definition of Done. +- Put firm logic in `packages/core`, HTTP in `apps/api`, UI in `apps/console`. +- Keep exception HITL default-off. Only tests/CI may pass `autoApproveException: true`. +- Keep CI and verify on `SimulationProvider`. Never set `CORPOS_ALLOW_LIVE` in CI. + +## Do not + +- Do not add LangGraph, CrewAI, or other graph/crew multi-agent runtimes. +- Do not imply production SaaS guarantees. +- Do not auto-approve exceptions in product/demo paths. +- Do not run live LLM calls in CI. +- Do not introduce Express or `better-sqlite3`. + +Read [`docs/DESIGN-PIVOT.md`](../docs/DESIGN-PIVOT.md) and [`AGENTS.md`](../AGENTS.md) before expanding scope. diff --git a/AGENTS.md b/AGENTS.md index 4d11b7a..547b16e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,27 +1,42 @@ -# Site contract +# CorpOS — agent notes -## Gates +CorpOS is a **company-day simulation**: firm model, work contracts, PDP/PEP +policy gates, and humans who Approve / Reject / Kill. It is not an agent +orchestration framework (not LangGraph, not CrewAI). LLM calls are optional +actors inside the sim (`CORPOS_ALLOW_LIVE=1`) and must never run in CI. -| Command | Purpose | -| ---------------------------------- | ----------------------------------- | -| `./scripts/harness/verify.sh` | Functional and static acceptance | -| `./scripts/harness/adversarial.sh` | Authorized local adversarial probes | +Factory / corporate-site overlay: [`docs/factory-overlay.md`](docs/factory-overlay.md). +Positioning: [`docs/DESIGN-PIVOT.md`](docs/DESIGN-PIVOT.md). -Record `verification_scripts` as the site directory `scripts/harness`. Required -entrypoints are `verify.sh` and `adversarial.sh`. Digest-bound companions under -the same directory (included in the harness digest) are: +## Commands -- `check-stub-canary.sh` — mandatory non-trivial verify canary -- `adversarial-run.mjs` — adversarial probe implementation +| Command | Purpose | +| ---------------------------------- | ------------------------------------------------------------------------ | +| `./scripts/harness/verify.sh` | Definition of Done — build, typecheck, test, lint, format, stack guards | +| `./scripts/harness/adversarial.sh` | Authorized local adversarial probes | +| `npm test` | Unit tests | +| `npm run scenario` | HITL default-off company day; non-zero unless the exception auto-settles | +| `npm run audit:verify` | Hash-chained audit receipts | -Optional wrappers may remain at `scripts/verify.sh` / `scripts/adversarial.sh` -(and `scripts/check-stub-canary.sh`) for humans; they are outside the digest -boundary. +A change is not done until `./scripts/harness/verify.sh` is green. -The corporate handoff fixes scope. The site manager assigns ADRs; site specialists write; -operations excellence reviews current evidence. Work in isolated roots, never edit -corporate approval state, and never self-approve. +## Layout -Site id: `corpos`. Prior Cursor Harness v4 is under `_archives/harness-v4/`. -Product company-day demos must not auto-approve exceptions unless a test/CI -caller passes `autoApproveException: true` explicitly. +| Path | Responsibility | +| ------------------------ | ------------------------------------------------------------ | +| `packages/core` | Firm model, work contracts, gateway / PDP / PEP, company day | +| `packages/mcp-knowledge` | Local MCP knowledge server (stdio) | +| `apps/api` | Hono REST + SSE | +| `apps/console` | Vite + Preact ops console | + +## Hard rules + +- **Never auto-approve exceptions** unless a test/CI caller passes + `autoApproveException: true` explicitly. Product demos and the ops console + keep it `false`. +- **Never live LLM in CI.** Default provider is `SimulationProvider`. + `CORPOS_ALLOW_LIVE` and `OPENROUTER_API_KEY` must stay unset in verify and CI. +- Do not add LangGraph, CrewAI, or other graph/crew runtimes to “keep up.” + See [`docs/DESIGN-PIVOT.md`](docs/DESIGN-PIVOT.md). +- Do not introduce Express or `better-sqlite3`. +- Never commit secrets, `*.db`, `.env`, or `dist/`. diff --git a/README.md b/README.md index e8f7745..47d64e2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # CorpOS -> Reference implementation of an **autonomous company** — firm model, work contracts, policy-gated control plane, and a July 2026 **governance plane** (PDP/PEP, three-layer authz, OTel GenAI, OWASP ASI / NIST RMF crosswalk). +> **Company-day simulation** of a firm — work contracts, PDP/PEP policy gates, and humans who Approve / Reject / Kill. Not an autonomous-company SaaS, and not LangGraph, CrewAI, or any multi-agent orchestration framework. + +> **Permit rule:** Approve / Reject / Kill is the closer. Default actors are scripted; live LLMs are optional. This is not a live EHS, health, or finance workforce. Same instinct: [SafetyMP](https://github.com/SafetyMP/SafetyMP). [![CI](https://github.com/SafetyMP/CorpOS/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/SafetyMP/CorpOS/actions/workflows/ci.yml) [![CodeQL](https://github.com/SafetyMP/CorpOS/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/SafetyMP/CorpOS/actions/workflows/codeql.yml) @@ -8,11 +10,11 @@ [![License: Apache-2.0](https://img.shields.io/github/license/SafetyMP/CorpOS)](LICENSE) [![Node](https://img.shields.io/badge/node-%E2%89%A522-339933?logo=node.js&logoColor=white)](#quick-start) -CorpOS shows how a firm operates when department agents do most work and **humans govern by exception** (Approve / Reject / Kill in the ops console). Autonomy is earned from evidence, not granted in prompts. Interop protocols (MCP) are transport; firm-side governance includes **G1 membership** and **G4 dissent** today, with a broader G1–G6 crosswalk in the docs. +CorpOS simulates a company day: department actors settle work contracts under a policy gate, and **humans govern by exception** (Approve / Reject / Kill in the ops console). Autonomy is earned from evidence, not granted in prompts. Interop protocols (MCP) are transport; firm-side governance includes **G1 membership** and **G4 dissent** today, with a broader G1–G6 crosswalk in the docs. Positioning: [`docs/DESIGN-PIVOT.md`](docs/DESIGN-PIVOT.md). > **Scope:** Reference architecture and runnable demo — **not** a production-hardened SaaS. See [SECURITY.md](SECURITY.md). -Default mode is **simulation** (`SimulationProvider`) for deterministic CI. Live LLM (`HttpLLMProvider`) drives company-day/orchestrator only when `CORPOS_ALLOW_LIVE=1` and `OPENROUTER_API_KEY` are set — `/api/health.mode` never lies. G1–G6 firm governance, orchestrator-driven day, TTL scheduler, console Bearer (shared mode), and live `/api/events` SSE are implemented. +Default mode is **simulation** (`SimulationProvider`) for deterministic CI. Live LLM (`HttpLLMProvider`) is an optional actor inside the sim only when `CORPOS_ALLOW_LIVE=1` and `OPENROUTER_API_KEY` are set — `/api/health.mode` never lies. G1–G6 firm governance, orchestrator-driven day, TTL scheduler, console Bearer (shared mode), and live `/api/events` SSE are implemented. Read the thesis: [`docs/future-of-the-firm.md`](docs/future-of-the-firm.md). Governance crosswalk: [`docs/governance-crosswalk.md`](docs/governance-crosswalk.md). AIBOM: [`docs/aibom.json`](docs/aibom.json). Docs index: [`docs/README.md`](docs/README.md). diff --git a/SECURITY.md b/SECURITY.md index ca3240a..6107caa 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -55,8 +55,8 @@ static token compare for demos, not an OAuth flow. after lockfile changes that introduce new install scripts. - Do **not** set `dangerously-allow-all-scripts=true` in CI. -## Reporting +## Reporting a Vulnerability -Use GitHub Security Advisories on the CorpOS repository for **vulnerabilities**. -Conduct issues are handled under [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), not -security advisories. +Use GitHub Security Advisories on the CorpOS repository for **vulnerabilities** +([`.github/SECURITY.md`](.github/SECURITY.md)). Conduct issues are handled under +[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), not security advisories. diff --git a/docs/DESIGN-PIVOT.md b/docs/DESIGN-PIVOT.md new file mode 100644 index 0000000..ce94b18 --- /dev/null +++ b/docs/DESIGN-PIVOT.md @@ -0,0 +1,38 @@ +# Design pivot — company-day simulation (September 2026) + +CorpOS is a **company-day simulation**. The product is a firm model, work +contracts, PDP/PEP policy enforcement, and humans who **Approve / Reject / Kill**. +It is **not** an agent orchestration framework. + +## What this is + +- A deterministic (by default) simulation of a company day. +- Work contracts that draft, hand off, settle, and compensate. +- A policy decision point / policy enforcement point (PDP/PEP) on consequential tools. +- Human governors in the ops console: Approve, Reject, Kill. + +## What this is not + +- Not an autonomous-company SaaS. +- Not LangGraph, CrewAI, AutoGen, or any multi-agent graph/crew runtime. +- Not a place to add graph/crew features to “keep up” with orchestration frameworks. + +LLM calls are **optional actors inside the sim**. They turn on only when +`CORPOS_ALLOW_LIVE=1` (plus a provider key). CI and `./scripts/harness/verify.sh` +stay on `SimulationProvider`. Health `mode` must never claim live when it is not. + +## Contested: CrewAI / LangGraph / multi-agent runtimes + +Do not add those runtimes. CorpOS already has a small in-process orchestrator +that drives a scripted company day (`enqueueAndRun` / `waitForResume`). That +surface exists to persist and resume work contracts under policy — not to +compete as a general agent graph. + +## Next slice + +1. **Shrink** the orchestrator surface (fewer general-purpose graph APIs). +2. **Deepen** work-contract semantics and PDP/PEP evidence (receipts, deny + paths, HITL default-off, audit chain). + +See also [ADR-11](adr/0011-provider-strategy.md), [ADR-15](adr/0015-company-day-orchestrator-workload.md), +[ADR-17](adr/0017-governance-pdp-pep.md). diff --git a/docs/README.md b/docs/README.md index 24534d5..311bc93 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,11 @@ # CorpOS documentation -Public docs for the autonomous-company reference. Not a certification claim. +Public docs for the company-day simulation reference. Not a certification claim. | Doc | Purpose | | --- | --- | +| [DESIGN-PIVOT.md](DESIGN-PIVOT.md) | September 2026 positioning — simulation, not an orchestration framework | +| [factory-overlay.md](factory-overlay.md) | Corporate / factory site-contract overlay (moved from root AGENTS.md) | | [future-of-the-firm.md](future-of-the-firm.md) | Product thesis and 20-minute demo path | | [governance-crosswalk.md](governance-crosswalk.md) | NIST AI RMF / OWASP ASI / standards mapping (pedagogical) | | [aibom.json](aibom.json) | AI bill of materials inventory | diff --git a/docs/factory-overlay.md b/docs/factory-overlay.md new file mode 100644 index 0000000..4d11b7a --- /dev/null +++ b/docs/factory-overlay.md @@ -0,0 +1,27 @@ +# Site contract + +## Gates + +| Command | Purpose | +| ---------------------------------- | ----------------------------------- | +| `./scripts/harness/verify.sh` | Functional and static acceptance | +| `./scripts/harness/adversarial.sh` | Authorized local adversarial probes | + +Record `verification_scripts` as the site directory `scripts/harness`. Required +entrypoints are `verify.sh` and `adversarial.sh`. Digest-bound companions under +the same directory (included in the harness digest) are: + +- `check-stub-canary.sh` — mandatory non-trivial verify canary +- `adversarial-run.mjs` — adversarial probe implementation + +Optional wrappers may remain at `scripts/verify.sh` / `scripts/adversarial.sh` +(and `scripts/check-stub-canary.sh`) for humans; they are outside the digest +boundary. + +The corporate handoff fixes scope. The site manager assigns ADRs; site specialists write; +operations excellence reviews current evidence. Work in isolated roots, never edit +corporate approval state, and never self-approve. + +Site id: `corpos`. Prior Cursor Harness v4 is under `_archives/harness-v4/`. +Product company-day demos must not auto-approve exceptions unless a test/CI +caller passes `autoApproveException: true` explicitly. diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..962901e --- /dev/null +++ b/llms.txt @@ -0,0 +1,19 @@ +# CorpOS + +> Company-day simulation of a firm: work contracts, PDP/PEP, humans Approve/Reject/Kill. Not an autonomous-company SaaS. Not LangGraph or CrewAI. + +## Docs + +- [README](README.md): quick start and architecture +- [DESIGN-PIVOT](docs/DESIGN-PIVOT.md): September 2026 positioning — simulation, not an orchestration framework +- [AGENTS](AGENTS.md): contributor and coding-agent conventions +- [Future of the firm](docs/future-of-the-firm.md): thesis and 20-minute demo +- [Governance crosswalk](docs/governance-crosswalk.md): NIST / OWASP ASI (pedagogical) +- [Security](SECURITY.md): reference-architecture posture +- [Contributing](CONTRIBUTING.md): setup and PR expectations + +## Verify + +`./scripts/harness/verify.sh` + +Default provider is simulation. Live LLM (`CORPOS_ALLOW_LIVE`) is optional and never used in CI.