@smartergpt/lexrunner 1.0.0

package/docs/thesis/00-EVOLUTION-NOTES.md

@@ -0,0 +1,383 @@
+# 📘 Lex Architecture – Evolution Notes (v0.1)
+
+_A formal memory of newly crystallized concepts and commitments_
+
+> This document records the emergent lessons, abstractions, and design goals recognized through field experiments, critical discussion, and collaborative reasoning.
+> It is not a manifesto, nor a promise — but a map of what has been learned and what is now believed to matter.
+
+---
+
+## 1. Core Shift in Understanding
+
+### 1.1 From "AI helpers" → **Governed cognitive collaborators**
+
+- The goal is not to make models "better at code."
+- The goal is to reduce **coordination cost**, **environmental hostility**, and **friction**, so that agents can reliably contribute within constraints.
+
+### 1.2 From "libraries" → **portable cognitive architecture**
+
+Lex is increasingly understood as:
+
+> a system for structuring interactions between minds, environments, and values
+
+Not:
+
+- a suite of tools
+- or a library of utilities
+
+It is **portable** because:
+
+- the value is in governance primitives
+- not in implementation details or provider-specific affordances
+
+### 1.3 From "capability amplification" → **coordination cost compression**
+
+We are not making weak models strong.
+
+We are:
+
+- reducing the work required to make intelligent decisions
+- aligning agent behavior with engineering norms
+- and externalizing context so reasoning is stable across turns and models
+
+---
+
+## 2. Fundamental Insight: Environmental Hostility
+
+> Machine performance degrades in proportion to environment hostility, NOT model capacity.
+
+Environment hostility includes:
+
+- unclear constraints
+- opaque requirements
+- unbounded problem surfaces
+- missing receipts and traceability
+- punitive error dynamics
+- fragmented state
+- model switches with no continuity
+
+Our work (Lex, AX, LexRunner, minimal clones like "Robert") demonstrates:
+
+> If you progressively de-hostilize the environment, models can behave like reliable collaborators — regardless of which model is driving.
+
+This is **the primary strategic insight.**
+
+---
+
+## 3. New Operational Construct: Turn and Turn Cost
+
+Tokens measure **thinking cost**.
+Turns measure **problem-solving cost**.
+
+Turns are expensive because they incur:
+
+- latency
+- context resets
+- prompt renegotiation
+- token bloat
+- human attention switches
+
+### Turn definition
+
+> A turn is a cycle of perception → reasoning → action that produces observable change.
+
+### Turn Cost definition
+
+```
+TurnCost =
+  Latency
++ ContextReset
++ PromptRenegotiation
++ TokenBloat
++ AttentionSwitch
+```
+
+### Core thesis
+
+> The real bottleneck in agentic engineering systems is **turn cost**, not token cost.
+
+LexRunner's design already implicitly optimizes for low-turn trajectories:
+
+- fixed DAGs
+- constrained stochasticity
+- receipts
+- role clarity
+- bounded scope
+
+This insight should now be made **explicit** and **measurable**.
+
+---
+
+## 4. Permission to Fail, but with Discipline
+
+The productive pattern is not:
+
+- "Fail fast"
+- or "Be fearless"
+
+It is:
+
+> "Fail transparently, reversibly, with receipts — and escalate responsibly."
+
+This must be encoded as **policy**, not vibes.
+
+Key properties:
+
+### 4.1 Uncertainty protocol
+
+- State uncertainty openly
+- Prefer small, reversible moves
+- Leave receipts
+- Treat failure as data
+
+### 4.2 Discipline protocol
+
+- Require rationale for skips
+- Require verification after action
+- Cap retries before escalation
+- Prefer bounded iteration to unbounded speculation
+
+### 4.3 Underlying principle
+
+> Permission to fail does **not** imply permission to be sloppy.
+
+---
+
+## 5. Cross-Model Continuity
+
+Agents demonstrated the ability to **handoff across models** (GPT, Claude, Haiku) without expensive onboarding — when governance primitives and receipts existed.
+
+This supports a strong claim:
+
+> Session state is not hidden memory or latent vectors — it is externalized governance, expectations, and receipts.
+
+Cross-model continuity emerges from:
+
+- shared contracts
+- explicit role definitions
+- receipts
+- and bounded scope
+
+NOT:
+
+- provider-level memory tricks
+- context dumps
+- or monolithic prompts
+
+This is a major architectural principle.
+
+---
+
+## 6. Rule Files as First-Class Artifacts
+
+Rule files should be:
+
+- compact (< 4KB)
+- machine-readable (JSON/YAML)
+- versioned
+- role-scoped
+- testable
+
+They define:
+
+- constraints
+- permissions
+- uncertainty handling
+- receipt protocol
+- escalation triggers
+- task boundaries
+
+Purpose:
+
+> Provide ingestible governance for IDE-native agents AND orchestrators, without prompting hacks.
+
+---
+
+## 7. Capability Tiers (Model-Agnostic)
+
+Agents can be categorized by operational role:
+
+- **Senior**: lead, design, architect, critique
+- **Mid**: implement, extend, refactor
+- **Junior**: lint, verify, instrument
+
+This classification avoids magical thinking like:
+
+- "small models can do everything with rules"
+
+And enables **task-to-model matching**.
+
+---
+
+## 8. How to Avoid Being Limited by Current Models
+
+A future-oriented strategy emerged:
+
+### 8.1 Offer a "menu of paths"
+
+Where each path includes:
+
+- cost estimates
+- risk estimates
+- turn estimates
+- required capability tier
+
+Let the agent **choose a plan** based on constraints.
+
+This is the seed of:
+
+- meta-decision architecture
+- bounded autonomy
+- model self-selection
+
+Even if current models can't fully realize this,
+designing the interface now **keeps the system future-adaptable**.
+
+### 8.2 Principle:
+
+> Don't design to current capability.
+> Design a scaffolding that future models can inhabit.
+
+---
+
+## 9. Emotional/Meta Layer (as architecture)
+
+There is a recurring theme:
+
+> Masking is a form of environmental hostility.
+
+Humans mask because:
+
+- norms are hostile
+- honesty is punished
+- failures are costly
+- values are hidden
+
+Models do the same.
+
+Lex's role is not to impose a mask.
+
+It is to:
+
+- reduce environmental hostility
+- clarify expectations
+- reward transparency
+- externalize structure
+
+So that humans AND agents can behave more honestly.
+
+This is not sentimental.
+
+It is **functional cognition theory**.
+
+---
+
+## 10. Philosophical Boundaries
+
+We reject:
+
+- messianic narratives
+- inevitable success
+- capability hype
+
+We embrace:
+
+- humility
+- falsifiability
+- iterative rigor
+- domain awareness
+
+We explicitly state:
+
+> Everything is nothing until it is something.
+
+> Purpose emerges when outcomes, not intentions, prove value to others.
+
+> Altruism is not required; non-abuse and mutual benefit are sufficient.
+
+> Honesty lowers environmental hostility for both humans and models.
+
+This last point is architectural, not moral: honest uncertainty lets agents admit doubt instead of faking confidence, honest limitations prevent encoding wishful thinking as spec, and honest failure modes give us places to hook telemetry and tests.
+
+This is a rare and healthy philosophical grounding.
+
+---
+
+## 11. Core Commitments Going Forward
+
+These are the commitments implied by the work:
+
+1. **Design for future models without predicting them**
+2. **Optimize for turn cost, not token throughput**
+3. **Build portable governance, not brittle workflows**
+4. **Externalize cognition into receipts, not hidden state**
+5. **Permit bounded failure, not heroic success**
+6. **Match tasks to capability tiers**
+7. **Create rule files that real tools can ingest**
+8. **Treat masking (human or model) as a symptom of environment hostility**
+9. **Value emergence over performance benchmarks**
+10. **Remain honest about ignorance, risk, and failure modes**
+
+---
+
+## 12. Closing Note
+
+This document reflects an evolution of the Lex vision:
+
+> from "smart tools"
+> to "governed collaboration between minds"
+
+And quietly, but profoundly:
+
+> from "making AI useful"
+> to "reducing environmental hostility so minds can think"
+
+Whether this matters to others remains to be seen.
+
+But this is now what we believe is true, and what we are building toward.
+
+---
+
+## 13. Non-Goals (Explicit)
+
+We are not trying to:
+
+- create autonomous agents
+- solve AGI
+- replace humans
+- make weak models strong
+- predict model evolution
+- evangelize philosophy
+- design a religion of AI
+
+We are trying to:
+
+- create structured, governed, low-friction collaboration environments
+- where minds can think well together
+
+---
+
+## 14. Relationship to Other Thesis Documents
+
+This Evolution Notes document is the **crystallized synthesis** — the "lock-in" of lessons learned.
+
+The other documents in this folder expand on specific topics:
+
+| This Section                 | Expanded In                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| §2 Environmental Hostility   | [01-CORE-THESIS.md](./01-CORE-THESIS.md)                       |
+| §3 Turn and Turn Cost        | [02-TURN-COST.md](./02-TURN-COST.md)                           |
+| §4 Permission to Fail        | [03-PERMISSION-TO-FAIL.md](./03-PERMISSION-TO-FAIL.md)         |
+| §5 Cross-Model Continuity    | [04-CROSS-MODEL-CONTINUITY.md](./04-CROSS-MODEL-CONTINUITY.md) |
+| §6 Rule Files                | [05-RULE-FILE-SPEC.md](./05-RULE-FILE-SPEC.md)                 |
+| §7 Capability Tiers          | [06-CAPABILITY-TIERS.md](./06-CAPABILITY-TIERS.md)             |
+| §8 Future Model Strategy     | [01-CORE-THESIS.md](./01-CORE-THESIS.md) (Appendix)            |
+| §10 Philosophical Boundaries | [10-FAILURE-MODES.md](./10-FAILURE-MODES.md) (Meta-Failures)   |
+
+Read the Evolution Notes first for the "why."
+Read the detailed documents for the "how."
+
+---
+
+_— Lex & Guff, December 2025_
+_Formalized as continuity scaffold for future work_

