Skip to content

Rewrite the README and docs index for a first-time reader - #80

Merged
Akilleez-QA merged 9 commits into
mainfrom
docs/reader-first
Nov 10, 2026
Merged

Akilleez-QA merged 9 commits into
mainfrom
docs/reader-first

Conversation

@Akilleez-QA

@Akilleez-QA Akilleez-QA commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Update 2026-11-10: brought up to date with main

Merged origin/main at 3d6998a (merge commit a08a1c0; 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 with tools/build_export_manifest.py after the docs changes (1236 files). docs/guides/tutorials/first-run.md merged cleanly and keeps main's new .recovered wording.

Facts re-checked against the merge result:

  • Approval example re-run on a real pty (tools/tty_approve.py): same prompt and request digest 60f2b7ba...; 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_status stopped, execution_certainty not_dispatched.
  • Forge stub goal: candidate_passed, AssemblyScript 0.28.20, 12 calls, cgroup: unavailable.
  • MCP server from another directory: server cstack-example; tools aor, start_goal, advance, decide, execute, ledger.
  • Six domains registered in bootstrap.py; vendor and foundation paths in "What's inside" and "Related projects" exist; the registry marks send, payment, post, filing and delete as ask.
  • The scheduled_approvals.py limitation still holds: Durable ledger rolls back a failed open; unknown attempts survive session end #81 changed only how bootstrap.py names a finished core ledger (.closed or .recovered). read_witnessed still opens only the node log.
  • foundations-and-pins.md: reasoning/poodo/ is now described as the partial sync that contracts/SOURCE-PINS.json lists (poodo_skill, status: partial-sync), not as an "earlier snapshot".
  • CHANGELOG: added an Unreleased entry for this PR.

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). In docs/verification/measured-2026-11.md every commit named is an ancestor of main (e2efa37, e02a0c4, 7225ae9, 66420c3, checked with git merge-base --is-ancestor). The one row that ran check_readme.py against the harden-tools branch 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

  • Before: "Cstack: template for a bot fleet under one human approver (GPL-3.0-only)", then the Mjölnir line and a classification paragraph ("self-assessed Class E analog under NPR 7150.2D ...") above the quickstart.
  • After (purpose from contracts/DECISION.md ADR 001 and DECISION-005; needs coordinator approval before merge): "Cstack is a local-first system for building and running software with AI agents under your control. One control core owns every goal, decision, permission and piece of evidence. Domain packages called Foundations plug in to supply exact knowledge and checks. EndoForge, its software engine, is meant to generate code that the core evaluates, then activates, keeps or throws away. Anything risky waits for one human to approve it." It is followed by an honest "What works today / Not yet" paragraph, then why, a real approval run, a diagram and the install.

README now

  1. One-sentence definition, what a bot and "template" mean.
  2. Why: four concrete bullets.
  3. See it work: the real terminal approval prompt from python -B cli.py --approver < examples/ask-approval.json and the run's nine hash-chained events (from a run on this branch), with POODO explained.
  4. How it works: Mermaid (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.
  5. Install and run, then the forge goal (stub transport) as "Bots that write code".
  6. What you can do (links to guides), what's inside, status and limitations, related projects, engineering records (classification line once), license unchanged.

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

From README To
CLI approval docs/guides/how-to/approve-asks.md (plus MCP asks)
Define your bots docs/guides/how-to/define-bots.md
Real model transport, resume, outcome_unknown docs/guides/how-to/use-a-real-model.md
Add a domain docs/guides/how-to/add-a-domain.md (now names every piece: schema, adapter, extension, inventory row, pin, register call)
Wire the merge train 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")
Foundations, How pins work docs/guides/explanation/foundations-and-pins.md
Measured table docs/verification/measured-2026-11.md, kept as written, marked historical
Layout README "What's inside"

docs/README.md leads 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

Doc Stale or wrong claim found Fixed
README Taglines disagreed with About; classification in intro; "stays inside its bot's slice" for the merge train; Measured table mixed commits/branches Yes
tools/check_readme.py Ran run-local.sh python links while the README said python links trace, so the README command was uncovered Yes, with a failing-first test (test_every_readme_command_has_a_check)
how-to/README, explanation/README Pointed at README sections Now point at real guides
approve-asks (new) MCP approval channel limitation, see Defects Documented

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 --wip and --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.py cannot see asks from MCP sessions. With a witnessed ledger configured, bootstrap gives each core its own file at <log without .jsonl>/<bot>/<domain>.jsonl, but read_witnessed opens only the node log named in ledger.json. Reproduced: an ask session returned approval_pending, brief printed "nothing waiting on you", and answer refused 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.py passes because it writes the approval with ApprovalWriter directly. Documented as a limitation in the README and approve-asks guide.

Cold-read scores (fresh no-context subagent, rendered README text only)

Round Score Main confusions it reported
Before (main) 3/10 First command's purpose; undefined POODO, AOR, workcell, Foundation, grant; NASA classification near the top; no sample output; Measured table inconsistent
1 6/10 "template" vs framework; bot undefined; POODO not expanded; forge jargon
2 7/10 POODO in practice; too many terms; trivial echo example; no MCP config
3 7/10 Permissions in two places; forge feels like a second product
4 7/10 Ledger vs log; Node needed?; no MCP snippet
5 7/10 Can it wrap side-effecting tools?; who writes checkpoints; does the agent block?
6 7/10 Wanted an end-to-end MCP walkthrough
7 7/10 Same; "team" coordination
9 7/10 Same; plus the documented approval-channel limitation reads as the main MCP path being partly broken
10 (purpose-led opening) 7/10 Opening (building software) vs Why (governing tool calls) felt like two products; fixed by tying Why to both; domain mix; NASA note

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.
  • New test test_every_readme_command_has_a_check: fails on the old check_readme.py, passes now.
  • Last commit (README opening only) re-checked with check_links, check_trace and tests/test_readme_tools.py: all pass.
  • Not run: tools/check_readme.py end to end (fresh clone, about 25 minutes); its individual commands were run by hand as listed above.

🤖 Generated with Claude Code

Akilleez-QA and others added 4 commits November 8, 2026 22:12
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>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-10T11:00:38.097327Z 7402197 New commits
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

Akilleez-QA and others added 4 commits November 10, 2026 04:36
Brings in the re-vendored foundations (#82) and the backfill-review
ledger fixes (#81). EXPORT-MANIFEST.json conflicted; main's copy is
taken here and the manifest is rebuilt after the docs changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
@Akilleez-QA

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/guides/how-to/merge-train.md Outdated
- 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread README.md
## 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`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

@Akilleez-QA
Akilleez-QA merged commit 8e92f7b into main Nov 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant