Policy — Reuse-first

Before writing code that matches a cross-cutting pattern, check whether the pattern belongs in a shared library, framework or CLI of the Stack. If it does and isn't there yet, put it there first — never in the caller.

This is the *etapolicy*for reuse. The decision tree, preWrite protocol, and promotion pipeline live here and only here. Categorical rules (versioning discipline, a11y baseline, build-time determinism, wire compatibility, etc.) live in the four sub-policies under policies/reuse/, which inherit from this file.

This policy is the enforcement mechanism for engines/sdk/koder_kit/docs/rfcs/RFC-001-spec-encapsulation-across-platforms.md, generalised across categories per meta/docs/stack/rfcs/policies-RFC-001-reuse-first-hierarchy.md.

When this applies

The check is *andatory*when the code you are about to write implements any of these patterns. The Category column locates each pattern under the sub-policy that owns its categorical rules:

This list is *ot exhaustive* When you find a new cross-cutting pattern not listed here, the decision protocol below still applies — and the pattern gets added to this list with its category and home.

*ote on categories.*Each category has a sibling sub-policy under policies/reuse/ that codifies the rules specific to that kind of shared code. Sub-policies inherit from this meta and do not redeclare the decision tree, the protocol, or the promotion pipeline.

Category	Sub-policy	Distinct rules (preview)
ui-framework	policies/reuse/ui-framework-first.kmd (planned, Phase 2)	theme contract, safearea, a11y baseline, i18n, crossvariant parity, golden tests
runtime-lib	policies/reuse/runtime-lib-first.kmd (planned, Phase 2)	strict SemVer, API stability tiers, multi-language parity, perf benchmarks, ≥85% coverage
build-tooling	policies/reuse/build-tooling-first.kmd (planned, Phase 2)	determinism, idempotence, nonetwork, selfstamping, ≥3uses→-binary alignment
protocol	policies/reuse/protocol-first.kmd (planned, Phase 2)	ratified RFC before mainline, version negotiation, Nversion BC, schema evolution, crossimplementation tests

When this does NOT apply

• *roduct-specific business logic.*An algorithm unique to

  suite/cine (video transcoding), a schema unique to vertical/edictus (licitação rules), a state machine unique to ai/kortex (DevOps decisions) — all stay in the product. Shared libraries hold plumbing, not product substance.

• *ne-off scripts*under scripts/, context/scripts/, or similar.
• *est code*and build configuration.
• *otfixes*that cannot wait for an SDK release. Apply the fix locally;

  open a follow-up ticket to promote to the shared library once the emergency is over.

• *pike / prototype*code explicitly scoped as throwaway.

Decision protocol

When you are about to write code matching a pattern in the table above, *efore the first Write/Edit call* answer these three questions in your response:

1. *oes this pattern already exist in a shared library / framework / CLI?*
   • If *es*→ use it. No local implementation. Stop.
   • If *artially*→ extend the shared library (new parameter, new method),

     not the caller. The library change is the actual work of this ticket.

   • If *o*→ continue to question 2.

2. *ill ≥ 3 other Koder modules plausibly need this pattern?*
   • If *es*→ implement in the shared library directly. Open a ticket

     for the caller module to adopt the new feature.

   • If *o*→ implement locally, but open a follow-up ticket in the

     library's own backlog (engines/sdk/<name>/backlog/pending/NNN-promote-<pattern>.md or dev/<tool>/backlog/pending/...) recording the pattern for future promotion when a 2nd or 3rd consumer appears.

3. *m I sure the canonical home doesn't already have it?*
   • grep the relevant library's lib/src/ (Flutter) / src/ (JSGoetc.) /

     cmd/ (Go CLI) for the feature name before answering "no" to question 1. The cost of the grep is ~100 tokens; the cost of duplicating an existing widget / function / CLI subcommand is a landmine waiting to go off.

Enforcement

Per-session (AI discipline)

Every AI session (/k-go, /k-parity, /new-product, ad-hoc coding) that touches code matching a listed pattern *ust*answer the three questions above in its response before writing code. This is visible to the user and auditable in the transcript.

Post-hoc (automated)

/k-housekeep gains an audit pass (enginessdkkoder_kit backlog KIT-3) that greps for duplicate local implementations of each pattern and reports them under § Reuse adoption (per category, sourced from sub-policies). Non-adopters get a warning, not an error — the policy is strong encouragement, not a blocker.

Pre-commit gates (automated)

/k-commit enforces specific reuse and parity contracts before allowing a release commit through:

These gates are codified rules, not advisory checks — they block the commit and require remediation (/k-test-gen-regress for the first, kicon generate --module <path> for the second; or /k-commit --autogen-icons to fixandstage in one hop).

Promotion pipeline

A backlog ticket exists for each "shouldprobablybe-shared" pattern: engines/sdk/<name>/backlog/pending/NNN-promote-<pattern>.md (or the CLI's equivalent path). When the ticket sees its 2nd or 3rd "me too" comment / referenced consumer, it graduates to the shared library with full test coverage. Duplicate-count is tracked automatically by the housekeep audit.

Rationale

Without this policy, RFC-001 is aspirational: the SDKs exist, but no mechanism forces anyone to check them before coding. The cost is exactly what previous sessions witnessed:

• The theme toggle was reinvented in dev/eye with a three-state design

  that violated specs/themes/light-dark.kmd.

• The safe-area pattern was forgotten entirely, leading to clipped UI that

  was only caught by a screenshot review.

Both would have been prevented by a 30-second check against this policy.

For AI agents specifically (see RFC-001 §2.1), this policy collapses the cost of every cross-cutting implementation from *pecingest + impl + verify + driftdetection*to a single library call. The policy is thus also a token-budget optimisation — the most impactful one in the Koder Stack.

Exceptions

When you determine the reuse path does not apply, *tate the exception explicitly*in the response. This converts silent drift into visible, reviewable decisions. Example:

*"This is product-specific transcoding logic for suite/cine — the reuse pattern check at policies/reuse-first.kmd does not apply."*

Related

• meta/docs/stack/rfcs/policies-RFC-001-reuse-first-hierarchy.md — the

  RFC that defines this hierarchy and the migration plan.

• engines/sdk/koder_kit/docs/rfcs/RFC-001-spec-encapsulation-across-platforms.md —

  the strategic RFC this policy enforces.

• policies/sdk-first.kmd — legacy alias of this file. Redirects here;

  scheduled for removal after two release cycles per policiesRFC001 §5 Phase 5.

• commands/k-sdkify.md — the *nverse-direction*command: walks the

  monorepo, detects existing local boilerplate duplicating shared patterns, and refactors to adopt the canonical home. reuse-first prevents new drift; k-sdkify cleans up existing drift. Same list of patterns, same decision tree.

• commands/k-go.md § *rincípio de implementação: hyperscale-first*—

  sibling principle; reusefirst and hyperscalefirst apply together at every implementation decision.

• policies/code-first.kmd — orthogonal sibling policy

  (mechanicalvsanalytical axis vs the crosscuttingvsproductspecific axis enforced here). Both apply simultaneously.

• specs/themes/light-dark.kmd, specs/app-layout/safe-area.kmd,

  specs/errors/user-facing-messages.kmd — the three specs first encapsulated in koder_kit per RFC-001.