process: Reconcile design principles between plan-spec and tbd-design.md

The user pointed out the new Design Principles in the docs-config plan
should be cross-referenced and consolidated with the existing tbd-design
principles. Three changes:

1. tbd-design.md §1.5 (Design Principles) extended from 6 to 10:
   - #1 (Simplicity first) extended to spell out "simple things simple,
     complex things possible".
   - #3 (Git for sync) extended with the reproducible-from-config
     contract.
   - #7 added: Auth is always out-of-band — tbd never holds credentials.
   - #8 added: Hard cuts on format versions with reliable migration —
     already practiced for f02→f03; making it an explicit principle.
   - #9 added: Spec ↔ implementation synchrony via tests.
   - #10 added: Layered architecture, separable artifacts.

   These four new principles emerged from the docs-config redesign work
   but apply tbd-wide.

2. tbd-design.md §1.4 Design Goals: added goal #8 (extensible knowledge
   subsystem), which links forward to the plan-spec and the docref/
   docmap design docs as the authoritative location for that subsystem's
   design.

3. plan-spec Design Principles intro: now explicitly notes that P1, P5,
   P6, P7, P8, P9 are restatements/elaborations of tbd-design §1.5
   principles, while P2, P3, P4 are docs/config-specific and have no
   direct system-wide analog. Each restated principle gets an inline
   "(extends tbd-design §1.5 #N)" cross-reference. tbd-design.md is
   declared authoritative for system-wide values.

This consolidates principles in one foundational location (tbd-design.md)
while keeping the docs-config plan readable on its own.

https://claude.ai/code/session_01PhbYdWX7DUBpUBVuUesVuP

Author: claude

docs/project/specs/active/plan-2026-05-07-docs-config-redesign.md

@@ -311,11 +311,19 @@ Other consumers — present or future — would only need to implement the docma
 
 ## Design Principles
 
-These are the values the design serves.
-When the open questions (Q1–Q20) are resolved, the answers should be the ones most
-consistent with these principles.
+These are the values this redesign serves.
+When the open questions (Q1–Q20) are resolved, the answers should be most consistent
+with these principles.
 
