RFC — Reuse-First policy hierarchy

1. Summary

Replace the single policies/sdk-first.kmd with a *wo-level hierarchy*

• *policies/reusefirst.kmd`*(meta) — single source of truth for the crosscutting decision tree, the pre-Write protocol, the promotion pipeline, and the canonical pattern → category → home table.
• *policiesreusecategoryfirst.kmd`*(subpolicies, 4 of them) — declare inherits_from: reuse-first.kmd in frontmatter and add *nly*the rules that are categorically distinct (versioning, breaking-change discipline, testing thresholds, build determinism, wire compatibility, etc.).

The decision tree is *ever duplicated*— it lives only in the meta. Subpolicies extend, they do not reimplement. `sdkfirst.kmd` becomes a redirect stub for one or two release cycles, then is removed.

2. Motivation

The current sdk-first.kmd carries three problems that compound as the Stack grows:

1. *aming is narrower than scope.*The policy covers UI framework, runtime libs, build-time CLIs and protocol clients — but the name suggests "API client SDK only". New engineers (and AI sessions) underestimate which patterns are in scope.
2. *ategorical rules are implicit.*Today you discover that a runtime lib should follow strict SemVer or that a buildtime tool must be hashstable only by reading other policies (releases.kmd, code-first.kmd) or by tribal knowledge. Nothing forces these rules at the source where they apply.
3. *he flat 15row table will not scale.*As the Stack adds patterns (e.g. shared ML model artefacts, kernel extensions, codec engines) the table inflates and categoryspecific search becomes manual.

A flat split into four independent policies was considered (and rejected — see §9): it would duplicate the decision tree four times, exactly the crossLLM drift `codefirst.kmd` warns against.

The hierarchy proposed here avoids both ends: the decision tree stays unique; the categorical content gets first-class location.

3. Design

3.1 Two-level structure

meta/docs/stack/policies/
├── reuse-first.kmd                          ← meta (replaces sdk-first.kmd)
├── code-first.kmd                           ← sibling, untouched
└── reuse/                                   ← sub-policy directory
    ├── ui-framework-first.kmd
    ├── runtime-lib-first.kmd
    ├── build-tooling-first.kmd
    └── protocol-first.kmd

The meta policy is one file; subpolicies are one file each, scoped to a single category. Adding a fifth category later (e.g. `mlassetfirst`) is a singlefile addition; no policy needs to grow.

3.2 Frontmatter schema

The meta reuse-first.kmd keeps its current frontmatter shape (name, type: policy, mandatory: true, triggers, references).

Sub-policies declare an extra field:

---
name: UI Framework First
type: policy
inherits_from: policies/reuse-first.kmd
mandatory: true
category: ui-framework
audit:
  applicable_to:
    - "engines/sdk/koder_kit
app/**/*.dart"
  script: ./ui-framework-first-audit.sh
  severity: strict
summary: |
  …categorical rules only…
---

inherits_from is structurally validated: a subpolicy that does not declare it (or declares an invalid path) fails `koderspecaudit reuse`. Subpolicies must NOT redeclare the decision tree, the protocol, or the promotion pipeline.

3.3 Layout — what goes where

3.4 Audit

koder-spec-audit reuse (a new subcommand of the existing `koderspecaudit` binary tracked in KSTACK101) performs three structural checks:

1. *nheritance link valid.*Every file under policies/reuse/ declares inherits_from: policies/reuse-first.kmd in its frontmatter, and the target file exists.
2. *o duplicated content.*Sub-policies do not contain the decision tree (heuristic: no h2/h3 with text matching Decision (tree|protocol), When this applies, Promotion pipeline).
3. *ategory coverage.*Every row in the meta pattern → category → home table cites a category that has an existing sub-policy.

The audit is *trict*for subpolicy structural validity and *dvisory*for table coverage (a new category may exist briefly before its subpolicy is written).

4. Categorical content preview

Each sub-policy is justified only if it carries *t least three substantive categorical rules*that the meta cannot express. The four below clear that bar.

4.1 ui-framework-first.kmd

Applies to: `enginessdkkoder_kit