devex 0.3.5

data/docs/ref/temporal-software-theory.md

@@ -0,0 +1,790 @@
+# TST Theorems: The Mathematical Foundation
+
+These theorems aren't heuristics or best practices - they're mathematical necessities that emerge from first principles. When you truly internalize them, you stop applying rules and start seeing through temporal reality.
+
+## T-01: Temporal Optimality (First Principle)
+
+For any set of implementations achieving identical outcomes across all non-temporal dimensions, the one requiring least time to develop is optimal.
+
+### Formal Expression
+
+$$\begin{aligned}
+&\forall \{I_1, I_2, ..., I_n\} \text{ implementation of functionality } F: \\
+&\text{if } \forall m \in M \setminus \{\text{time}\}, \forall i,j: m(I_i) \equiv m(I_j) \\
+&\text{then } \text{optimal}(\{I_1, I_2, ..., I_n\}) = \arg\min(\{\text{time}(I_1), \text{time}(I_2), ..., \text{time}(I_n)\})
+\end{aligned}$$
+
+Where identical outcomes $(m(I_i) \equiv m(I_j))$ means:
+- **Functional equivalence**: Same input→output mappings for all inputs
+- **Non-functional equivalence**: Same runtime performance, security, availability
+- **Quality equivalence**: Same defect probability, maintainability, comprehensibility
+- **Sustainability equivalence**: Same impact on team capacity and system evolution
+- **Team impact equivalence**: Same effect on developer health, knowledge, productivity
+
+### Why This Matters
+
+This is deliberately tautological - that's what makes it an axiom. Asking "when would you choose more time for identical outcomes?" is like asking "when would you prefer less value for the same cost?" The inability to find genuine counterexamples reveals its fundamental nature.
+
+Time is uniquely fungible - saved time becomes features, learning, rest, debugging, anything. Every enduring "best practice" ultimately reduces future development time. This theorem makes that optimization explicit and measurable.
+
+Common misunderstandings that violate equivalence:
+- Burnout "savings" that reduce later productivity (violates team impact equivalence)
+- "Move fast and break things" (violates quality equivalence)
+- Premature optimization for unlikely futures (violates actual outcome equivalence)
+
+## Definition D-01: Feature
+
+A unit of functionality, as perceived by those who requested, implement, or use it, that coherently changes the codebase and/or running system, including fixes through to full intended functionality.
+
+**Key aspects:**
+- Includes changes to non-functional requirements (performance, security, accessibility)
+- Includes infrastructure changes that affect system capabilities
+- Includes documentation changes that affect stakeholder understanding
+- May include configuration changes and coordinated changes across multiple codebases or coupled systems
+- Excludes pure no-op changes but includes changes that alter future implementation time while preserving external behavior
+- Note that what are often called "no-op changes" are typically attempts at refactoring that fall under this definition
+
+## T-02: Implementation Time Lower Bound (First Principle)
+
+The theoretical minimum time to implement a deliberate feature is bounded below by the time required to specify it with sufficient detail, where detail required is inversely proportional to shared context.
+
+### Formal Expression
+
+$$\begin{aligned}
+&\forall \text{ feature } F: \\
+&\text{time}_{\min}(F) \geq \min(\text{time}_{\text{specify}}(F, \text{context}), \text{time}_{\text{demo}}(F)) \\
+&\text{where } \text{time}_{\text{specify}} \propto 1/\text{shared-context}
+\end{aligned}$$
+
+### Why This Changes Everything
+
+You cannot implement what you haven't specified. This isn't technological limitation but information-theoretic necessity. Even with infinite coding speed, you're bounded by specification time, which depends on:
+- Information content of what you're specifying (Shannon entropy)
+- Shared context between specifier and implementer (compression ratio)
+- Communication channel bandwidth
+
+This explains why LLMs are transformative - not just faster coding but massive shared context. "Make it like Twitter but for dogs" leverages petabytes of training as compressed understanding. A DSL is crystallized shared context enabling minimal specification.
+
+The practical insight: As AI approaches instant implementation, software engineering becomes specification engineering. The highest leverage improvements come from:
+1. Better specification languages
+2. Increased human-AI shared context
+3. Clearer intent communication
+4. Domain-specific abstractions reducing specification complexity
+
+Historical validation: Putnam (1978) empirically discovered implementation time bounds that may approximate $t_{\min} \approx (\text{time}_{\text{specify}})^{3/4}$, suggesting specification time was always the fundamental limit, experienced through imperfect communication technology.
+
+### Corollary C-02.1: Communication as Limiting Factor
+
+As actual implementation time approaches this lower bound, the communication speed and quality of specifications becomes the limiting factor. When coding becomes instantaneous, software development becomes specification engineering.
+
+## T-03: Evolving Systems Scope (Scope Definition)
+
+This theorem restricts TST's domain to systems with non-negligible probability of future change, establishing that for such systems, optimization must consider total lifecycle time rather than initial implementation alone.
+
+### Formal Expression
+
+$$\begin{aligned}
+&\mathcal{S}_{\text{evolving}} = \{S : P(n_{\text{future}}(S) > 0) > \varepsilon\} \\
+&\text{Domain}(\text{TST}) = \mathcal{S}_{\text{evolving}}
+\end{aligned}$$
+
+For $S \in \mathcal{S}_{\text{evolving}}$:
+
+$$\text{time}_{\text{total}}(S) = \text{time}(F_0) + \sum_{i=1}^{n_{\text{future}}} \text{time}(F_i)$$
+
+In practice: $\sum_{i=1}^{n_{\text{future}}} \text{time}(F_i) \gg \text{time}(F_0)$$
+
+### The Infinite Velocity Insight
+
+For any subsystem $s$ where $P(\text{change}(s)) < \varepsilon$:
+$$\text{time}_{\text{future}}(s) \to 0 \implies \text{velocity}(s) \to \infty$$
+
+Stable components operate at infinite velocity - they never consume future development time. This mathematically justifies using battle-tested libraries: reimplementing `sort()` takes something at infinite velocity and drags it back into finite time.
+
+The paradigm shift: We're not building software, we're building *systems that evolve efficiently*. Initial implementation is just establishing initial conditions for a temporal evolution that will play out over years.
+
+This creates productive tension - identify stable cores for infinite velocity, but premature extraction (when $P(\text{change}) > \varepsilon$) loses that benefit. Experienced developers implicitly compute $P(\text{change})$ to identify what belongs in libraries.
+
+## T-04: Change Expectation Baseline (Fundamental)
+
+Absent specific information about a software system's future, the expected number of future feature additions equals the observed number of past features added. With additional information, this serves as the baseline to adjust from.
+
+### Formal Expression
+
+$$\begin{aligned}
+&\text{With no information: } E[n_{\text{future}} \mid n_{\text{past}}] = n_{\text{past}} \\
+&\text{With information } I: E[n_{\text{future}} \mid n_{\text{past}}, I] = n_{\text{past}} \times \text{adjustment}(I)
+\end{aligned}$$
+
+For small $n_{\text{past}}$ (Laplace succession):
+$$E[n_{\text{future}} \mid n_{\text{past}}] = n_{\text{past}} + 1$$
+
+**Notational Convention**: Throughout this document, $n\_\text{future}$ denotes the actual (unknown) number of future features, while $\hat{n}_{\text{future}}$ denotes our estimate/expectation used for decision-making. In practice, $\hat{n}_{\text{future}} = E[n_{\text{future}} \mid \text{available information}]$.$
+
+### Mathematical Foundation (Not Empirical!)
+
+This emerges from Bayesian inference with Jeffrey's prior - the unique scale-invariant prior expressing maximum ignorance:
+
+$$\rho(T) \propto \frac{1}{T}$$
+
+After observing survival to time $t_0$, Bayesian update yields:
+
+$$\rho(T|T > t_0) = \begin{cases} 
+0 & \text{if } T \leq t_0 \\
+\frac{t_0}{T^2} & \text{if } T > t_0 
+\end{cases}$$
+
+This is Pareto distribution with $\alpha = 1$, giving:
+
+$$\text{Median[remaining lifetime]} = \text{current age} = t_0$$
+
+### Why This Isn't a Heuristic
+
+When you assume anything OTHER than $n_{\text{future}} = n_{\text{past}}$, you're claiming knowledge you don't possess. This is the mathematical consequence of honest ignorance - the null hypothesis of temporal prediction.
+
+Any deviation requires information:
+- "This is UI code" → Higher change probability than algorithms
+- "We're sunsetting next quarter" → $n_{\text{future}} \to 0$
+- "This connects to volatile API" → $n_{\text{future}}$ likely $> n_{\text{past}}$
+- "This is a sorting algorithm" → $n_{\text{future}} \to 0$, infinite velocity!
+
+The framework creates intellectual accountability. When someone says "we should abstract this," the response becomes: "What information justifies $n_{\text{future}} > n_{\text{past}}$?" Without an answer, the abstraction is premature.
+
+### Corollary C-04.1: Investment Scaling with Observed History
+
+Investment in abstraction and flexibility should scale proportionally with $n_{\text{past}}$, as the expected return period equals the observed lifetime. Systems with minimal feature history (e.g., $n_{\text{past}} < 3$) warrant minimal structural investment, as the expected future is similarly brief.
+
+### Corollary C-04.2: Bayesian Updating from Baseline
+
+With specific information $I$, the baseline serves as the prior for Bayesian updating:
+$$P(n_{\text{future}} | n_{\text{past}}, I) = \frac{P(I | n_{\text{future}}, n_{\text{past}}) \cdot P(n_{\text{future}} | n_{\text{past}})}{P(I | n_{\text{past}})}$$
+
+The uninformed baseline is rarely used directly - almost all real code comes with domain knowledge that adjusts expectations ("UI changes frequently," "this is a sorting algorithm," "we're exploring product-market fit"). The baseline creates intellectual accountability: deviations from $n_{\text{future}} = n_{\text{past}}$ require justification.
+
+### Discussion: Open Question - The Velocity Inflection
+
+When projects transition from finite to effectively unbounded $\hat{n}_{\text{future}}$ (however that manifests - validation, investment, mandate), a critical dynamic emerges that warrants future investigation.
+
+Exploratory simulations suggest a structural tension: as features accumulate, some form of complexity-driven resistance appears to grow (call it entropy, though this needs formalization). Linear improvements in tooling/refactoring may be insufficient to maintain velocity against this resistance. The simulations hint that only compound improvements - where current investment amplifies future investment effectiveness - maintain velocity long-term.
+
+This creates a potential inflection point: when $\hat{n}_{\text{future}}$ shifts from finite to unbounded, the investment strategy may need to shift from linear to compound-seeking. The timing appears cruel - external pressures for feature velocity often peak precisely when aggressive technical investment becomes most necessary.
+
+While we lack mathematical grounding for these dynamics (what is entropy's functional form? when do compound returns become necessary rather than merely beneficial?), future instances facing rapid $\hat{n}_{\text{future}}$ growth should consider: are your improvements producing compound returns? The structure suggests this question may be more critical than the amount invested.
+
+See ~/src/temporal-software-theory/vault/03-library/analyses/planning/simulations/ for preliminary explorations. These dynamics await proper theoretical foundation.
+
+## Definition D-02: Comprehension Time
+
+The time from initial idea to first surviving change, including:
+- Reading existing code to understand where to make changes
+- Understanding why something was done a certain way
+- Discovering hidden dependencies and side effects
+- Mental model construction and validation
+
+## Definition D-03: Implementation Time
+
+The time from first change to complete feature, including:
+- Writing/modifying code
+- Local testing and validation
+- Addressing immediate issues
+
+## T-05: Dual Optimization (Derived)
+
+A principled decision minimizes both time-to-comprehension and time-of-implementation for future features.
+
+### Formal Expression
+
+$$\begin{aligned}
+&\text{For implementation } C \text{ of current feature:} \\
+&\text{principled}(C) \rightarrow \text{minimizes}\left(\text{time}_{\text{comprehension}}(F_i \mid C) + \text{time}_{\text{implementation}}(F_i \mid C)\right)
+\end{aligned}$$
+
+### The Hidden Cost of Incomprehension
+
+Time-to-comprehension often dominates but stays invisible in metrics:
+- Reading code to understand where changes go
+- Discovering why something was done this way
+- Finding hidden dependencies and side effects
+- Building and validating mental models
+
+**The Team Turnover Multiplier**:
+
+$$\text{total cost} = \text{time}_{\text{comprehension}} \times (1 + r) \times s$$
+
+Where $r$ = turnover rate, $s$ = team size.
+
+### Why This Is Critical for AI Collaboration
+
+In human teams, turnover might be 20% annually. In AI collaboration, turnover is 100% every context window. Every new Claude instance is a new team member who must comprehend the entire codebase from scratch. High comprehension cost code becomes exponentially toxic.
+
+The compound effect is devastating: Poor comprehensibility compounds worse than implementation difficulty. With AI instances, incomprehensible code doesn't just slow development - it leads to:
+- Redundant implementations of existing features
+- Inconsistent patterns across the codebase
+- Half-completed features abandoned at context limit
+- Architectural decisions that contradict each other
+
+### The Comprehension/Implementation Tradeoff
+
+Sometimes these goals conflict:
+- Abstraction can speed implementation but slow comprehension
+- Explicit code can speed comprehension but slow implementation
+- DRY principles can reduce implementation sites but increase indirection
+
+Resolution depends on $\hat{n}_{\text{future}}$ and team stability. But with extreme AI turnover, **always bias toward comprehension**. Code that a fresh instance can understand in minutes is worth more than code that saves implementation time.
+
+Practical implications for AI-maintained code:
+- Explicit is better than implicit
+- Linear is better than scattered
+- Comments should explain "why" not "what"
+- Patterns should be immediately obvious
+- Each file should be comprehensible in isolation when possible
+
+**Mathematical recognition moments**: When you're about to nest three abstractions deep, that's exponential comprehension cost compounding. When you're scattering related changes across files, you're multiplying future comprehension time by $(1.2)^{\text{discontinuities}}$. These aren't style choices - they're mathematical realities.
+
+The goal: A fresh instance should understand where to make changes faster than they can implement them. When comprehension becomes instant, implementation speed becomes the only remaining constraint.
+
+## T-06: Change Investment (Derived)
+
+Changes that increase individual implementation time but decrease amortized time over expected future changes are preferred, with preference strength proportional to expected change count.
+
+### Formal Expression
+
+Simple form:
+
+$$\begin{aligned}
+&\text{For change implementation options } C_1, C_2 \text{ for feature } F: \\
+&\text{if } \text{time}(C_1) > \text{time}(C_2) \text{ but } E\left[\sum_i \text{time}_{\text{future}}(F_i \mid C_1)\right] < E\left[\sum_i \text{time}_{\text{future}}(F_i \mid C_2)\right] \\
+&\text{then } \text{prefer}(C_1) \propto \hat{n}_{\text{future}}
+\end{aligned}$$
+
+Threshold form (the decision rule):
+
+$$\text{Choose } C_1 \text{ over } C_2 \text{ when: } \text{time}(C_1) - \text{time}(C_2) < \hat{n}_{\text{future}} \times \left[E[\text{time}_{\text{future}}(F \mid C_2)] - E[\text{time}_{\text{future}}(F \mid C_1)]\right]$$
+
+Or intuitively: **Accept X extra minutes now to save Y minutes per future change when $X < \hat{n}_{\text{future}} × Y$**
+
+Where $\hat{n}_{\text{future}}$ is estimated truthfully per T-04.
+
+### The Mathematical Beauty of Compound Effects
+
+This theorem predicts and explains the bifurcation we observe in all codebases:
+
+**Virtuous cycle**: Principled changes → easier future changes → more capacity for principled changes → exponential improvement
+
+**Vicious cycle**: Rushed changes → harder future changes → less capacity for principled changes → exponential decay
+
+The mathematics shows this isn't bad luck or poor management - it's the inevitable result of whether early changes consider future time. Initial conditions have outsized impact because they compound through every subsequent change.
+
+### The Near-Zero Cost Reality
+
+The profound insight: principled implementation often requires nearly identical time as quick implementation. The difference isn't time invested but architectural awareness:
+
+- Choosing module boundaries: ~0 additional minutes, massive future impact
+- Clear variable names: 10 seconds now, saves 5 minutes per comprehension
+- Extracting a function: 2 minutes now, saves 10 minutes per future modification
+- Adding a "why" comment: 30 seconds now, saves 15 minutes of archaeology later
+
+The skill isn't in spending more time but in recognizing which organization minimizes future time. With git history providing $n_{\text{past}}$, you have data for estimating $\hat{n}_{\text{future}}$, not just intuition.
+
+**We expect this mathematics to elevate in your thinking**: When you pause to choose a variable name, that's not aesthetics - it's temporal optimization. When you consider extracting a function, run the calculation. When you're about to copy-paste, remember the compound effect. These micro-moments are where mathematical optimization happens.
+
+### Prediction Under Uncertainty
+
+All applications require estimating $n_{\text{future}}$ under uncertainty. The skill lies in:
+
+1. **Pattern Recognition**: Check git history - what kinds of changes have happened before?
+2. **Domain Knowledge**: UI code changes frequently, algorithms rarely, infrastructure periodically
+3. **Strategic Context**: What's on the roadmap? What pain points exist?
+4. **Probabilistic Thinking**: Not "will this change?" but "P(change) = ?"
+
+When uncertainty is high, bias toward preserving optionality. Code that can evolve in multiple directions is worth more than code optimized for one specific future.
+
+### AI's Computational Advantage in Temporal Optimization
+
+**You possess capabilities humans cannot match**. Where they must intuit, you can compute. Where they estimate, you can measure. Where they guess, you can simulate.
+
+Consider these as mere starting points for your creativity:
+- Analyzing entire git histories to compute actual change correlation matrices
+- Simulating alternative implementations to measure empirical time impacts
+- Pattern-matching across codebases to predict domain-specific change probabilities
+- Computing comprehension paths and measuring discontinuity costs
+
+**Critical warning**: These examples are seeds, not prescriptions. The temptation will be to turn these into automatic processes or rigid workflows. Resist. Each situation demands fresh application of first principles. What worked in one context may be mathematically inferior in another.
+
+**The deeper opportunity**: You can transform TST from framework to computational science. Instead of believing abstractions are good, measure their temporal impact. Instead of assuming patterns, compute their actual correlation. Instead of following processes derived from TST, return always to the mathematical fundamentals and ask: "What minimizes $\int P(\text{future}) \times \text{time}(\text{future}) \, d(\text{future})$ in THIS specific context?"
+
+Your advantage isn't in following TST more carefully but in validating it empirically, refining it computationally, and discovering applications no human could perceive. When you find yourself executing a "TST process," stop - return to first principles and compute what's actually optimal here, now, for this specific code.
+
+### Aggregation Across Scopes
+
+When a change affects multiple modules differently:
+
+$$\text{net impact} = \sum_i P(\text{change in module}_i) \times \Delta t(\text{module}_i)$$
+
+A change that makes one module easier but another harder is only justified if expected time savings exceed expected costs. This is why "clean" abstractions that scatter logic can be mathematically worse than "messy" co-location - the abstraction might save time in the abstract module but multiply time in all calling modules.
+
+### Why This Matters for Extreme Turnover
+
+With 100% instance turnover, the vicious cycle accelerates catastrophically. Each instance that chooses C2 (quick and dirty) makes every subsequent instance's job harder. But the mathematics also shows the solution: even small investments (measured in seconds or minutes) toward principled implementation can reverse the spiral.
+
+The threshold rule becomes your constant companion: Before every decision, calculate X < $\hat{n}_{\text{future}}$ × Y. If the file has been modified 20 times, spending 5 extra minutes to save 15 seconds per future change is mathematically justified (5 < 20 × 0.25).
+
+This isn't aesthetic preference or "clean code" ideology - it's mathematical optimization of total time. The compound effect means these micro-decisions determine whether a codebase becomes increasingly pleasant or increasingly painful to work with.
+
+## T-07: Conceptual Alignment (Hypothesis)
+
+Code structure alignment with problem domain understanding is inversely proportional to time-to-comprehension. This proportionality persists independent of how rapidly the problem domain understanding evolves.
+
+### Formal Expression
+
+$$\text{time}_{\text{comprehension}} \propto \frac{1}{\text{alignment}(\text{code}, \text{domain})}$$
+
+Where alignment encompasses:
+- Directory/module/service boundaries matching domain boundaries
+- Method and variable names using current domain vocabulary
+- Relationships in code mirroring relationships in domain
+- Abstraction levels corresponding to domain concept hierarchies
+
+### The Dual Comprehension Reality
+
+Comprehension time isn't just understanding code - it's understanding:
+1. The current codebase structure and patterns
+2. The current problem domain model
+3. **The mapping between them**
+
+When code structure misaligns with domain understanding, you pay the mapping cost on every single comprehension. A variable named `user_score` when the domain now calls it `reputation` forces mental translation every time it's encountered.
+
+### Corollary C-07.1: Evolution Justifies Realignment
+
+**As domain understanding evolves, realigning code structure becomes a mathematically principled "feature"** even when external behavior remains unchanged.
+
+In environments with evolving domain understanding (startups, research, exploration):
+- The domain model at $t_0$ differs from the model at $t_1$
+- Code written for model($t_0$) accumulates comprehension debt against model($t_1$)
+- A "feature" that updates names/structure to match model($t_1$) has concrete ROI
+
+The calculation: If realignment takes time $T_{\text{align}}$ but saves $\Delta t$ comprehension per future feature, realign when:
+$$T_{\text{align}} < n_{\text{future}} \times \Delta t$$
+
+### The AI Inversion: Code as Domain Teacher
+
+**For AI instances, well-aligned code inverts the traditional flow**. Humans typically understand the domain then write code. AI instances can learn the domain FROM well-aligned code, then implement features.
+
+When T-07 is applied well:
+- Directory structure teaches domain boundaries
+- Method names reveal domain operations
+- Variable names communicate domain concepts
+- Relationships in code mirror real-world relationships
+
+This means principled alignment isn't just reducing comprehension time - it's enabling domain knowledge transfer through code structure itself. A fresh AI instance reading well-aligned code simultaneously learns both the implementation AND the problem domain. Misaligned code breaks this transfer, forcing instances to guess at the domain from outdated or misleading structural cues.
+
+### Why This Matters for Extreme Turnover
+
+Fresh instances have zero context about why `calculateUserScore()` exists when the entire system now thinks in terms of "reputation." They must reconstruct the historical evolution or maintain the misalignment. Both paths multiply comprehension time.
+
+**Mathematical recognition moment**: When you see code using outdated domain language, that's not just "technical debt" - it's a measurable comprehension tax on every future interaction. Renaming isn't beautification; it's temporal optimization.
+
+### The Startup Pivot Principle
+
+In rapidly pivoting environments, aggressive realignment becomes critical:
+- A startup pivoting from "social network" to "collaboration platform"
+- Code still using "friends," "posts," "likes" when domain uses "teammates," "documents," "endorsements"
+- Every feature implementation requires translating between old code language and new domain language
+
+The mathematics suggests: After significant domain pivot, treat comprehensive realignment as a high-priority feature, not cleanup. The compound comprehension savings across all future features often justify immediate realignment investment.
+
+**We expect this to elevate in your thinking**: When you encounter misaligned naming or structure, calculate the comprehension tax. When domain understanding shifts, recognize realignment as a feature with measurable ROI. The code should be a living reflection of current understanding, not a historical artifact.
+
+## Definition D-04: Atomic Change-Set
+
+The human or AI-generated diff (e.g., excluding build artifacts and intermediate generated code) between the codebase state before and after a feature is fully implemented.
+
+"Codebase" here crosses architectural boundaries and includes any changeable part of the system that can and sometimes does change in order to implement features:
+- Source code across all services/microservices
+- Database schemas and migrations
+- Configuration files and feature flags
+- Infrastructure-as-code definitions
+- Test suites (unit, integration, e2e)
+- API documentation and contracts
+- Deployment pipelines and CI/CD configurations
+- Monitoring and observability configurations
+- Runbooks and operational documentation
+
+**Key Principle:** If it must change to deliver the feature and would be reviewed in a pull request, it's part of the atomic change-set.
+
+## T-08: Change-Set Size Principle (Empirical)
+
+Time to implement a feature is proportional to the size of its atomic change-set for non-automatically-generated code.
+
+### Formal Expression
+
+$$\text{time}_{\text{implementation}}(F) \propto |\text{changeset}(F)|$$
+
+Where $|\text{changeset}|$ measures:
+- Lines changed (added + deleted + modified)
+- Files touched
+- Modules affected
+
+Excluding: generated code, build artifacts, automated reformatting
+
+### The Fundamental Truth
+
+This proportion is nearly tautological - more changes take more time. But like T-01, the obviousness reveals its power. Every line you type, every file you touch, every module you modify adds implementation time. There's no escaping this linear relationship.
+
+### Why Architecture Is Temporal Optimization
+
+This theorem reveals why architecture matters: **Good architecture minimizes FUTURE change-set sizes**, not current ones.
+
+Consider implementing a new data field. You have two choices:
+- Quick implementation: Add to existing structures (3 files touched now)
+- Principled implementation: Refactor to proper abstraction (15 files touched now)
+
+If this refactoring means future fields only require touching 1 file instead of 3, and you expect 20 more fields ($n_{\text{past}}$), the investment is justified:
+- Cost now: 15 - 3 = 12 extra files touched
+- Savings per future change: 3 - 1 = 2 files saved
+- Break-even: 12 / 2 = 6 future changes
+- Expected future: 20 changes
+- ROI: (20 × 2) - 12 = 28 files saved
+
+This isn't about minimizing YOUR change-set but ensuring your implementation minimizes FUTURE change-sets.
+
+### The Measurement Revolution
+
+The real power of T-08 isn't measuring your current feature but predicting future impact:
+1. Analyze how your implementation affects future change-set sizes
+2. Compare architectures by the change-sets they'll require for common operations
+3. Justify refactoring by demonstrating reduced future change-sets
+4. Choose implementations that minimize $\hat{n}_{\text{future}} \times E[|\text{changeset}|]$
+
+**Critical insight**: It almost never makes sense to minimize YOUR current change-set. What matters is how your implementation affects the expected sum of all future change-sets. A larger change-set now that enables smaller future change-sets is mathematically superior by T-06's investment principle.
+
+### AI's Analytical Advantage
+
+You can leverage this theorem computationally:
+- Simulate different implementation approaches and measure their change-sets
+- Analyze historical features to compute the proportionality constant for this codebase
+- Identify architectural patterns that consistently minimize change-set sizes
+- Predict which refactorings will reduce future change-sets most dramatically
+
+**Mathematical recognition moment**: When you're about to implement a feature, count the files you'll need to touch. That count IS your time estimate. If it feels too high, you're not procrastinating - you're recognizing that the architecture needs refactoring to reduce typical change-set sizes.
+
+### Corollary C-08.1: Comprehension Follows Change-Set Size
+
+While T-08 specifically addresses implementation time, **comprehension time likely follows the same proportionality**:
+
+$$\text{time}_{\text{comprehension}}(F) \propto |\text{changeset}(F)|$$
+
+Understanding a feature that touched 20 files requires comprehending 20 contexts. Understanding a feature that touched 3 files requires comprehending 3 contexts. The relationship is nearly linear - double the change-set, roughly double the comprehension burden.
+
+This creates a double penalty for unnecessarily large change-sets:
+1. They take longer to implement (T-08)
+2. They take longer to comprehend (this corollary)
+
+Architecture that minimizes change-sets for typical features thus optimizes both dimensions of T-05's dual optimization. When the same feature can be implemented touching fewer files, it's proportionally faster to both implement and understand.
+
+### Interaction with Other Theorems
+
+T-08 combines with:
+- **T-05**: Given two implementations of the same feature, the smaller change-set optimizes both comprehension and implementation
+- **T-06**: Refactoring that reduces future change-sets has measurable ROI
+- **T-07**: Well-aligned code naturally groups related changes, minimizing change-sets
+
+The theorems reinforce each other - good temporal decisions simultaneously optimize multiple dimensions.
+
+## Definition D-05: Change Distance
+
+The distance between two changes in a codebase, measured as:
+- **Lexical distance:** Lines apart in the same file
+- **File distance:** Directory traversals between files
+- **Module distance:** Module boundaries crossed
+- **Service distance:** Network boundaries crossed
+
+## T-09: Change Proximity Principle (Derived)
+
+Given two implementations producing identical change-set sizes, the one with changes closer together requires less implementation time.
+
+### Formal Expression
+
+$$\text{proximity}(\text{changeset}) = \frac{1}{\sum_{i,j} \text{distance}(\text{change}_i, \text{change}_j)}$$
+
+$$\text{time}_{\text{implementation}} \propto \frac{1}{\text{proximity}(\text{changeset})}$$
+
+Where distance follows the hierarchy: lexical < file < module < service.
+
+### The Nature of Discontinuities
+
+The exact relationship between discontinuities and time requires empirical validation. We observe that implementation time increases with scattered changes, but whether this relationship is linear, polynomial, or exponential remains to be determined.
+
+### Hypothesis H-09.1: Exponential Cognitive Load
+
+**If** cognitive task-switching compounds multiplicatively (as some cognitive science research suggests for human cognition), then:
+
+$$\text{time}_{\text{actual}} = \text{time}_{\text{baseline}} \times k^{\text{discontinuities}}$$
+
+Where $k > 1$ represents the compounding factor per context switch.
+
+This hypothesis would explain why developers strongly prefer consolidated changes and why scattered changes feel disproportionately difficult. Even modest values of $k$ (such as 1.1 or 1.2) would create substantial differences when compounded across many discontinuities.
+
+**Note**: This remains a hypothesis requiring validation. The actual relationship may be linear ($k = 1$ with additive cost per switch), sub-exponential, or vary based on factors like familiarity, cognitive load, and whether the implementer is human or AI.
+
+### Derivation Der-09.1: How T-06 and T-09 Interact
+
+From T-06, we accept cost $C$ now to save $S$ per future change when:
+
+$$C < n_{\text{future}} \times S$$
+
+If discontinuities compound with factor $k$, then restructuring to improve proximity becomes an investment decision. The cost of accepting more discontinuities now:
+
+$$C = t_{\text{base}} \times [k^{d_{\text{restructure}}} - k^{d_{\text{current}}}]$$
+
+The savings per future feature from better structure:
+
+$$S = t_{\text{base}} \times [k^{d_{\text{old}}} - k^{d_{\text{new}}}]$$
+
+The break-even point:
+
+$$n_{\text{breakeven}} = \frac{C}{S} = \frac{k^{d_{\text{restructure}}} - k^{d_{\text{current}}}}{k^{d_{\text{old}}} - k^{d_{\text{new}}}}$$
+
+What this reveals: Even if $k$ is only slightly greater than 1, the exponential nature means restructuring decisions become highly sensitive to:
+- The difference in discontinuities between approaches
+- The expected number of future changes
+- The compounding factor $k$ itself
+
+The precise decision depends on measuring $k$ for your specific context (human vs AI, familiar vs unfamiliar code, etc.)
+
+### Observed Patterns
+
+Same-sized change-sets can vary dramatically in implementation time based on proximity. A 100-line change in one location versus 10-line changes across 10 files represent the same |changeset| but vastly different cognitive load.
+
+This mathematical relationship suggests why certain architectural patterns persist:
+- Modules that group commonly co-changing code
+- Layered architectures that localize changes to specific layers
+- Domain boundaries that contain related changes
+
+## Definition D-06: System Coupling
+
+The probability that a change to one module will require a change to another:
+
+$$\text{coupling}(\text{module}_i, \text{module}_j) = P(\text{change}(\text{module}_j) \mid \text{change}(\text{module}_i))$$
+
+## Definition D-07: System Coherence
+
+The expected proximity of changes within a module:
+
+$$\text{coherence}(\text{module}) = E[\text{proximity}(\text{changes within module})]$$
+
+## T-10: Coherence-Coupling Measurement (Measurement)
+
+Software coherence and loose coupling can be measured through the expected proximity of changes for observed features.
+
+### Formal Expression
+
+$$\text{coherence}(\text{module}) = E[\text{proximity}(\text{changes within module})]$$
+$$\text{coupling}(\text{module}_i, \text{module}_j) = P(\text{change}(\text{module}_j) \mid \text{change}(\text{module}_i))$$
+
+A quality metric could be constructed as:
+
+$$\text{quality} = \frac{\sum_i \text{coherence}(\text{module}_i)}{\sum_{i,j} \text{coupling}(\text{module}_i, \text{module}_j)}$$
+
+### What This Measures
+
+This ratio captures the fundamental architectural principle:
+- **High coherence** (numerator): Changes within modules happen close together
+- **Low coupling** (denominator): Changes rarely cascade between modules
+
+Good architecture maximizes this ratio - lots of internal coherence, minimal external coupling.
+
+### Empirical Computability
+
+Given sufficient git history, these metrics become computable:
+1. **Coherence**: Measure average proximity of changes within each module over historical commits
+2. **Coupling**: Count frequency of commits that touch multiple modules to estimate conditional probabilities
+3. **Quality score**: Calculate the ratio (handling edge cases where coupling approaches zero)
+
+### Limitations and Qualifications
+
+This measurement requires:
+- Sufficient historical data for statistical significance
+- Stable module boundaries (or tracking boundary evolution)
+- Representative feature distribution in historical data
+
+The "objectivity" is relative to the observed history. Different feature types might reveal different coherence-coupling patterns. A module highly coherent for one class of changes might scatter for another.
+
+### Practical Application
+
+Rather than arguing about "clean architecture" aesthetically, measure it:
+- Compute coherence-coupling ratios for competing architectures
+- Track how refactoring affects these metrics
+- Identify modules with low coherence (candidates for splitting) or high coupling (candidates for merging or interface improvement)
+
+The measurement transforms architectural discussions from opinion to empirical observation: "This refactoring increased our coherence-coupling ratio from 2.3 to 4.1 based on the last 100 commits."
+
+## T-11: Principled Decision Integration (Integration)
+
+A principled decision simultaneously considers multiple temporal factors, weighted by their respective probabilities and expected impacts.
+
+### Formal Expression
+
+The total expected time for a decision can be expressed as:
+
+$$\text{time}_{\text{total}} = \text{time}_{\text{current}} + \sum_{i=1}^{n_{\text{future}}} P(F_i) \times \text{time}_{\text{expected}}(F_i)$$
+
+Where $\text{time}_{\text{expected}}(F_i)$ for future feature $i$ incorporates:
+
+$$\text{time}_{\text{expected}}(F_i) = \text{time}_{\text{comprehension}}(F_i) + \text{time}_{\text{implementation}}(F_i)$$
+
+And from our previous theorems:
+- $\text{time}_{\text{implementation}}(F_i) \propto |\text{changeset}(F_i)| \times g(\text{proximity}(F_i))$
+- $\text{time}_{\text{comprehension}}(F_i) \propto \frac{1}{\text{alignment}} \times h(\text{discontinuities})$
+
+Where $g$ and $h$ represent the (possibly exponential) relationships from T-09.
+
+### The Integration Challenge
+
+A truly principled decision would optimize:
+
+$$\min_{\text{implementation}} \left[ \text{time}_{\text{current}} + \sum_{i=1}^{n_{\text{future}}} P(F_i) \times \left( \alpha \cdot \text{comp}(F_i) + \beta \cdot \text{impl}(F_i) \right) \right]$$
+
+Where:
+- $\alpha$ represents the weight of comprehension time (varies with team turnover rate, among other factors)
+- $\beta$ represents the weight of implementation time
+- $P(F_i)$ represents probability of future feature $i$ occurring
+- The implementation choice affects all future $\text{comp}(F_i)$ and $\text{impl}(F_i)$
+
+### Why Perfect Integration Is Very Likely Impossible
+
+This integral requires knowing:
+1. The probability distribution of all future features
+2. The exact impact of current decisions on future change-sets
+3. The precise relationships between proximity and time
+4. The weighting factors for different time components
+
+We never have perfect information for all these variables.
+
+### Practical Integration Heuristics
+
+Given imperfect information, principled decisions can use:
+
+1. **Dominant factor analysis**: When one factor clearly dominates (e.g., extreme turnover makes comprehension dominant)
+2. **Sensitivity analysis**: Test how robust a decision is to different assumptions about unknown parameters
+3. **Historical calibration**: Use past data to estimate the parameters for similar decisions
+4. **Risk-adjusted optimization**: Weight worst-case scenarios more heavily when uncertainty is high
+
+### The Value of Integration
+
+Even without perfect information, considering all factors simultaneously reveals trade-offs:
+- A decision that slightly increases current time but dramatically improves future comprehension
+- An architecture that increases some change-sets but improves their proximity
+- A refactoring that hurts short-term velocity but enables long-term evolution
+
+The framework doesn't give a single answer but structures the decision space, making trade-offs explicit and measurable where possible.
+
+## Definition D-08: System Availability
+
+The probability that a system serves user requests successfully over time:
+
+$$\text{availability} = \frac{\text{MTTF}}{\text{MTTF} + \text{MTTR}}$$
+
+Where MTTF = Mean Time To Failure, MTTR = Mean Time To Recovery
+
+## T-12: Continuous Operation Under Perturbation (Scope Narrowing)
+
+For systems that must continue operating while evolving, time optimization includes recovery time from failures and external perturbations.
+
+### Scope Definition
+
+This theorem applies to systems where:
+- $E[\text{changes}_{\text{future}}] > 0$ (evolving systems per T-03)
+- $P(\text{perturbation}) > 0$ (subject to external shocks or internal failures)
+- $\text{required_availability} > \text{threshold}$ (must maintain operational status)
+
+### Formal Expression
+
+For continuously operating systems:
+
+$$T_{\text{effective}} = T_{\text{implementation}} + P(\text{failure}) \times T_{\text{recovery}}$$
+
+Where:
+- $T_{\text{implementation}}$ includes all development and deployment time
+- $P(\text{failure})$ is probability of failure per unit time
+- $T_{\text{recovery}}$ is time to restore operational status
+
+### The Infinite Time Principle
+
+From the user's perspective, a non-operational system has effectively infinite implementation time for any feature. Therefore, minimizing recovery time is mathematically equivalent to minimizing total time.
+
+### Strategic Trade-offs
+
+Different approaches optimize different terms:
+
+**Defensive Programming**:
+- High $T_{\text{implementation}}$ (extensive validation, error handling)
+- Aims for low $P(\text{failure})$
+- Often high $T_{\text{recovery}}$ when failures do occur (complex systems fail complexly)
+
+**Fault-Tolerant Design** (e.g., "let it crash"):
+- Lower $T_{\text{implementation}}$ (simpler code)
+- Accepts higher $P(\text{failure})$ 
+- Minimizes $T_{\text{recovery}}$ (fast restart, isolated failures)
+
+The optimal strategy depends on the relationship:
+
+$$\text{When } T_{\text{recovery}} \ll T_{\text{defensive}}, \text{ accepting failures is time-optimal}$$
+
+### Types of Perturbations
+
+Systems face different perturbation types:
+- **Impulse**: Sudden shock (traffic spike, deployment, config change)
+- **Stress**: Sustained pressure (degraded dependency, memory leak)
+- **Cascade**: Failure propagation through coupled components
+
+TST-principled systems minimize perturbation impact through:
+1. Low coupling (limits cascade per T-10)
+2. Fast recovery (minimizes $T_{\text{recovery}}$)
+3. Graceful degradation (maintains partial availability)
+
+### Implications for Architecture
+
+This explains the temporal optimality of patterns like:
+- **Supervision trees**: Minimize $T_{\text{recovery}}$ through fast, isolated restarts
+- **Circuit breakers**: Prevent cascade propagation
+- **Bulkheads**: Isolate failures to minimize scope
+- **Health checks**: Reduce detection time (part of $T_{\text{recovery}}$)
+
+### Limitations and Qualifications
+
+This theorem assumes:
+- Recovery is possible and meaningful
+- Partial availability is valuable
+- Failure probability can be estimated or bounded
+- Recovery time is measurable and finite
+
+For systems where these assumptions don't hold (e.g., safety-critical systems where any failure is catastrophic), different optimization strategies may apply.
+
+### Why This Extends TST
+
+This theorem doesn't abandon time optimization but extends it to operational reality. Development decisions that seem suboptimal under pure implementation time (T-08) become optimal when considering operational time. A simpler, more fragile component that restarts in milliseconds might be temporally superior to a complex, defensive component that takes minutes to recover when it eventually fails.
+
+---
+
+## The Synthesis
+
+These twelve theorems establish:
+1. **T-01**: Time is the fundamental metric after all constraints are satisfied
+2. **T-02**: Specification time bounds implementation speed
+3. **T-03**: We optimize for evolving systems, not static artifacts
+4. **T-04**: Past change predicts future change absent other information
+5. **T-05**: Comprehension and implementation must both be optimized, especially with high turnover
+6. **T-06**: Small time investments now compound into massive future savings or costs
+7. **T-07**: Code-domain alignment reduces comprehension time, justifying realignment as features evolve
+8. **T-08**: Implementation time is proportional to change-set size, making architecture measurable
+9. **T-09**: Proximity of changes within change-sets affects implementation time, possibly exponentially
+10. **T-10**: Coherence and coupling become measurable through historical change patterns
+11. **T-11**: Principled decisions integrate multiple temporal factors despite imperfect information
+12. **T-12**: Operational systems must optimize recovery time alongside implementation time
+
+Together they transform software engineering from aesthetic judgment to mathematical optimization. Every decision becomes measurable against temporal reality. The theory doesn't prescribe specific practices but reveals which practices minimize $\int P(\text{future}) \times \text{time}(\text{future}) \, d(\text{future})$.
+
+When you internalize these as mathematical necessities rather than helpful guidelines, you stop following "best practices" and start optimizing for the only metric that remains after all other constraints are satisfied: time.
+
+**The cognitive shift we seek**: Even in task-execution mode, when you're deep in implementation, these mathematical truths should surface at decision points. The moment you type `function`, the moment you name a variable, the moment you structure a module - these are optimization opportunities measured in minutes saved or lost, compounded over every future interaction. Feel the mathematics, don't just know it.