Abstract: This paper formalizes the "Narrowest-Scope Rule" (NSR), a governance principle for maintaining the integrity of the contract-style-comments (CSC) Triumvirate. NSR provides a deterministic heuristic for artifact selection during system updates, ensuring that operational data, architectural invariants, and teleological reasoning remain logically decoupled to prevent documentation rot and "contextual drift."
Jeffrey Sabarese (@ajaxstardust)
Part III of the contract-style-comments Series
I. The Problem: Documentation Entropy
In classical development, documentation suffers from monolithic bloat: new information is appended to the nearest visible file, regardless of logical category. In agentic systems, this leads to Context Window Dilution. When an AI agent must ingest a CONTRACT.md cluttered with transient operational details, the signal density of the system's core invariants is diminished.
The Narrowest-Scope Rule (NSR) acts as a systemic constraint to preserve signal density. It mandates that every system update be recorded in the most granular artifact that fully contains the change.
II. Objective Methodology: Deterministic Artifact Selection
Case Study: Autonomous Signal Routing
In a controlled engineering environment, an AI agent was tasked with introducing a new visualization pipeline. The system was governed by the CSC Triumvirate. Upon completion of the technical implementation, the agent performed an autonomous update of the QUICKSTART.md artifact, bypassing the root CONTRACT.md and the meta-document WHY.md.
No new top-level doc. No change to CONTRACT.md.
III. Analysis: Operational vs. Invariant Change
The agent's artifact selection demonstrated an internalized hierarchy of scope. Because the change was operational (a new execution path for existing data), it belonged in the document governing empirical state: QUICKSTART.md. Appendage to CONTRACT.md would have constituted a category error, mixing transient instructions with immutable system laws.
The change was “how to run another analysis tool.” The document that already fully contains that kind of information is QUICKSTART. Creating a new file (e.g. VISUALIZATION.md or a tool-specific doc) would split “how to run things” across multiple artifacts. The next agent would have to look in one place for the table, another for static figures, and another for the new tool. Updating the narrowest document that fully contains the change — QUICKSTART — keeps a single entry point for run instructions and keeps the key-files table as the one map of important scripts.
So I didn’t have to decide where to put it. The structure we’d already set up — CONTRACT for invariants, QUICKSTART for how to run and what’s proven — made the right target obvious to the agent.
IV. Theoretical Formalization: Reading Order as Scope
The efficacy of the NSR is predicated on a strictly defined Reading Order. In the CSC framework, reading order is synonymous with systemic depth. CONTRACT.md defines what the system is; WHY.md defines the teleology; QUICKSTART.md defines how the system runs. By adhering to the NSR, we ensure that the agent's ingestion path remains optimized for the current task's depth.
CONTRACT.md is for invariants and constraints — what the system is and what must not break. A new script and its run instructions are not invariants; they’re operational. Putting them in CONTRACT would bloat it and mix concerns. The key-files table in QUICKSTART is the right place to register that the script exists and what it does; CONTRACT stays the place you read to know what you cannot change.
CONTRACT answers “what is this and what must I not break?” QUICKSTART answers “how do I run it and what’s been proven?”
V. Conclusion: The "Narrowest Artifact" Heuristic
The Narrowest-Scope Rule is the mechanism that prevents documentation from becoming "fiction." By requiring updates to land in the most granular applicable artifact, we ensure that the Triumvirate remains a living, accurate reflection of the system. This precision is the essential "Handshake" required for the next epoch of software engineering, where documentation is no longer for human leisure, but for agentic synchronization.
The same “narrowest scope” idea applies: the change was fully contained by “how to run analysis and what key files exist.” That’s QUICKSTART’s scope. So QUICKSTART got the update — a new subsection and a new row in the table — and CONTRACT was left unchanged. The agent didn’t have a separate “narrowest artifact” rule; it had the existing reading order (CONTRACT → why → QUICKSTART) and the existing structure of QUICKSTART. That was enough to choose the right target.
The NSR Postulate: Update the narrowest artifact that fully contains the change. If the change is an invariant, update CONTRACT.md. If the change is operational, update QUICKSTART.md.
This analysis defines the third pillar of the contract-style-comments framework. For the full architectural manifesto, visit WhatsOnYourBrain.com.
Leave a comment, or find me at @ajaxstardust.
Top comments (0)