Repository navigation
Rewrite the README and docs index for a first-time reader - #80
Conversation
The README now leads with what Cstack is, why you would use it, a real approval run with its hash-chained events, a diagram of the real flow and a copy-paste install. Task detail moved into how-to guides (approve asks, define bots, use a real model, add a domain, merge train), the Foundations and pins section into an explanation page, and the old Measured table into docs/verification as a historical record. The docs index leads with reader tasks and keeps the control documents unchanged under Engineering records. check_readme.py now runs the trace suite the README names and treats the clone and cd lines as its own setup; a new test fails when a README command has no check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hes differ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oday Describe EndoForge as the runtime where coding agents build real software. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
The README already had no Measured table on this branch. It now points to the generated test report, which names its commit, and to the kept November measurements. The one kept row that ran against the harden-tools branch with no recorded commit is removed. The README ledger example now shows hashes from a run at the merge with main, and the pins page describes reasoning/poodo as the partial sync that SOURCE-PINS.json lists. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3ee72c7785
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - its branch is in scope: `coordinator/*` branches, and `worker/*` branches whose files all sit in the iteration paths listed in the tool's docstring, and | ||
| - it merges cleanly. | ||
|
|
||
| Platform-core paths (`poodo_core/`, `adapters/`, `contracts/`, `tools/`, `tests/` and others) are never merged by the train; they wait for review. It squash-merges, never deletes branches and never force-pushes. |
There was a problem hiding this comment.
Describe the coordinator exception to core-path exclusions
When the train runs with its documented default --policy all, coordinator branches can merge changes to tools/, tests/, bootstrap.py, and .github/; those paths do not necessarily wait for review. In tools/merge_train.py, in_scope() exempts coordinator branches from the general CORE exclusion and rejects only poodo_core/*, adapters/*, contracts/*, and examples/interface/* for them. Calling in_scope() with a coordinator branch and a file in each of the former paths returns true. Narrow this guarantee and explain the coordinator exception so operators do not enable unattended merges believing those paths are protected.
Useful? React with 👍 / 👎.
in_scope() lets coordinator/* branches change tools/, tests/, bootstrap.py, cli.py, extensions/, vendor/, .github/ and foundations/ under the default --policy all; only poodo_core/, adapters/, contracts/ and examples/interface/* stay out for them. worker/* branches may change examples/interface/*. The guide claimed tools/ and tests/ always wait for review. It now shows scope per branch, the coordinator exception and --policy low-risk for unattended runs, notes that the branch-slug check is off without a lane list, and shows output re-run today. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7402197c58
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Status and limitations | ||
|
|
||
| - 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`. |
There was a problem hiding this comment.
Explain the effect wiring required for side-effecting Foundations
When adding an email-sending Foundation through the linked domain guide, registering it in bootstrap.DOMAINS does not make it use the registry's send: ask policy: bootstrap.build_aor_session() assigns every registered domain the read effect, and AorSession derives approval requirements from that assigned effect. With the example bot's read: allow, the new tool would therefore execute without approval. Qualify this extension advice to explain that side-effecting domains also require host-side effect classification changes; adding a Foundation alone does not preserve the approval guarantee described above.
Useful? React with 👍 / 👎.
Update 2026-11-10: brought up to date with main
Merged
origin/mainat3d6998a(merge commita08a1c0; no force-push). Main had gained the re-vendored foundations (#82) and the backfill-review ledger fixes (#81).Conflicts: only
EXPORT-MANIFEST.json. Main's copy was taken in the merge, then the manifest was rebuilt withtools/build_export_manifest.pyafter the docs changes (1236 files).docs/guides/tutorials/first-run.mdmerged cleanly and keeps main's new.recoveredwording.Facts re-checked against the merge result:
tools/tty_approve.py): same prompt and request digest60f2b7ba...; 9 events,observation_echoed. Hashes 1-6 matched the README; rows 7-9 differ because the approval id changes per run, so the README table now shows this run's hashes. Without--approver:run_statusstopped,execution_certaintynot_dispatched.candidate_passed, AssemblyScript0.28.20, 12 calls,cgroup: unavailable.cstack-example; toolsaor, start_goal, advance, decide, execute, ledger.bootstrap.py; vendor and foundation paths in "What's inside" and "Related projects" exist; the registry marks send, payment, post, filing and delete asask.scheduled_approvals.pylimitation still holds: Durable ledger rolls back a failed open; unknown attempts survive session end #81 changed only howbootstrap.pynames a finished core ledger (.closedor.recovered).read_witnessedstill opens only the node log.foundations-and-pins.md:reasoning/poodo/is now described as the partial sync thatcontracts/SOURCE-PINS.jsonlists (poodo_skill,status: partial-sync), not as an "earlier snapshot".F-7 closed (
docs/assurance/assurance-record.md). The README has no Measured table. It now points to the generated STR-baseline, which names its commit (b3f609b, on main). Indocs/verification/measured-2026-11.mdevery commit named is an ancestor of main (e2efa37,e02a0c4,7225ae9,66420c3, checked withgit merge-base --is-ancestor). The one row that rancheck_readme.pyagainst theharden-toolsbranch recorded no commit and was removed. No new figures were added.Checks at head
3ee72c7(Python 3.12, Node 26.13.0):PATH="$PWD/.venv/bin:$PATH" bash ci/run-local.sh links trace:check_links: 1428 paths checked, 0 broken, 0 stale allowlist entries;check_trace: 77 requirements, 76 with tests, 1 listed gaps; 76/76 test files traced; 0 failures..venv/bin/python -B -m unittest tests.test_readme_tools: 8 tests, OK.heavy-run -- python -B -m unittest discover -s tests: 734 tests, OK (skipped=3).heavy-run -- bash ci/run-local.sh python links trace: rc 0, every Foundation suite OK.heavy-run -- python -B tools/check_readme.py --branch docs/reader-first(fresh local clone, including pip and npm install):{"commands": 17, "failed": 0, "uncovered": 0, "skipped_needs_gh": 0, "skipped_needs_claude": 0}.Original description (2026-11-09)
Rewrites the root README and the docs index for a first-time reader (Craig, 2026-11-08: "the main readmes need to be much much much better"). The NASA control documents are unchanged and now sit behind one "Engineering records" section.
Before and after: first paragraph
README now
python -B cli.py --approver < examples/ask-approval.jsonand the run's nine hash-chained events (from a run on this branch), with POODO explained.flowchart TD) of the real flow (cli.py or MCP server -> core -> allow/ask/deny -> adapter -> pinned Foundation -> result -> log), the MCP server entry and its six tools.Patterns taken from ripgrep, uv and Litestream READMEs: one sentence naming the category, a real example near the top, a highlights list that links onward, and one plain safety statement.
Moved, not lost
docs/guides/how-to/approve-asks.md(plus MCP asks)docs/guides/how-to/define-bots.mddocs/guides/how-to/use-a-real-model.mddocs/guides/how-to/add-a-domain.md(now names every piece: schema, adapter, extension, inventory row, pin, register call)docs/guides/how-to/merge-train.md(scope corrected from the tool's docstring: branch scope and platform-core paths, not "the bot's slice")docs/guides/explanation/foundations-and-pins.mddocs/verification/measured-2026-11.md, kept as written, marked historicaldocs/README.mdleads with Learn / Do a task / Look something up / Understand the design, then Engineering records (control-document table, verification records, family standard) unchanged. Anchors updated in SUM-MAP, AGENTS.md, guide indexes and the tutorial.Docs audit
run-local.sh python linkswhile the README saidpython links trace, so the README command was uncoveredtest_every_readme_command_has_a_check)Every command shown was run on this branch: the approval prompt (via
tools/tty_approve.py),--approver=deny, answer file, invalid answer file (invalid_or_unsupported_request), forge stub (re-run after merging origin/main:candidate_passed, AssemblyScript 0.28.20, 12 calls,cgroup: unavailable), registry validation (owner-via-approver), the MCP server from another cwd (six tools),merge_train.py --wipand--dry-run --policy low-risk,scheduled_approvals.py brief, and the approval example without the npm step.Defect found (not fixed here; needs a code lane)
tools/scheduled_approvals.pycannot see asks from MCP sessions. With a witnessed ledger configured,bootstrapgives each core its own file at<log without .jsonl>/<bot>/<domain>.jsonl, butread_witnessedopens only the node log named inledger.json. Reproduced: anasksession returnedapproval_pending,briefprinted "nothing waiting on you", andanswerrefused with "is not pending in any readable ledger". Without a witnessed ledger the session ledger is memory only, so the channel can never see it either.tests/test_mcp_driving_adapter.pypasses because it writes the approval withApprovalWriterdirectly. Documented as a limitation in the README and approve-asks guide.Cold-read scores (fresh no-context subagent, rendered README text only)
Every round since 2 described the project correctly; the remaining confusions are about depth of use, the forge section and the domain mix. The gate (9 with no confusion about what it is) is not met. The single change every reader asked for, an end-to-end MCP walkthrough with an owner approving from another shell, cannot be shown truthfully until the approval-channel defect above is fixed. I wrote such a demo and it failed on that defect, so it is not included.
About
Proposed cstack About, to set when this merges: "Cstack (code name Mjölnir): a local-first system for building and running software with AI agents under your control. One control core owns goals, decisions, permissions and evidence; Foundations supply domain checks; risky actions wait for a human. GPL-3.0-only."
EndoForge is described per Craig's correction as the runtime where coding agents build real software (finds, reuses or generates code, checks it in V8-isolate workcells against an independent evaluator, records results in a tamper-evident ledger).
Local checks
Python 3.12.14, Node 26.13.0, after merging origin/main (7ebda4d), via heavy-run:
python -B -m unittest discover -s tests: 729 tests OK, 3 skipped (also inside run-local, normal and -O).bash ci/run-local.sh python links trace: Foundation suites all OK; check_links 1420 paths, 0 broken; check_trace 77 requirements, 76/76 test files traced, 0 failures.test_every_readme_command_has_a_check: fails on the old check_readme.py, passes now.tools/check_readme.pyend to end (fresh clone, about 25 minutes); its individual commands were run by hand as listed above.🤖 Generated with Claude Code