Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,14 @@ release yet; entries name the pull requests that made them.

### Changed

- `tools/cstack_mcp.py` refuses to start without the durable ledger `cstack init` sets up, and says which command to run; `--allow-memory-ledger` keeps the memory ledger for tests and throwaway development. Tailscale is now optional: the device name comes from `--device`, the name `cstack init` recorded, or the tailnet name. `cryptography` moved from `ci/requirements.txt` to `requirements.txt`.
- Re-vendored the four pinned foundations at the commits that merged the 2026-11-09 backfill-review fixes: refrigeration `f78905d`, film `52fa82c`, robotics `d61de96`, template `0dcf469` (template gains one test file, 50 entries). Upstream changed only docs, tests and tools; no bridge or schema changed, so inventory hashes are unchanged. `poodo_skill` moves to `aeba967` (its 45 synced files are byte-identical; the new upstream release-docs test file is listed as deferred). `EXPORT-MANIFEST.json` rebuilt. EndoForge stays pinned until its rounds 8-10 merge.
- README and docs index rewritten for a first-time reader: purpose, a real approval run, a top-down diagram and install first; the NASA control documents sit behind one "Engineering records" section. Material moved out of the README went to new how-to guides (approve asks, define bots, use a real model, add a domain, merge train) and an explanation of Foundations and pins. The README's Measured table moved to `docs/verification/measured-2026-11.md`, with every figure tied to a commit on `main` (assurance finding F-7) (#80).


### Added

