Skip to content

Refine Article XV / X — /chat contract, not transport#5

Open
kody-w wants to merge 1 commit into
refactor/strip-t2tfrom
refactor/refine-article-xv
Open

Refine Article XV / X — /chat contract, not transport#5
kody-w wants to merge 1 commit into
refactor/strip-t2tfrom
refactor/refine-article-xv

Conversation

@kody-w

@kody-w kody-w commented Apr 21, 2026

Copy link
Copy Markdown
Owner

Summary

Refines the tier-parity article so the constitution matches the actual intent: Tier 1 stays Copilot-only for training simplicity; Tier 2 is where the user picks which AI runs in their cloud deployment.

The original Article XV (as written in PR #1) conflated two things: the /chat contract callers see, and the LLM transport running below it. Its rules-out list said:

❌ A Tier-1-only LLM provider path (e.g. Copilot-only) that Tier 2 has to re-implement. Provider dispatch is shared.

That sentence rules out the architecture we actually want.

What changes

Articles renamed in both src/CONSTITUTION.md (Article XV) and rapp_brainstem/CONSTITUTION.md (Article X):

"Tier Parity Is a /chat Contract, Not a Transport"

What must be identical across tiers (the contract):

  • Request envelope: user_input, conversation_history, session_id.
  • Response envelope: response, voice_response, twin_response, session_id, agent_logs, provider, model.
  • Tool-calling loop shape.
  • |||VOICE||| / |||TWIN||| split (and twin sub-tags).
  • Agent contract (BasicAgent + perform()). Agents that run on Tier 1 must run unmodified on Tier 2.
  • State layout (.brainstem_data/ on Tier 1, BRAINSTEM_HOME on Tier 2; same shape inside).

What may legitimately differ (the transport):

  • Mount point for state.
  • LLM transport. Tier 1 stays Copilot-only. Pushing to the RAPP cloud swarm is the moment the user declares which AI runs there — Azure OpenAI, OpenAI, Anthropic, or whatever the deploy target gives access to. That decision lives on the cloud side because it's the cloud operator's constraint, not the learner's.

Rules-out list updated:

  • Removed: "❌ A Tier-1-only LLM provider path… Provider dispatch is shared."
  • Added: "❌ Adding an LLM provider to Tier 1 that breaks the one-liner install. Default posture: don't — put provider choice on the cloud-deploy side where it already lives."

Stacked on PR #1

Branch is refactor/refine-article-xv → refactor/strip-t2t. The articles being refined here only exist on PR #1. When #1 merges, this retargets to main automatically.

No code changes, no test changes

Pure governance doc update. Nothing to run.

🤖 Generated with Claude Code

@kody-w @claude
Refine Article XV / X — tier parity is a /chat contract, not a transport
d5a8438 
The original Article XV (and its mirror, Article X in
rapp_brainstem/CONSTITUTION.md) conflated two things: the /chat
contract that callers see (envelope + loop + split + agent behavior +
state layout) and the LLM transport that runs underneath it. The
bullet "❌ A Tier-1-only LLM provider path (e.g. Copilot-only) that
Tier 2 has to re-implement. Provider dispatch is shared." rules out
exactly the architecture we want.

Tier 1 is Copilot-only by design:
  • One auth chain (gh CLI), one provider, one training story.
  • Zero extra config for new users — the one-liner install is sacred
    (Article V).

Tier 2 is multi-provider by design:
  • Pushing to the RAPP cloud swarm is the moment the user declares
    WHICH AI their cloud deployment uses (Azure OpenAI, OpenAI,
    Anthropic, or whatever the deploy target gives access to).
  • Provider choice lives there because it's the cloud operator's
    constraint, not the learner's.

Both tiers still produce the same response envelope and run the same
tool-calling loop shape. That's the invariant tier parity actually
requires.

Changes:
  • Rename article: "Tier Parity Is a /chat Contract, Not a Transport"
    (both src/ and rapp_brainstem/ copies).
  • Enumerate what must be identical (envelope, loop shape, split,
    agent contract, state layout) vs. what may legitimately differ
    (mount point, LLM transport).
  • Replace the "provider dispatch is shared" rules-out with a clearer
    "don't add providers to Tier 1 that break the one-liner — put
    provider choice on the cloud-deploy side."
  • Call out explicitly that pushing to the cloud swarm is where
    LLM requirements get declared.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 21, 2026
Merged
Merged
kody-w added a commit that referenced this pull request Apr 25, 2026
@kody-w @claude
Content Strategy: cross-medium distribution + 30-day calendar
6e17a1d 
Adds the public-distribution companion to Blog Roadmap. The vault is the
source of truth; the blog anchors each week; Newsletter / YouTube /
TikTok / X / LinkedIn / Instagram each get a different cut of the same
essay. Re-shape per channel; never copy-paste.

NEW VAULT NOTE
- pages/vault/Plans & Ledgers/Content Strategy.md (living doc) -- per-
  channel principles, cadence per channel, content matrix mapping each
  blog post type to which channels rebroadcast it, 30-day launch
  calendar tied to blog posts #1-#5 from Blog Roadmap, voice & style
  rules, cross-promotion mechanics, analytics minimum, what-this-rules-
  out, when-to-reconsider checkpoints.

DOCUMENTATION ROADMAP -- new build-out tasks
- Channel setup (newsletter, X, LinkedIn, YouTube, TikTok, Instagram) --
  claim handles, profile bios, link surfaces.
- Channel voice + visual style guides -- one-pager per channel inline
  in Content Strategy.
- Production templates (code-screenshot palette, YouTube intro
  convention, X-thread skeleton, LinkedIn-article header) at
  pages/vault/Blog Drafts/templates/.
- First-30-day content calendar execution -- run weeks 1-4 from
  Content Strategy; each blog post fans out to newsletter + X thread +
  TikTok + LinkedIn + occasional YouTube.
- Channel-specific recurring formats -- YouTube workshop series + Why-
  we-did-X series; TikTok 60-sec builds; X weekly threads; LinkedIn
  monthly long-form. Produce the first 3 episodes of each.
- Analytics surface -- Plausible or equivalent on kody-w.github.io;
  open-rate / watch-through / replies-and-bookmarks; skip vanity.

WIRING
- _manifest.json: Content Strategy added under Plans & Ledgers.
- _index.md: new entry alongside Blog Roadmap.

CHECKS
- node tests/vault-check.mjs: 52 notes, 697 wikilinks resolve, 0 PII,
  0 failures, 0 warnings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kody-w added a commit that referenced this pull request May 10, 2026
@kody-w @claude
bilateral autobiography agents (scaffolding; paused build)
e5cac32 
Two agents from the bilateral-autobiography demo (#5 from the prior demo
list) that we built but never executed end-to-end before pivoting to
Article XLVII.5 substrate-agnostic federation. Committing them so the
work is checkpointed and discoverable; they're complete and tested for
parsing/import.

- rapp_brainstem/agents/plant_bilateral_neighborhood_agent.py
  Plants a paired-memory neighborhood with two rappids as co-anchors.
  Emits the full Door URL Set + co_planters: [partner_rappid] in
  rappid.json + bilateral.json (rapp-bilateral/1.0 manifest with
  voices) + two souls + canvas.md + entries/. ~280 lines.

- rapp_brainstem/agents/bilateral_weekly_write_agent.py
  Voice-aware LLM-driven entry writer. Reads the voice's soul.md,
  calls claude -p (REAL LLM call per memory rule no-fake-mode),
  commits new entry to entries/<voice-slug>-<date>.md, weaves
  canvas.md. ~200 lines.

To activate: invoke plant_bilateral_neighborhood with my_rappid +
partner_rappid + display_name + purpose. Then bilateral_weekly_write
on a cadence (cron, manual, etc.). The agents are operator-mediated;
they don't auto-execute.

Pivot context: the user redirected to LAN/sneakernet federation
(Articles XLVII.5 → XLVII.5.3) which is now fully shipped. The
bilateral demo can resume any time on top of that substrate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kody-w added a commit that referenced this pull request May 11, 2026
@kody-w @claude
docs: ecosystem-stale-check pass — CLAUDE.md / ECOSYSTEM_MAP / HERO_U…
ff7609e 
…SECASE updated for vbrainstem + .egg cartridges

Same gap-scan technique as SPEC.md §18.10–§18.12, applied to the three
companion docs that index the system for different audiences.

CLAUDE.md (project guide for Claude in future sessions):
- New section "vBrainstem + the .egg cartridge family (the tethered
  surface)" between Visual Anatomy and Key Directories, pointing at
  pages/vbrainstem.html, the .egg cartridge family table, the
  egg_hatcher_agent.py introspection-routing pattern, and the Doorman
  Copilot path
