docs: README refresh + AGENTS.md mirror#39
Merged
Conversation
Accurate-to-source README (graph->fold->operad->kernel layering, four rewrites, M11/M12 gates, HTTP+MCP surface, sweep, seed, build/test) + thin AGENTS.md mirror pointing at ffs0/AGENTS.md as project SOT. No .go changes. authored-by: agent:claude-cowork.hp-z440 / session:sam.z440-cowork-workspace / readme-foldering Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR refreshes the repository documentation to align the README with the current Go runtime implementation, and adds an AGENTS.md “thin mirror” that points back to ffs0/AGENTS.md as the project source-of-truth.
Changes:
- Rewrites
README.mdto document the runtime model (log→fold, operad validation, runtime gates), package layering, and the verified HTTP/MCP surfaces. - Adds
AGENTS.mdas a minimal mirror/entrypoint for contributor rules, repo orientation, branching, and safety constraints.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Major documentation refresh: kernel model, layering map, runtime gates, HTTP API, MCP tools, sweep/seed/build/test guidance. |
| AGENTS.md | New thin mirror pointing to ffs0/AGENTS.md as project SOT; includes repo-specific orientation and contribution rules. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+73
to
+74
| Operad validation (type / port-pair / authority) runs ahead of the gates; `fold` then enforces | ||
| structural invariants and maintains indexes. |
| | `internal/hdc` | hyperdimensional computing | spectral, fiber, crosswalk, encode, live-index. | | ||
| | `internal/mcp` | MCP JSON-RPC | SSE + stdio + Streamable HTTP. | | ||
| | `internal/operad` | type system | `Registry` (ontology **v3.16.2** — 53 node types, WF01–WF21) with `Version` for `/healthz`; strict port-pair `ValidateLINK` (pair must be declared; src/tgt type enforcement), `ValidateMUTATE`; `AdminScopeRewrite`, `SystemInternalEnvelope`, `ResolveSessionForEnvelope`; occupancy + admin-capability walks. | | ||
| | `internal/kernel` | **effect layer** | `Runtime`, `Store`, `LogStore` / `MemStore`. §M11 session-liveness + §M12 admin-capability gates (`liveness.go`). Sweep loop emits WF13 governance proposals on `t_hook.firing_state` transitions. The only place state mutates. | |
|
|
||
| `Runtime.RunTimedSweep` / `SweepTick` runs on its own goroutine every `--sweep-interval` | ||
| (default `30s`, `0` disables). Each tick walks all pending `t_hook`s and, for every hook whose | ||
| predicate fires, **proposes** a WF13 `governance_proposal` (status `pending`). The sweep **never |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft — README refresh + new thin
AGENTS.mdmirror for the Go runtime, matching the ffs0 instruction/README foldering pass.README.md— grounded in the actual source: the rewrite engine ("log is truth, state is derived"), the layering tower graph→fold(catamorphism)→operad(registry)→kernel(only mutator)→transport/mcp, the four rewrites, §M11 liveness + §M12 admin gates + operad validation, the verified HTTP surface (/healthz,/state/*,/log,/fold,/rewrites,/programs,/operad/*,/twin/*,/t-hook,/t-cone), the MCP server (apply_rewrite/apply_program + reads), the 30s sweep (proposes, never auto-applies), seed mode, build/run/test. Corrected stale v3.16.1 → v3.16.2.AGENTS.md— new thin mirror: points atffs0/AGENTS.mdas project SOT; orientation (this repo = the Go runtime; semantic SOT = folded HG +/healthz); the rule; branchingfeat/<purpose-slug>.No
.gochanges.