-### P1. Simple things simple, complex things possible
+The principles below extend the system-wide design principles in
+[tbd-design.md §1.5](../../../packages/tbd/docs/tbd-design.md#15-design-principles).
+P1, P5, P6, P7, P8, and P9 here are restatements or doc-system-specific elaborations of
+principles in that doc; P2, P3, and P4 are docs/config-specific principles without a
+direct system-wide analog.
+Anything inconsistent between the two should be reconciled in tbd-design.md, which is
+authoritative for system-wide values.
+
+### P1. Simple things simple, complex things possible (extends tbd-design §1.5 #1)
 
 Adding a typical doc bundle should be a single command that “just works” — no config
 edits, no per-doc rules, no upstream coordination.
@@ -346,34 +354,34 @@ Every doc that exists in any source should be discoverable through the format (G
 Shadowing, overriding, ambiguity, and collisions are properties of the *view*, not of
 the inventory. The raw graph never hides anything; tooling builds policy views over it.
 
-### P5. Reproducible from config
+### P5. Reproducible from config (extends tbd-design §1.5 #3)
 
 Given the manifest, the lockfile, and a working network, two clones of a repo produce
 caches with identical content (G9). Sync is idempotent; update is the explicit forward
 step. Lockfile carries enough identity (Q17) to make this contract robust under bundle
 moves and source reshapes.
 
-### P6. tbd never holds credentials
+### P6. tbd never holds credentials (extends tbd-design §1.5 #7)
 
 Authentication is always out of band: git’s credential helpers, `gh` CLI, AWS profiles,
 etc. (G13). The format has no auth fields, ever.
 Public sources just work; private sources rely on the user’s environment.
 
-### P7. The format is a separable artifact
+### P7. The format is a separable artifact (extends tbd-design §1.5 #10)
 
 docref and docmap are tool-agnostic specifications with reference implementations.
 tbd is the first consumer; others can adopt the formats without depending on tbd code
 (G18). Architectural decisions that benefit a single tool but burden the format (e.g.,
 baking tbd-specific overrides into the schema) are rejected in favor of layering —
 tbd-specific concerns live above the format.
 
-### P8. Hard cuts on format versions, reliable migration
+### P8. Hard cuts on format versions, reliable migration (extends tbd-design §1.5 #8)
 
 Schema versions are clean breaks at the boundary; runtime supports exactly one shape;
 deprecated fields are detected, migrated, and deleted (G11). Forward compatibility lives
 in `.strict()` validation and migration tests, not in layered field-level fallbacks.
 
-### P9. Tests are spec mirrors
+### P9. Tests are spec mirrors (extends tbd-design §1.5 #9)
 
 Every spec example has a corresponding test; every change to either side requires the
 matching change to the other.

packages/tbd/docs/tbd-design.md

@@ -448,20 +448,51 @@ tbd addresses specific requirements:
 7. **Easy migration**: `tbd import <beads-export.jsonl>` or `tbd import --from-beads`
    converts existing Beads databases
 
+8. **Extensible knowledge subsystem**: Shortcuts, guidelines, templates, and other doc
+   types ("categories") can be authored locally, mirrored from external git repos or
+   URLs, overridden in shadcn-style local forks, and round-tripped back upstream — using
+   a tool-agnostic format (`docref` for addressing,
+   [`docmap`](./design-docmap-format.md) for the manifest/lockfile/index/sync layer)
+   that can be extracted as standalone libraries.
+   Detailed design lives in
+   [plan-2026-05-07-docs-config-redesign.md](../../../docs/project/specs/active/plan-2026-05-07-docs-config-redesign.md).
+
 ### 1.5 Design Principles
 
 1. **Simplicity first**: Prefer boring, well-understood approaches over clever
-   optimization
+   optimization. Simple things should be simple; complex things should be possible.
+
+2. **Files as truth**: Markdown + YAML files on disk are the canonical state.
+
+3. **Git for sync**: Standard git commands handle all distribution.
+   Reproducible from config: given the manifest/lockfile and a working network, two
+   clones produce identical state.
+
+4. **No required daemon**: CLI-first, background services optional.
+
+5. **Debuggable by design**: Every state change is visible in files and git history.
 
-2. **Files as truth**: Markdown + YAML files on disk are the canonical state
+6. **Progressive enhancement**: Core works standalone, bridges/UI are optional layers.
 
-3. **Git for sync**: Standard git commands handle all distribution
+7. **Auth is always out-of-band**: tbd never holds credentials.
+   Authentication is delegated to the underlying tool’s own mechanisms (git credential
+   helpers, `gh` CLI, AWS profiles, etc.). The format has no auth fields, ever.
 
-4. **No required daemon**: CLI-first, background services optional
+8. **Hard cuts on format versions, reliable migration**: Each format version is the only
+   valid shape at runtime; deprecated fields are detected on read, migrated in one shot,
+   and never re-emitted.
+   Forward compatibility lives in strict schema validation and migration tests, not in
+   layered runtime fallbacks.
 
-5. **Debuggable by design**: Every state change is visible in files and git history
+9. **Spec ↔ implementation synchrony via tests**: Reference implementations of
+   format-level specs (Zod schemas, parsers, resolvers) are kept in sync with their
+   specs by tests that mirror every spec example.
+   Changes to either side require a matching change to the other.
 
-6. **Progressive enhancement**: Core works standalone, bridges/UI are optional layers
+10. **Layered architecture, separable artifacts**: Tool-agnostic format specifications
+    (e.g., docref, docmap) are layered below tool-specific workflows.
+    Format specs are extractable as standalone libraries; tbd-specific policy
+    (overrides, eject, roundtrip) sits above and depends on the format.
 
 ### 1.6 Non-Goals