Restructure documentation: condense thesis, add RFC collection - #3
Open
andreisavu wants to merge 5 commits into
Open
Restructure documentation: condense thesis, add RFC collection#3andreisavu wants to merge 5 commits into
andreisavu wants to merge 5 commits into
Conversation
Distill the design ideas behind weakincentives/weakincentives into 14 implementation-agnostic RFCs specifying what a state-of-the-art library for unattended agents should look like: the definition ring (instruction graph, transactional tools, policies, feedback/completion gates, event ledger), the environment ring (workspace/sandbox/egress, capabilities and injected time), and the control plane (execution envelope, work distribution, run records, adapter certification, versioned overrides and experiments, evaluation). README changes: link the RFC collection, add two tenets (make the correct path the easy path; evaluation is the control loop), extend the reference architecture with egress/credential posture, the canonical transcript, and hash-anchored versioned iteration, add an upgrade-gating success scenario, and reflect the additions in the boundary diagram. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JgQvogiHxBzof7Cd7LYita
Fold reviewed decisions into normative text and add a decision log to the RFC index: 1. Policies gate the full action surface, including native harness tools, via adapter pre-action hooks; harnesses without an interception point declare the capability absent (RFC-0004, RFC-0012). 2. The transcript becomes the storage substrate: one append-only event stream per run, with conversation, state, and operational views as projections; definition-plane appends are authoritative while harness-derived mirroring stays best-effort (RFC-0006, RFC-0011). 3. Dead-letter and retriability classification move to the definition, declared against the typed error taxonomy; the adapter error-translation layer is named as the load-bearing encapsulation boundary (RFC-0010, RFC-0012). 4. Analysis agents are report-only and must emit structured findings with evidence references and machine-actionable proposals (RFC-0014). 5. The adapter floor is Core tier plus transcript emission (RFC-0012). Also update the root README state-contract paragraph, the glossary, and open-question sections; add new open questions surfaced by the decisions (cross-source ordering on the unified stream, deny-with-reason hook expressiveness, structured-finding schema). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JgQvogiHxBzof7Cd7LYita
Remove the trailing open-questions sections from all RFCs rather than parking implementation-level choices as future work. Add an "Altitude" convention to the index: RFCs specify observable contracts, and implementation choices that do not change behavior observable through the compatibility surface are deliberately unstated. Keep only the additions that close real contract holes: causal ordering across transcript sources (RFC-0011), sub-agent spend attribution to the parent envelope (RFC-0009), and invariants-over-exact-counts guidance for suite scenarios (RFC-0012). Trim implementation-flavored phrasing from the filesystem protocol and slice-view passages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JgQvogiHxBzof7Cd7LYita
Blocker-driven rewrite of all 14 RFCs, the index, and the README. The narrative: one artifact defines the agent, one stream records the run, explicit bounds contain it, tests prove it ports, evaluation improves it. Blockers fixed: - Ownership contradiction: the README diagram assigned deadlines, retries, and leases to the harness while the RFCs made them control-plane contracts. The diagram is now three boxes (definition / control plane / harness) consistent with RFC-0001's rings and ownership table. - Dependency inversion: the definition-ring state RFC depended on a control-plane RFC for its own substrate. The transcript now lives in RFC-0006 (The Transcript and State, definition ring); RFC-0011 becomes The Run Record. Files renamed accordingly. - Terminology drift: "ledger" (three meanings across nine files) retired in favor of transcript (stream) and slices/views (state). - Repetition: shared motivation hoisted into RFC-0001; per-RFC motivation cut to one paragraph; README FAQ removed with its load-bearing content folded into the principles and worst-cases sections. The README's tenets become twelve principles that the RFCs elaborate. Collection shrinks from 2,735 to 2,002 lines with no contract removed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JgQvogiHxBzof7Cd7LYita
Revise the substrate decision: the ledger — one append-only, high-granularity event stream per run covering conversation, guardrail decisions, state transitions, and operational signals — is the storage abstraction. The transcript is a deterministic projection of what the model saw and did; state slices and metrics are other views. Not every state transition appears in the transcript; nothing escapes the ledger. RFC-0006 becomes The Event Ledger, with an event-class table mapping each class to transcript membership (the model boundary is the membership rule) and a transcript-stuffing anti-pattern. The compatibility oracle moves to the transcript view, where cross-harness parity is meaningful — full-ledger granularity may differ across harnesses. Recording contracts across RFCs 0001-0005 and 0011-0014 now name the ledger; model-visible assertions keep naming the transcript. Decision log entry 2 is superseded in place; glossary gains a Ledger entry; README principle 6 becomes "One ledger". Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JgQvogiHxBzof7Cd7LYita
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
2 participants
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.
Summary
This PR restructures the project documentation to establish a clearer, more actionable foundation for the agent-definition library. The main README is condensed from a lengthy philosophical exposition into a concise statement of the core thesis and nine guiding principles. A new RFC collection in
rfcs/provides detailed, testable contracts for implementing the vision.Key Changes
README.md: Reduced from ~387 lines to ~223 lines
rfcs/README.md (new): Index and overview of the RFC collection
RFC-0001 through RFC-0014 (new): Detailed design contracts
Notable Implementation Details
https://claude.ai/code/session_01JgQvogiHxBzof7Cd7LYita