########################################################################
# Module overlay template.
#
# Copy to `modules/<YourModule>.yml` and fill in from EVIDENCE IN YOUR OWN CODE.
# A real overlay is never shipped with this skill: it quotes module paths, symbol
# names and call-site counts, so it describes one codebase and would bind another
# codebase's slots to the wrong dialect.
#
# The rule that makes this safe: an UNBOUND slot DISABLES its rules. Leaving a
# slot empty costs you those checks and the audit says so. Guessing a value costs
# you a hundred findings against a module that made the other defensible choice,
# which is a migration proposal wearing a standards pass. Empty beats guessed.
#
# Every `*_evidence` field wants a COUNT, not a preference. The count is the only
# thing that distinguishes "this module chose a dialect" from "this module has a
# defect". No count, no binding.
########################################################################

module: <YourModule>
path: <Path/To/Module>
role: feature # feature | common | app
registry_version: 1.1.0
updated: <YYYY-MM-DD>

description: >
  Per-module overlay for the shared registry. Carries what code cannot state: the vocabulary
  bindings a rule needs to generate its check, the module's dialect choices, prohibitions that
  currently have zero instances, deliberate carve-outs, and the real verification command.

# --- Dialect slots -----------------------------------------------------
# Bind only what you can evidence. See `rules.yml -> module_overlay_slots`
# for what each slot governs and which values are defensible.
dialect:
  # Governs SVC-07. Values: send-path | domain-verb
  ServiceNamingScheme:
  ServiceNamingScheme_evidence: >
    Count both spellings before binding, e.g. "N `func send<Path>` against M `func fetch<X>`".
    The minority spelling is then the finding this rule should report. If the counts are close,
    the module has not chosen  -  leave the slot unbound and raise the split as the finding.

  # Governs NAME-01. Values: coordinator-event | output-closure
  NavExitShape:
  NavExitShape_evidence: >
    Count typed event enums against output closures, and name the handler symbol the coordinator
    applies.

  # Governs READ-04b. Any consistent directory name; two names in one module is the violation.
  ComponentsDir:

# --- Vocabulary --------------------------------------------------------
# Symbol and path slots the judgement rules need in order to generate a check.
# An unfilled slot disables the rules that read it.
vocabulary:
  ScreenRoot: <Sources/<Module>/Screens>
  ScreenRoleSuffixes: [] # e.g. [Scene, ViewModel, UseCase, Repository, Mapper]
  HandlerName: "<Screen><Suffix>"

# --- Sensitive data inventory -----------------------------------------
# Drives SEC-01 in both directions: a sensitive value over-persisted, AND a
# transient value persisted at all. Classify every one the module handles;
# see `rules.yml -> sensitive_data_classes` for the classes and their at-rest
# and loggable rules. An unclassified symbol cannot be checked.
sensitive_data: []

# --- Zero-instance prohibitions ---------------------------------------
# Shapes this module has never contained and intends never to. Recording the
# zero is what makes the first instance a regression instead of a debate.
prohibitions: []

# --- Carve-outs --------------------------------------------------------
# Deliberate deviations, each with a rule ID and a reason. A carve-out here is
# a decision; the same deviation unmarked in code is a finding. In-code form:
#   // standard:exception(<RULE-ID>) <reason> <expiry:YYYY-MM-DD>
carve_outs: []

# --- Verification ------------------------------------------------------
# The command that actually proves this module builds and its tests pass.
# The audit runs this rather than assuming a scheme name.
validation:
  command:
  notes: >
    Name the real scheme/target. A wrong command that exits 0 is worse than no command.