📖 [Docs]: Software design principles now cover smart defaults and local overrides

src/docs/Ways-of-Working/Principles/Software-Design.md

@@ -1,6 +1,6 @@
 ---
 title: Software design
-description: SOLID, extensibility, DRY with judgment, and making change easy before making the change.
+description: SOLID, extensibility, smart defaults with local overrides, DRY with judgment, and making change easy before making the change.
 ---
 
 # Software design
@@ -19,6 +19,28 @@ Extend by adding, not by modifying what already works — the Open/Closed princi
 
 The system stays pluggable: the docs do not change when a new agent runtime is added — only a new integration layer is written. See the [Agentic Development](../Agentic-Development.md) specification for how this plays out in practice.
 
+## Smart defaults, local overrides
+
+The default is the smart, secure choice — what you would pick most of the time, and the safe option when unsure. A system with no configuration is already correct, safe, and useful out of the box. Configuration exists to *deviate* from a good default, never to reach a usable one.
+
+Set the default at the broadest scope, and let each narrower scope override it. The setting closest to the thing it controls wins:
+
+```text
+org / ecosystem     the widest default — set once, inherited everywhere
+└── repository      may narrow the default for one codebase
+    └── directory   may narrow it further for one area
+        └── item    the last word — closest to what it configures
+```
+
+This shape is chosen for manageability over the life of a system, and it earns two properties at once:
+
+- **Manageable across the wide.** Change the default in one place and everything that has not opted out follows. You set the norm once instead of finding and editing many copies of it.
+- **Flexible in the narrow.** Deviating is a small, local edit beside the item that needs it — not a fight with the system, and not a change that ripples outward. The exception lives with the thing it applies to.
+
+Make the wide default easy to set and the local override easy to make. When the two disagree, the more specific one wins — predictably, by its position in the hierarchy, never by special-casing.
+
+This is [Easy and Safe](../../index.md) expressed as design: doing the right thing takes no effort because it is the default, and deviating is deliberate and contained because it is a local override. [Least-privilege](Purpose-and-Direction.md) and [secure by default](../../Coding-Standards/Security.md) are this principle applied to permissions and security; the way [the vision cascades](../../Vision/index.md) is its shape applied to knowledge.
+
 ## DRY — with judgment
 
 Don't Repeat Yourself, but **don't extract too early**. Wait until the same non-trivial logic appears in three or more places, or until the duplication is clearly load-bearing. Premature abstraction is more expensive than duplication.

src/docs/Ways-of-Working/Principles/index.md

@@ -15,7 +15,7 @@ Principles are grouped by theme; each theme is its own page so an agent can load
 | --- | --- |
 | [Purpose and direction](Purpose-and-Direction.md) | Why we build, who we build for, and the least-privilege stance under every decision. |
 | [AI-first development](AI-First-Development.md) | Agents as first-class participants, determinism before intelligence, and how humans and agents share the work. |
-| [Software design](Software-Design.md) | SOLID, extensibility, DRY with judgment, and making change easy before making the change. |
+| [Software design](Software-Design.md) | SOLID, extensibility, smart defaults with local overrides, DRY with judgment, and making change easy before making the change. |
 | [Engineering practices](Engineering-Practices.md) | Write it down, everything as code, evergreen docs, test-driven development, and shift-left quality. |
 | [Planning and delivery](Planning-and-Delivery.md) | Roadmapping, lean delivery, and the loops that keep iteration fast. |
 | [References](References.md) | The literature behind these principles. |