- `cstack init` (`tools/cstack_init.py`, `adapters/local_setup.py`): one command sets up a private state folder, the device name and a durable witnessed ledger for every bot; safe to run again, with `--check` for a read-only health report. Requirements CS-REQ-084 to CS-REQ-086; guide [Set up Cstack](docs/guides/how-to/set-up.md).
- Cstack family documentation standard published in `docs/standards/` (standard, checklist, templates) as the canonical copy for the family.
- NASA-organized control documents: software management plan, compliance matrix, test plan and procedures, generated data dictionary, generated test report and version description for the `main` baseline, assurance record, user manual map, limitations page; problem-report and change-request issue templates and a peer-review PR template.
- Requirements CS-REQ-036 to CS-REQ-077 for behaviour existing tests already check; every requirement allocated to a design component; full bidirectional trace.
Expand Down
130 changes: 79 additions & 51 deletions EXPORT-MANIFEST.json
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
"bytes": 1415
},
".github/workflows/ci.yml": {
"sha256": "7a77c7f271c47d8c89db411c767ce79eab77c9d497961d6abe1fdbd4f3227fea",
"sha256": "e50ae65fffd328ad8b1b3ab7b3561a6f22ddd488cd334159324280d0165e635b",
"bytes": 1052
},
".gitignore": {
Expand All @@ -51,8 +51,8 @@
"bytes": 4359
},
"CHANGELOG.md": {
"sha256": "4b45ad9f8663e5d4e32a2398d5be78a5eeb21bbf95ad3ec5f520f845524c828e",
"bytes": 7103
"sha256": "a8f9af483703b39d476ba20124e93e54b6daf83b51f7de6bd506b4c181087c75",
"bytes": 7833
},
"CODE_OF_CONDUCT.md": {
"sha256": "6228457a516409a784d807676564c8477f58d979eb7df3a4f690008d8a794442",
Expand All @@ -71,8 +71,8 @@
"bytes": 1183
},
"README.md": {
"sha256": "f180ee76b42982e1d4b7a83064746a6684ef1704270d0c0d18f7a9c468d5d015",
"bytes": 16333
"sha256": "75cd2ad52f8185d762610fd51d1c4e9f4130dde437c9c2b332934b44e1aeaa04",
"bytes": 17147
},
"SECURITY.md": {
"sha256": "ca32c78d9c9402d31cfac4538c20ddbc9e689f9ce6ecec40fd7535e651edba65",
Expand Down Expand Up @@ -186,6 +186,10 @@
"sha256": "cd8cabcba2739b2aac95c3798710707605791950a34fceba73eb7ccd28392837",
"bytes": 14042
},
"adapters/foundations_mcp.py": {
"sha256": "18674ac66ffae13f19f97535cde966eccca5ea8fba7ef6313cfa418f550b5402",
"bytes": 7965
},
"adapters/host_read_models.py": {
"sha256": "554a6149db492d1ebdd5ffa7230ab6128518daea208359002eb8c1d3f1646239",
"bytes": 21208
Expand All @@ -194,6 +198,10 @@
"sha256": "356cf0918fc5fba8752ee11ddd78dee9ce577ef546e80ef319ff2ce074690a3c",
"bytes": 23532
},
"adapters/local_setup.py": {
"sha256": "b1bc30924dc4de0e45a1df589f14168546fabcd9a95bf29ee026862de8f548c8",
"bytes": 16299
},
"adapters/math_stdio.py": {
"sha256": "7332a747fbb96aa2699073ed9f6b6ca7ce88c285b47f7d6fc73cdb07f0ba35e7",
"bytes": 11813
Expand All @@ -203,8 +211,8 @@
"bytes": 25742
},
"adapters/mcp_stdio_server.py": {
"sha256": "566ed454db6d412209e03db367a0f4a2a2188d9f30012a13e9f1d98f900008cc",
"bytes": 12805
"sha256": "433e7e59d43e85743c43b6039107fface3a206002c8246f72f754ef54ff06b22",
"bytes": 12830
},
"adapters/memory/README.md": {
"sha256": "30dd166af5d401519d2acd28f357c51f2a0fa0b98a0cd445449d4c95963b183e",
Expand Down Expand Up @@ -379,8 +387,8 @@
"bytes": 1010
},
"bootstrap.py": {
"sha256": "cf066bfe377e5f02d24cfc0d040a1ba2efe5dde7026f11c72d00e8f8b3faf138",
"bytes": 27733
"sha256": "7c4b19e2e25b70dac12e953339d97bb00e30fbb293841f57c2e27fcfff523daa",
"bytes": 28554
},
"ci/host-only.txt": {
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
Expand All @@ -391,8 +399,8 @@
"bytes": 270
},
"ci/requirements.txt": {
"sha256": "1ecce7d0091219627059831f2e48b6c433465defd9702c2c3f741f6f39d58bf7",
"bytes": 372
"sha256": "c26053f6e77ab2093df22e5fb5227f6f4fe6e5993610d0669930cadd7c76590f",
"bytes": 289
},
"ci/run-local.sh": {
"sha256": "477f0eaa0de1b9305f6949ceac603fcc98f4826fd9ffc486364457db6fb0e594",
Expand All @@ -411,8 +419,8 @@
"bytes": 8349
},
"contracts/ADAPTERS.json": {
"sha256": "f3acd594ab22dc509793f40f6093e742c4abcb7af09d51156e0fe2a86fb3961c",
"bytes": 31508
"sha256": "82b2a3b5972f64238597702dc5411105f4011f1320e51972e6c30ea42f8301d4",
"bytes": 33684
},
"contracts/CONTRACT.json": {
"sha256": "05848bff545d839bdcc9e30f4c8d2352f768e0298129e4bc57cbb68ed9e0c0c5",
Expand All @@ -439,8 +447,8 @@
"bytes": 2422
},
"contracts/INTERFACES.md": {
"sha256": "34938f9049a848706ff03583eb630e46af43ed33cc070eb1c6d9f3fa5d0ed771",
"bytes": 26705
"sha256": "78e96fde981a066f2f9a57d8e57c6b04bca08169af7770635e82986e89646fc1",
"bytes": 26900
},
"contracts/RESEARCH.md": {
"sha256": "633318d6f72fce2caa8ccfbed7ab34c2f5ff8f1b6e350fe761b27a3a96e8d80d",
Expand Down Expand Up @@ -471,12 +479,12 @@
"bytes": 684
},
"docs/README.md": {
"sha256": "914f226db4b69a76e5ccbe616005d65c4def91fa8f95427e33359e638a18315e",
"bytes": 7078
"sha256": "632a972f27d73c770deceb41c3a6f8bed0a43f810b4cf45e2037e36285f8bbe7",
"bytes": 7172
},
"docs/architecture/architecture.md": {
"sha256": "d5a259bcfc07576eac4cea7a74036744a5320dec2d98e74debc53a1df47243c3",
"bytes": 22319
"sha256": "4a1728ef2188f9380be605eab67f67744f39a1ddc8d8506b7f83300133f948d2",
"bytes": 23113
},
"docs/assurance/assurance-record.md": {
"sha256": "71d5308e71aa46f70dd1ac06cd99e19955ae63bafd3cea57355634924b3b8a7f",
Expand Down Expand Up @@ -511,12 +519,12 @@
"bytes": 4034
},
"docs/guides/explanation/server-and-adapters.md": {
"sha256": "d6eac3103da29a0e668bbcdce7b143e157be312936f795010d1cb14e21029bf7",
"bytes": 7321
"sha256": "8756fa75134d603696266069d266aaff3d87f658c2b74d4d8b4f14b244399183",
"bytes": 7455
},
"docs/guides/how-to/README.md": {
"sha256": "05a9051fb3b603dadbe67fd2507edd8ca435005abc9f382d97e6602c51f166da",
"bytes": 1048
"sha256": "6890089d7cad4f4a85591c471e052d42f8648cbead70cadca522718f7a301ac7",
"bytes": 1146
},
"docs/guides/how-to/add-a-domain.md": {
"sha256": "2db40dba2a8b8921b41d54c874d1328c2652fbe149614a25309c7edb2b60c429",
Expand All @@ -527,8 +535,8 @@
"bytes": 4667
},
"docs/guides/how-to/define-bots.md": {
"sha256": "f0657bb1bfee699cf7782714493b70dcfd97e3ed3b8ef7cd8c67ad6dd50df2d5",
"bytes": 2634
"sha256": "60e71f1ff3ab2d662ff60fe694d3ca6c0bfcb3b9762851e02475e91fec0a2dac",
"bytes": 2797
},
"docs/guides/how-to/merge-train.md": {
"sha256": "57f342c9540af29378026196cdd67bd918a0aeff1c35e02d7fef2acdda95350f",
Expand All @@ -539,8 +547,12 @@
"bytes": 4911
},
"docs/guides/how-to/run-ci-locally.md": {
"sha256": "2cf4d16896f4863d3949be5e6d0a352606d9782ba1ac79717d62c6c148215ce8",
"bytes": 5058
"sha256": "da1947ec3660e137aa06bf41ffbafde90b17347b1f4d28b875b441e770532fa8",
"bytes": 5100
},
"docs/guides/how-to/set-up.md": {
"sha256": "e9b476e56231584c52c62014a6e62b370a20451c27072ec156376eeef1b46e99",
"bytes": 4322
},
"docs/guides/how-to/use-a-real-model.md": {
"sha256": "47f525d28f2ef975f511adab6404dce51775eb669ab3c8f113bba968ce2e738d",
Expand All @@ -551,24 +563,24 @@
"bytes": 1800
},
"docs/guides/reference/commands.md": {
"sha256": "61af7b706324d15cdcd8af87a460d801aaafda861750b40662811f01ca855519",
"bytes": 9258
"sha256": "822c34c8f9bde3cefcea7c9cc0cdb212e8b623ab3dca489e4903b02bc3702823",
"bytes": 9729
},
"docs/guides/reference/configuration.md": {
"sha256": "edf4f27e425d74117146a5ae2393d793dba08b2cf6911ad5874dc9c23040092c",
"bytes": 4752
"sha256": "10f87f0f7991cc2957e03c3476df8bcce0ac2b08af58653a48f216e8e5a837ca",
"bytes": 5000
},
"docs/guides/reference/environment.md": {
"sha256": "961b924137b919c0631b962cf8088e881759d146731c48b6b8a81dcc5ab76995",
"bytes": 4218
"sha256": "dcd6917825219ebb0bdfcba953d2aee1bc8707e9ea59c2c8e2e91ecdce2ae9da",
"bytes": 4244
},
"docs/guides/tutorials/README.md": {
"sha256": "e3e7a578ad9a12704e226839c61d88aa2278a64e30c7771228517eee6f06e45b",
"bytes": 483
},
"docs/guides/tutorials/first-run.md": {
"sha256": "a0a8da3c25b2c71a7d06db1acacf07e1c4a55a37222f58090ae4f19fe21353d0",
"bytes": 7604
"sha256": "c8a717d417219b056ad1b049cb1365b7f573b27ba81226fd0e91d5828e715612",
"bytes": 7778
},
"docs/icd/icd-endoforge-pin.md": {
"sha256": "7602054207a725e24ef5c28153582ebdf09d3f89df5e82dac286f827f0147c06",
Expand All @@ -579,8 +591,8 @@
"bytes": 21041
},
"docs/icd/icd-foundations.md": {
"sha256": "bcabb16e735448824c89dcb91ca416b0f80a555e316991252dcc6fe01c67fd03",
"bytes": 12026
"sha256": "8564330068956d0e8e8d067f8b22902e14191bfce8c04df2f56a3d9727007b45",
"bytes": 15770
},
"docs/icd/icd-poodo.md": {
"sha256": "8be48f4f2e7c9917ded4390fbae6cef604be62710cd569623c7e2005cbcc44db",
Expand All @@ -603,8 +615,8 @@
"bytes": 5760
},
"docs/requirements/requirements.md": {
"sha256": "aa5457afcdd3ae494306a74b75319ccd0fd0725de4c3587832083699a29491a7",
"bytes": 49158
"sha256": "f8600e4cb1aa3a71a079d2f343d4b7eaedcd62a842b2f152cf582e72cd564651",
"bytes": 52840
},
"docs/rules/no-comments.md": {
"sha256": "cd0aac16b8119228bb5b7e79d38e71ddcc430679916a9f7080d7b3bd88fb4a90",
Expand Down Expand Up @@ -711,8 +723,8 @@
"bytes": 9734
},
"docs/verification/verification-matrix.md": {
"sha256": "36973230602038f7ee2a96fc73ff992c3a37ce7e8c2f89feb8e2aed3a13f2391",
"bytes": 23845
"sha256": "84cb6209311ad0a6e045ebaa1adba606c64bb3d7e38cbdaef896b248b21f61e6",
"bytes": 24954
},
"docs/verification/wiring-acceptance.md": {
"sha256": "a063e0580bf60ca41b37d473f1df7989b12c7e0aa915cecef30b916a4c4720d8",
Expand Down Expand Up @@ -2059,8 +2071,8 @@
"bytes": 4167
},
"requirements.txt": {
"sha256": "55ff5313a0132d4037cf57d9dc9dd29073aee248a472b0702d2246b37cbd0431",
"bytes": 98
"sha256": "a4418a02bdf15e406a1286532bebc4c7fe5443efb6da2d7a5f4d2c81161d150e",
"bytes": 119
},
"schemas/engine-v020-tools.json": {
"sha256": "500b73fee56fd877649e5e475b8155cd77f7b3a7f002394a5ab909725fc56699",
Expand Down Expand Up @@ -2246,6 +2258,10 @@
"sha256": "a46ebe47e5ebe01bcb8b2d44dec816fee936b2e3e50bfbb13d723a97af7f0383",
"bytes": 7726
},
"tests/test_cstack_init.py": {
"sha256": "4e51554a33b035389809023718a58eadfa04096f06b2997f66c942b43d1d6c83",
"bytes": 14744
},
"tests/test_data_dictionary.py": {
"sha256": "c07bd1cac36da3d80e39f387207bf754c2bd8eafab98fb80e58ae818315764a1",
"bytes": 1157
Expand Down Expand Up @@ -2291,8 +2307,8 @@
"bytes": 1942
},
"tests/test_fleet_mail.py": {
"sha256": "195bb022f35b6f9a1a6f06f914c6545124724b6fc87cb9b9d4b80ecd1c1d25f8",
"bytes": 27897
"sha256": "96dd99a04bc37041069fc6ab752ba66a3b16f23db103c6ba5a79060ff33eb100",
"bytes": 27925
},
"tests/test_fleet_mail_budget.py": {
"sha256": "39bac88d15171a8d2f60953ba9a7ea848b6001cbee4d0927c46e5b672e7c1fbd",
Expand Down Expand Up @@ -2322,6 +2338,10 @@
"sha256": "6450fac6fbef445afd4eeec66f28b78172c57648fbda58ff72e9ea2dfcf79fbd",
"bytes": 4156
},
"tests/test_foundations_mcp.py": {
"sha256": "e8d849e69538cd03d9ba55711ae526c9ea0913094056a75a2b2e8e5aad3fe099",
"bytes": 12003
},
"tests/test_goal_liveness.py": {
"sha256": "75f3b7e05e45b340add1bed493c6ce478ac2c83ee69a135673429fc6b948ee75",
"bytes": 5001
Expand All @@ -2347,8 +2367,8 @@
"bytes": 5223
},
"tests/test_mcp_driving_adapter.py": {
"sha256": "19475f9c54763aa6b0b838106e441ad4d0969e30ae10f683246688da2b943cdf",
"bytes": 11728
"sha256": "f1445aac99c7a386c3d353fb8716ef06eb7f7877e33900f1839d710c865b9772",
"bytes": 11778
},
"tests/test_mcp_stdio_client.py": {
"sha256": "f4a362be20e12fcc20d05942a7f4cbcd6126a22017f48b20e13effc696bae613",
Expand Down Expand Up @@ -2479,8 +2499,8 @@
"bytes": 6107
},
"tools/check_readme.py": {
"sha256": "2b829de8aa66f98795878d16b741bea66a8d68d24ccce859db737c3dc9c679f3",
"bytes": 10091
"sha256": "d04104663cfafbe729f701e489f8a46646b18d8a117e2564b69181a018484b33",
"bytes": 11054
},
"tools/check_trace.py": {
"sha256": "621b54f7923fa1cdfb25b3b71f52798befba681f6dffd2df8fea9c60765f8196",
Expand All @@ -2490,9 +2510,13 @@
"sha256": "368a1f7dda5ab9ecc9c0adaf524707df064e1f5e95b10ffb096ea10eed0bbce5",
"bytes": 12521
},
"tools/cstack_init.py": {
"sha256": "68884a22bba2b8dd34e39b6db6046333962692bda553778618bd47a96490c346",
"bytes": 2690
},
"tools/cstack_mcp.py": {
"sha256": "25e1de628ee66b3fa4273a4ceaca3c0a4658e789e0c65ab8f970fd4d307bcb38",
"bytes": 2961
"sha256": "e1205c7ba9f1284b62800cb55262b54e44b5cafe969d9f56a8dadb31aadcfc4c",
"bytes": 3375
},
"tools/e2e_agent.py": {
"sha256": "0c3240023a16ea16592131e31117c0c9c97e2cb120f05dd468cd1b937c1505a5",
Expand All @@ -2502,6 +2526,10 @@
"sha256": "4c49f50eecf4d51140b308d08e5f7192c69c99a647f611d3cc3ea02219b4717f",
"bytes": 133
},
"tools/foundations_mcp.py": {
"sha256": "a05758847bca2689e0003a7372b207e19269a3660f0f8a6c5ef62ca548984193",
"bytes": 1810
},
"tools/fuzz_ports.py": {
"sha256": "1b38686b291fe83230226353dcafb936684e653ac9b820e7b823ecb1c6531a20",
"bytes": 9540
Expand Down
17 changes: 13 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,10 +74,10 @@ A bot reaches Cstack in one of two ways. `cli.py` runs one JSON file to the end,
```json
{ "mcpServers": { "cstack-example": {
"command": "/path/to/cstack/.venv/bin/python",
"args": ["-B", "/path/to/cstack/tools/cstack_mcp.py", "--aor", "example", "--device", "example-host", "--state-root", "/tmp/cstack-state"] } } }
"args": ["-B", "/path/to/cstack/tools/cstack_mcp.py", "--aor", "example"] } } }
```

`--device` names the machine, and `--state-root` is where this bot's ledger and your approvals live. The agent then gets six tools: `aor` (who am I), `start_goal`, `advance` (next phase, with its checkpoint), `decide` (record a call and its expected result), `execute` and `ledger`. Their descriptions walk the agent through the phases.
The server finds this bot's ledger, your approvals and the machine's device name in the state folder that `cstack init` set up (see [Install and run](#install-and-run)). If that setup is missing, it refuses to start and tells you the one command to run, rather than keep a record that would be lost. The agent then gets six tools: `aor` (who am I), `start_goal`, `advance` (next phase, with its checkpoint), `decide` (record a call and its expected result), `execute` and `ledger`. Their descriptions walk the agent through the phases.

Cstack doesn't start your agents. Each agent connects to its own server; the shared registry, ledgers and approval channel are what make them one team. With `--fleet-mail`, bots can also leave each other messages. Either way, the core walks the goal through the POODO phases and applies each call's effect: `allow` runs it, `ask` waits for you, `deny` refuses it. Which bot may do what is set in `aors/fleet.json`, a file you own. Nothing in a request, a bot's output or a tool's reply can raise its own permissions.

Expand All @@ -96,7 +96,15 @@ npm ci --prefix adapters/workcell-toolchain --ignore-scripts --no-audit --no-fun
cp cstack.config.example.json cstack.config.json
```

The `npm` step installs the pinned compiler for code-writing runs; the approval example runs without it. `ci/requirements.txt` adds what the test suites need. `cstack.config.json` holds your host settings: where the ledger is written and what a code-writing run may use. Now run the example above. To check your install, run the test suite, then the Python, link and trace checks that CI runs:
The `npm` step installs the pinned compiler for code-writing runs; the approval example runs without it. `ci/requirements.txt` adds what the test suites need. `cstack.config.json` holds your host settings: where the ledger is written and what a code-writing run may use. Now run the example above.

Before you point an agent at Cstack, set up this machine once:

```sh
python -B tools/cstack_init.py
```

`cstack init` makes a private state folder, a signing key for each bot in `aors/fleet.json` and a durable ledger that survives restarts. Tailscale is optional. Run it again after adding a bot; it keeps what exists and adds what is missing. `--check` reports health without changing anything. [Set up Cstack](docs/guides/how-to/set-up.md) explains each part. To check your install, run the test suite, then the Python, link and trace checks that CI runs:

```sh
python -B -m unittest discover -s tests
Expand All @@ -109,6 +117,7 @@ The [first-run tutorial](docs/guides/tutorials/first-run.md) walks through three

| Task | Guide |
|---|---|
| Set up a machine so bots keep a durable ledger | [Set up Cstack](docs/guides/how-to/set-up.md) |
| Approve calls from a terminal or an answer file | [Approve ask calls](docs/guides/how-to/approve-asks.md) |
| Name your bots, what they own and what needs your approval | [Define your bots](docs/guides/how-to/define-bots.md) |
| Let a real model write forge code (Claude Code subscription login) | [Use a real model](docs/guides/how-to/use-a-real-model.md) |
Expand Down Expand Up @@ -143,7 +152,7 @@ It ends with `"assessment": "candidate_passed"` and a receipt naming the compile
- Early template. There is no tagged release; `main` is the supported version.
- The bundled tools are read-only calculations and checks. Tools with outside effects, such as sending email, are yours to add: as a Foundation, or as an external MCP tool server through `adapters/mcp_stdio_client.py`.
- Workcells and Foundations run as child processes with deadlines and output limits. Neither is an OS sandbox for hostile code.
- The ledger is written on one machine. A compromised machine can rewrite its own ledger before anyone else sees it; it is not an independent witness.
- The ledger is written on one machine. A compromised machine can rewrite its own ledger before anyone else sees it; it is not an independent witness. `cstack init`'s two witness keys live on the same machine; see [witnesses](docs/guides/how-to/set-up.md#witnesses).
- `tools/scheduled_approvals.py`, the owner's tool for answering a bot's asks, doesn't yet find asks in the per-domain ledger files that MCP sessions write. See [approve ask calls](docs/guides/how-to/approve-asks.md#answer-a-bots-asks).
- A forge goal runs one model at a time. EndoForge's parallel coding agents and its caching are not wired in yet.
- Results are observations, not engineering, safety or compliance approvals. See [limitations](docs/guides/explanation/limitations.md).
Expand Down
Loading
Loading