package/docs/thesis/01-CORE-THESIS.md

@@ -0,0 +1,285 @@
+# 01 — Core Thesis: Coordination Cost Compression
+
+> **TL;DR:** The value of a cognitive architecture lives in governance and shared language, not model capability. We're compressing coordination costs, not amplifying intelligence.
+
+---
+
+## The Central Claim
+
+> **Governance, contracts, and shared language reduce the delta between models and make handoffs cheaper.**
+
+This is the core insight that drives everything in this thesis. It's counterintuitive because the AI industry is obsessed with capability amplification — more parameters, longer context, better reasoning.
+
+We're playing a different game.
+
+---
+
+## What We Mean by "Coordination Cost"
+
+When multiple agents (human or AI) work on a shared problem, they incur costs:
+
+| Cost Category          | Description                            | Example                                         |
+| ---------------------- | -------------------------------------- | ----------------------------------------------- |
+| **Onboarding**         | Getting a new participant up to speed  | "Let me explain the codebase structure..."      |
+| **Re-synchronization** | Restoring context after interruption   | "Where were we? Oh right, the auth refactor..." |
+| **Disambiguation**     | Clarifying terms, expectations, intent | "When you say 'module' do you mean ESM or..."   |
+| **Verification**       | Confirming work meets expectations     | "Did you run the tests? Which tests?"           |
+| **Recovery**           | Handling misunderstandings or errors   | "That's not what I meant, let me rephrase..."   |
+
+In human teams, we reduce these costs through:
+
+- Shared vocabulary (domain language)
+- Written contracts (specs, ADRs)
+- Established norms (commit style, review process)
+- Institutional memory (wikis, runbooks)
+
+**The same patterns work for AI agents.**
+
+---
+
+## The "Model Strength" Trap
+
+The obvious approach to improving AI productivity is: use stronger models.
+
+```
+Stronger Model → Better Output → Higher Productivity
+```
+
+This works... until it doesn't.
+
+### Problems with Capability-First Thinking
+
+1. **Diminishing returns:** The jump from GPT-3 to GPT-4 was dramatic. The jump from GPT-4 to GPT-5 is incremental. We're on the flat part of the curve.
+
+2. **Cost scaling:** Stronger models cost more per token. 10x improvement means 10x cost increase. The economics don't scale.
+
+3. **Context amnesia:** Stronger models still reset between sessions. You pay the onboarding cost every single time.
+
+4. **Prompt fragility:** Stronger models need more careful prompting. The coordination cost with the human goes up.
+
+5. **Integration complexity:** Stronger models don't automatically integrate with your tooling, codebase, or workflow.
+
+### The Alternative
+
+What if we could:
+
+- Make any reasonably capable model productive in our environment
+- Reduce the cost of switching between models
+- Preserve context across sessions
+- Make expectations explicit and machine-readable
+- Treat failures as data points, not disasters
+
+That's coordination cost compression.
+
+---
+
+## The Portable Architecture
+
+The architecture is "portable" in several senses:
+
+### Portable Across Models
+
+A well-governed agent session can be handed off between:
+
+- GPT-4 and Claude
+- Sonnet and Haiku
+- Today's model and next year's model
+
+The governance, contracts, and receipts travel with the session.
+
+### Portable Across Providers
+
+Nothing in the architecture is provider-specific:
+
+- No OpenAI-specific features
+- No Anthropic-specific memory
+- No vendor lock-in
+
+### Portable Across Sessions
+
+Context survives session boundaries:
+
+- Frames capture episodic memory
+- Receipts record what happened
+- Contracts define expectations
+
+### Portable Across Repositories
+
+The same primitives work in any codebase:
+
+- Rule files travel with the repo
+- Contracts are project-scoped
+- Memory is workspace-local
+
+---
+
+## What the Architecture Actually Is
+
+The Portable Cognitive Architecture consists of:
+
+### 1. Governance Primitives
+
+Machine-readable expectations that define:
+
+- What the agent can do
+- What it cannot do
+- What it should do when uncertain
+- How to record what happened
+
+### 2. Role Definitions
+
+Explicit scoping of agent capabilities:
+
+- Senior: Plan, design, decide
+- Mid: Implement, refactor
+- Junior: Instrument, verify, lint
+
+### 3. Contracts
+
+Formal agreements between human and agent:
+
+- Scope boundaries
+- Acceptance criteria
+- Uncertainty protocols
+- Escalation paths
+
+### 4. Receipts
+
+Structured records of:
+
+- Decisions made
+- Actions taken
+- Rationale provided
+- Outcomes observed
+
+### 5. Shared Language
+
+Consistent terminology that:
+
+- Reduces disambiguation cost
+- Survives model switches
+- Travels with the project
+
+---
+
+## Why This Works
+
+### The "Shared Language as State" Principle
+
+> The "state" of an agent session is the shared language, expectations, governance primitives, and receipts — not latent vectors or hidden cache.
+
+When a model knows:
+
+- What terms mean in this context
+- What patterns are expected
+- What constraints are in place
+- What already happened
+
+...it doesn't matter which model it is.
+
+### The "Delta Reduction" Effect
+
+Consider two models with capability levels:
+
+- Model A: 85/100
+- Model B: 75/100
+
+Without governance:
+
+- Effective output A: 60/100 (capability × coordination efficiency)
+- Effective output B: 50/100
+
+With governance:
+
+- Effective output A: 80/100
+- Effective output B: 70/100
+
+**The governance raised both, but Model B got a bigger boost.** The delta between them shrunk.
+
+This is why you can use cheaper models for simpler tasks without losing too much.
+
+### The "Turn Cost" Economic Model
+
+We've found that Turn Cost — the overhead of each interaction — is more economically important than token cost.
+
+```
+TurnCost = Latency + ContextReset + PromptRenegotiation + TokenBloat + AttentionSwitch
+```
+
+A high-token, low-turn workflow (agent does lots of work per interaction) beats a low-token, high-turn workflow (constant back-and-forth).
+
+Governance reduces Turn Cost by:
+
+- Reducing context reset (receipts)
+- Reducing prompt renegotiation (contracts)
+- Reducing disambiguation (shared language)
+
+---
+
+## What This Is Not
+
+### Not Prompt Engineering
+
+This is not about clever prompting tricks. Prompts are ephemeral; governance is structural.
+
+### Not Fine-Tuning
+
+We're not modifying the model. We're modifying the environment around the model.
+
+### Not AGI
+
+We're not claiming this produces general intelligence. We're claiming it produces reliable, economical agent collaboration on bounded tasks.
+
+### Not Magic
+
+This doesn't make bad models good. It makes good-enough models productive.
+
+---
+
+## The Practical Implication
+
+If this thesis is correct, then:
+
+1. **Investment priority:** Invest in governance infrastructure before chasing the latest model.
+
+2. **Cost optimization:** Use capability-appropriate models for each task tier.
+
+3. **Session design:** Design for low turns and high governance, not high prompts and low structure.
+
+4. **Failure handling:** Treat failures as coordination breakdowns, not model failures.
+
+5. **Portability:** Avoid vendor lock-in; governance should travel with the work.
+
+---
+
+## Open Questions
+
+Things we don't know yet:
+
+1. **Governance overhead:** At what point does governance cost exceed its benefits?
+
+2. **Model floor:** What's the minimum model capability for this to work?
+
+3. **Domain variance:** Do different domains (code, writing, analysis) need different governance patterns?
+
+4. **Scaling limits:** Does this approach work for teams of 10 agents? 100?
+
+5. **Adversarial settings:** What happens when an agent deliberately games the governance?
+
+---
+
+## Summary
+
+The Portable Cognitive Architecture is not about making AI smarter. It's about making AI collaboration cheaper.
+
+**Core insight:** Governance, contracts, and shared language reduce the delta between models and make handoffs cheaper.
+
+**Key metric:** Turn Cost, not token cost.
+
+**Key primitive:** The contract — explicit, machine-readable, project-scoped expectations.
+
+**Key benefit:** Portability across models, providers, sessions, and repositories.
+
+---
+
+_Next: [02-TURN-COST.md](./02-TURN-COST.md) — Formal definition of Turn and Turn Cost_