@smartergpt/lexrunner 1.0.0 → 1.2.1

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

@@ -1,383 +0,0 @@
-# 📘 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

@@ -1,285 +0,0 @@
-# 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_