Apply lessons from arthyn/notes PRs #3 and #4#2
Open
arthyn wants to merge 4 commits into
Open
Conversation
Both PRs retrofit an LLM-generated notes Gall agent to tloncorp idioms; each commit's title is a rule the LLM didn't apply correctly the first time. Folding the load-bearing ones into the reference. architecture.md - ACUR section: show inner a-group/c-group, add four principles (outer carries identity / src.bowl IS the actor / fat updates / a-c split is a trust boundary) - State migration: forbid the state-N-to-current cascade explicitly; always state-N-to-N+1 chained via =? - Mark system: typed marks for peek endpoints (++grow ++json does encoding; agent returns raw typed value) patterns.md - =* audit pass criteria; faces default to the type name - Cast (^+) above assertions - Per-entity engines via abed/abet (worked se-core example) - Helper-arm extraction at three repeats; inline ?~ name=expr - |^ (kelt) for arm-scoped helpers - Tuple types with * for don't-care parts - Same-subject cell collapse [a b c]:subject (with last-element caveat) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lead with =face:type as the default rather than introducing it as a follow-up. Add a "When to use a semantic face instead" subsection covering disambiguation cases (old/new, src/dst, placeholder/real, shadowing collisions) — the type-name default is the rule, semantic faces are the exception when role > type-tag. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ance The original example showed peek arms with a get-book helper, but the notes refactor didn't actually fix those via a helper — it moved them into ++no-peek inside no-core (per-entity engine). That conflated two different cleanup moves. - Replace the example with ++strip-query: a true stateless one-liner used 3+ times in HTTP handlers. Pure function of its argument, no hidden entity load. - Add a "When restructuring beats a helper arm" subsection: if every call site does load-id-then-reach-into-fields, the helper-arm collapses only the first line — the real fix is an abed sub-core where load + permission live in one place. Cross-references the Per-Entity Engines section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two more rules from arthyn/notes#4 follow-up commits (68e0e1a, b6b8d48). architecture.md - New "Always poke the host" subsection in ACUR: the action handler emits a poke to ship.flag unconditionally; Gall loops self-pokes back through +poke %notes-command. Removes the host/sub branch from the action layer entirely. c-command processing becomes the single dispatch point for all state-changing logic. - New "State fields resolve without .state" callout under standard boilerplate: =| / =* state - puts state at subject head, so wing search finds books, invites, etc. directly. Prefer the unprefixed form except where local shadowing forces it. patterns.md - Updated existing examples (Tuple Types with *, Per-Entity Engines) to use books / cor(books ...) instead of books.state / cor(books.state ...) for consistency with the new rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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
arthyn/notes#3 (merged) and arthyn/notes#4 (open) retrofit an LLM-generated %notes Gall agent into tloncorp shape. Each commit's title is a rule the LLM didn't apply correctly the first time, so the commit log is a punch list of doc gaps. This PR folds the load-bearing ones in.
architecture.mda-group/c-group(previously only the outer wrapper was illustrated), with four explicit principles — outer carries identity,src.bowlIS the actor, updates are fat, the a-/c- split is a trust boundary.state-N-to-currentcascade explicitly. Alwaysstate-N-to-N+1, chained via=?inon-load.++grow ++jsondoes the encoding; agent returns raw typed values from+on-peek.patterns.md=*audit pass criteria: explicit=/vs=*vs inline decision rules.=/ notebook=notebook:novernb; use=face:typeshortcut where the face matches the type name.^+ se-coreimmediately after the gate sample, then?>.se-coreexample showing load → mutate → write-back.++get-book-style; inline?~ name=expr.|^for arm-scoped helpers: nest+poke-only handlers inside the arm.*:=/ entry=[=net:n *]when half is unused.[a b c]:subjectshorthand, with the load-bearing "must be the last sub-expression" caveat (counter-example included).Deliberately not included
json+!>(~)to bare~for absent peek results — conflicts withsimple-agent-primer.md's~=blocking /[~ ~]=invalid distinction; needs verification against homestead before flipping the canonical advice.?:chains with?-/?+in poke dispatch — already covered.Test plan
🤖 Generated with Claude Code