- Key Directories pages/ row updated to call out specialty surfaces
  (vbrainstem.html, sphere.html) explicitly

ECOSYSTEM_MAP.md (the schema + impl map):
- §5 schema table: added rows for brainstem-egg/2.3-session (shipping),
  brainstem-egg/2.3-neighborhood (planned), brainstem-egg/2.3-estate
  (planned), and rappterbox-cart/0.1 (legacy, one-release backwards-compat)
- Disambiguated rapp-vbrainstem-subscription/1.0 row to clarify it's
  the OLDER mobile pages/vbrainstem/index.html, distinct from the new
  pages/vbrainstem.html shipped 2026-05-10
- §6 implementation map: added rows for egg_hatcher_agent.py and
  pages/vbrainstem.html with full descriptions

HERO_USECASE.md (the canonical scenarios):
- §1 Charizard table: 6 of 8 existing rows expanded to also reference
  pages/vbrainstem.html alongside the doorman; added two new ✅ rows:
  "Live tethered group chat (vs. one-way egg trade)" and "One hatcher
  routes any cartridge kind"
- Acceptance criteria #5 added: live tethered group-chat session via
  vbrainstem.html, both screens synced, session-as-cartridge portable

No changes to §0–§17 of any spec; per the addendum discipline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kody-w added a commit that referenced this pull request May 11, 2026
@kody-w @claude
docs: full ecosystem-stale-check sweep — every spec doc + Constitutio…
5b79342 
…n Article L

After SPEC.md §18.10–§18.12 + CLAUDE.md/ECOSYSTEM_MAP/HERO_USECASE were
brought current earlier today, this sweep closes the gap across every
remaining spec + governance doc so today's ship (egg-cartridge unification
+ tethered vBrainstem) is properly cross-referenced ecosystem-wide.

Files touched (surgical insertions, no rewrites of frozen sections):

Root specs:
- ECOSYSTEM.md §8 — egg-cartridge family table inserted (5 variants)
- OSI.md L4a + L6 — pages/vbrainstem.html added as canonical implementation;
  brainstem-egg/2.3-* added to envelope schemas
- NEIGHBORHOOD_PROTOCOL.md §5a — vbrainstem.html cross-reference for the
  WebRTC tether channel
- SURVIVAL.md — estate-egg called out as the disaster-recovery primitive
  for the operator's whole multi-tier identity
- MASTER_PLAN.md Part 1 — .egg family unification noted in the "use eggs
  to share organisms" point
- README.md — vBrainstem tether bullet added to Notable Features
- CONSTITUTION.md — Article L appended (DRAFT — operator review needed)
  formalizing ".egg is the universal portable unit"

pages/docs/:
- SPEC.md — already updated (§18.10/§18.11/§18.12 from prior commit)
- PUBLIC_PRIVATE_BOUNDARY.md §1 — estate-egg cross-reference
- ESTATE_SPEC.md — estate-egg as the missing identity-portability primitive
- AGENTS.md — egg_hatcher_agent.py added to notable kernel agents
- skill.md — five-kind cartridge family explained alongside existing
  egg_hatcher mention
- ROADMAP.md — "Recently shipped 2026-05-10" section at the top
- SUBSTRATE_FEDERATION.md — substrate #5 (WebRTC tether) added to the
  four-substrates table; cartridge-as-substrate-agnostic-transport noted
- VERSIONS.md — 0.15.x version row + new schema version registry table
- rapplication-sdk.md — distribution-as-egg-cartridge note in intro

Other:
- pages/_site/index.json — new "Surfaces" section listing pages/vbrainstem.html
  and pages/sphere.html (both were missing from canonical site nav)
- rapp_brainstem/CLAUDE.md — egg_hatcher_agent.py + bond.py rows added to
  Key Files
- pages/vault/Decisions/2026-05-10 — Egg cartridge unification + tethered
  vBrainstem ship.md — the WHY-doc for today's architectural decisions
  (load-bearing per CLAUDE.md vault discipline)

Article L (Constitution) is marked DRAFT — operator should review the
prose voice (the cadence of XLVII–XLIX is the operator's; AI-authored
articles need ratification or rewrite). The principle is correct; the
language may need tightening.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kody-w