This document outlines the detailed, staged implementation plan for the Salve Universal Greeting & Cultural Awareness Engine.

Status markers: [x] = completed, […] = partly done, [ ] = not yet started.

• Analyze chat history and capture all conceptual expansions.
• Draft Functional, Technical, and Architectural Requirements Specification.
• Finalize JSON schemas for greeting packs and event registries.

• M2.1: Monorepo Scaffolding
  • Initialize workspace (npm workspaces).
  • Setup @salve/core, @salve/registry, and @salve/types.
• M2.2: Core Resolution Engine
  • Implement context resolution (locale, time, traditions).
  • Build the deterministic priority scoring engine.
  • Implement "Maximal Cultural Specificity" selection logic.
• M2.3: Anti-Repetition Layer
  • Define pluggable memory interface (GreetingMemory).
  • […] Implement default localStorage provider for browser environments (interface exists, no built-in localStorage adapter).
• M2.4: Build & Test Infrastructure (Completed)
  • Stabilize ESM monorepo architecture and workspace aliases.
  • Unify Jest testing environment with ts-jest for import/export compatibility.

• M3.1: Gregorian Plugin
  • Implement baseline date resolution (fixed dates).
  • Support Nth-weekday rules (e.g., Thanksgiving).
  • Implement temporal slots (Morning, Afternoon, Evening, Night).
• M3.2: Religious Calendar Plugins
  • @salve/calendars-pascha: Orthodox and Western Easter calculations.
  • @salve/calendars-hijri: Tabular Islamic calendar or conversion utility.
• M3.3: Specialty Calendars
  • Implement seasonal transitions (solstices, equinoxes).
  • Support personal milestones (birthdays, anniversaries).
  • Add basic astronomical events (full moon, eclipses).

• M4.1: Address Resolver
  • Implement localized honorific resolution (Mr/Ms/Mx).
  • Support academic and professional title integration.
  • Implement formality-based address formatting.
• M4.2: Vocabulary & Punctuation
  • Implement locale-specific punctuation rules (comma placement).
  • Support for vocative case inflections (morphology hooks — Greek vocative).
• M4.3: Initial Address Packs
  • Create @salve/pack-global-addresses with basic honorifics.

• M5.1: Name-Day Core
  • Implement two-stage resolution (Date -> Saint -> Names).
  • Build the Alias Index fuzzy matching (diacritic removal, edit distance).
• M5.2: Name-Day Data Curation
  • Create @salve/pack-el-namedays (Greek) and @salve/pack-bg-namedays (Bulgarian).
  • Implement partitioning strategy for large alias datasets.

• M6.1: @salve/registry & Loader (Completed)
  • Implement manifest-based dynamic loading (SalveLoader).
  • Support for integrity hashes and selective payload inclusion.
  • Introduce a generated pack index or manifest that can classify YAML sources by family, scope type, selectors, and tags for future custom bundle compilation.
• M6.2: Distribution Infrastructure (Partially Complete)
  • […] Setup automated CI/CD for publishing packs to NPM and a central CDN (GitHub Actions workflows exist for Pages deploy and publish, but no CDN distribution).

• M7.1: Salve CLI (Completed)
  • salve init: Setup project config.
  • salve add <pack>: Manage dependencies and bundling.
  • salve resolve: Resolve greeting from CLI.
• M7.2: Developer Tools (Completed)
  • Visually interactive Developer Mode overlay (@salve/devtools).
  • Debugging trace for greeting resolution.
  • Standalone dev tools integration: Align and integrate the standalone Developer Playground (website/salve-dev-playground.html), Test Harness (website/salve-test-harness.html), and the Demo Webapp (packages/demo → website/) per Integration Plan: Dev Tools & Demo (three artifacts kept separate; shared context shape and test format; optional suite runner and real-engine wiring).
• M7.3: Project Documentation (In Progress)
  • Create comprehensive README with installation and usage guides.
  • Add standard open-source metadata (LICENSE, CITATION, FUNDING).
  • API Reference Generation: Set up TypeDoc or similar to generate site from TSDoc comments.
  • Cultural Implementation Guide: Author a comprehensive guide for pack contributors explaining JSON schemas and specificity scoring.

• M8.1: The "Salve" Showcase (Demo App) (Completed)
  • Refine packages/demo into a polished web experience powered by the real @salve/core engine and calendar plugins.
  • Interactive Playground: Add controls for Locale, Time, and User Attributes to see real-time resolution, including presets for multiple cultural scenarios.
  • "Explain Why" Visualization: Render a narrative reasoning paragraph with inline editable variables and expose scoring trace.
  • Static Showcase Build: Produce a single self-contained website/index.html (all JS and CSS inlined) suitable for file:// usage and GitHub Pages.
  • Polish typography and microcopy for the landing page hero by stripping the developer-specific layout (drawer, developer area) to maximize narrative immersion.
• M8.2: Ecosystem Seeding (Modular & Event Packs) (Completed)
  • Establish modular "Source of Truth" architecture: *.greetings.yaml, *.regions.yaml, and *.events.yaml.
  • Create JSON Schema for pack validation (data/greeting-pack.schema.json).
  • Create generator pipeline (scripts/generate-demo-packs.ts) to aggregate modular and cross-locale event packs into bundled TypeScript registries.
  • Seed and standardize 7 locale packs and 1 cross-locale event pack (Christian).
• M8.3: Geographic Locale Mapping (Completed)
  • Implement LocationResolver with point-in-polygon support.
  • Add hierarchical resolution logic (Priority-based specificity).
  • Populate comprehensive region data for the Dutch-speaking area (18 regions).
  • Populate comprehensive Greek holiday data (15+ events).
  • Add starter packs for key regions:
    • en-GB: Exhaustive greetings pack; en.locales.yaml for English locale geography; UK.events.yaml and US.events.yaml for British and US public holidays (including Thanksgiving).
    • Complete NL/EL/EN coverage for integrators (e.g. Dutch–Greek vocabulary apps): NL.events.yaml, NL.regions.yaml, GR.regions.yaml, Greek and English academic protocol, trilingual labels/greetings in BE/GR/NL/UK/US events. See docs/Coverage-Plan-NL-EL-EN.md.
    • de-DE: High-formality address protocols (existing de.protocol.academic.yaml; further expansion if needed).
    • ar-SA: Hijri calendar integration demonstration.

(Derived from chat transcript 014546)

• M9.1: Monorepo Package Extraction (Not Started)
  • Split Salve into focused, tree-shakeable packages: @salve/runtime, @salve/schema, etc.
  • Implement plugin architecture with 4 main kinds: pack.locale, pack.protocol, provider.holiday, and provider.nameday.
• M9.2: Greeting Ontology & Canonical Schemas (Completed)
  • Create greeting-pack.schema.json (JSON Schema Draft 2020-12) for locale pack validation.
  • Implement "Smart Inheritance" for locale and sources at the pack level to reduce redundancy.
  • Implement the formal Greeting Ontology defining rules by act (salutation, valediction, etc.), form (email_opening, address_only), and style (neutral, formal, ceremonial, etc.) — types and GreetingRule defined in @salve/types.
  • Shift phase terminology from session-based (open/close) to interaction-based (encounter/parting) across the entire stack.
  • Expand structural flexibility to natively support array unions for constraints like phase and notes without duplicating syntax rules.
  • Support multi-script greetings via embedded transliteration keys (and universal metadata) in YAML data packs.
• M9.3: Global Event Namespace Registry (Completed)
  • Create a deterministic Event Registry (salve.event.domain.region.name) with alias support.
  • Support domains: bank, civil, religious, personal, seasonal, protocol, affinity.
  • Implement Hybrid Event Model: Separation of Global (Tradition) and Regional (Locale) events.
  • Seed 14 default events covering bank holidays, religious observances, and personal events.
• M9.4: The Salve Context Normalization Algorithm (SCNA) (Mostly Complete)
  • Introduce pre-processing of API inputs into a unified SalveContextV1 → NormalizedContext.
  • Automatically derive region from locale, resolve missing timezones, and enforce BCP-47 strictness.
  • Establish strict separation between explicit memberships (identities) and soft affinities (interests/reminders).
  • Implement optional, low-confidence Gender Inference from given names as a non-authoritative hint.
• M9.5: Deterministic Resolution Pipeline & Scoring (Completed)
  • Refactor engine loop: Context Normalization -> Locale Fallback -> Event Collection -> Candidate Enumeration -> Scoring -> Address Resolution -> Style Rendering -> Composition.
  • Implement the ScoreTuple for strict tie-breaking: (DomainRank, EventRank, PackPrecedence, RulePriority, LocaleMatch, StableTieBreak).
• M9.6: Greeting Style Engine (Rhetorical Register) (Completed)
  • Introduce structural style modes: neutral, formal, ceremonial, poetic, playful, archaic, liturgical, bureaucratic, minimal.
  • Enable fallback routing (e.g., ceremonial -> formal -> neutral) to transform base greetings.
• M9.7: Subculture Protocol Packs & Affinity Providers (Partly Complete)
  • Define canonical v1 address/protocol type model (AddressPack, ProtocolPack, AddressTitleToken, AddressRule, ResolvedAddress, etc.) in @salve/types.
  • Create JSON schemas for address packs (address-pack.schema.json) and protocol packs (protocol-pack.schema.json).
  • Implement v1-first AddressEngine with title stacking, rule matching, protocol-pack gating, group/collective addressing, and safe degradation.
  • Implement CompositionEngine with locale-aware punctuation handling, separator policies, capitalization control, and developer-configurable SalveRenderPolicy.
  • Integrate address resolution and composition into SalveEngine.resolveV1() pipeline (SalveOutputV1WithAddress).
  • Expand @salve/pack-global-addresses with baseline civility AddressPack data for en, de, fr, nl, el.
  • Create first institutional protocol packs: protocol-academic-de, protocol-academic-nl, protocol-academic-fr, protocol-judicial-nl, protocol-diplomatic-en.
  • Add protocol workbench demo component (postal/letterhead/salutation mockups with configurable variables).
  • Add comprehensive test coverage for address engine, composition engine, title suppression, group addressing, and postal/letterhead distinction.
  • Implement "Affinity Reminders" (e.g., reminding a user in Belgium of a Japanese festival if they have an affinity for Japan).
  • Add protocol-royal-nl, protocol-diplomatic-nl, protocol-religious-* packs (postponed to post-MVP).
  • Expand to non-European address traditions (Japanese honorifics, Arabic titles, etc.).
• M9.8: Provider Integrations (Not Started)
  • Wrap date-holidays into @salve/provider-date-holidays for global bank holidays.
  • Standardize Nameday remote fetching via @salve/provider-namedays-* (Date -> Saint -> Names).
• M9.9: Demo Integration & Developer Trace API (Partially Complete)
  • Output SalveOutputV1 featuring primary greeting, secondary extras (affinities), and full scoring trace metadata.
  • Update the Demo UI with Style toggles, Affinity selections, and visual trace logs to build developer trust.

• M10.1: Launch Logistics
  • Final npm publish of all packages (v1.0.0).
  • GitHub Release creation with detailed changelog.
  • Public announcement and social sharing (inc. dedication).

• M11.1: Awareness Signaling & Profession Logic
  • Implement "Awareness Signaling" via event emojis across the engine.
  • Extend SCNA and greeting rules to support profession-based filtering (e.g., targeted greetings for teachers).
  • Implement FixedDateCalendarPlugin with precedence support for resolving date overlaps.
• M11.2: The Salve Harvester Framework
  • Initialized @salve/harvester monorepo package.
  • Refactored legacy scraping scripts into modular SalveHarvester classes.
  • Implemented "Smart Merging" logic to preserve curated greetings during automated authoritative data updates.
• M11.3: UN Secular Observances Expansion
  • Purged low-quality auto-generated UN greetings.
  • Mass-populated 247 UN observances with high-quality, WikiData-sourced official labels across 12 languages.
  • Verified localized idiomatic patterns for professional awareness greetings.
  • Applied premium formatting and month-heading restoration to the secular events dataset.

• M12A.1: data/packs Directory Reorganization
  • Reorganize pack YAML sources into category-first subdirectories: greetings/, events/, addresses/, protocol/, locales/, regions/, and namedays/.
  • Preserve stable machine-readable filenames instead of inventing human geography buckets such as greece-and-greek/.
  • Keep the canonical source tree precise even when contributors think in language or cultural context.
• […] M12A.2: Recursive Discovery & Shared Pack Index
  • Replace flat data/packs/ scans in generator scripts with shared recursive discovery via scripts/lib/discover-packs.ts.
  • Generate a normalized index or manifest recording pack family, scope type, selectors, and tags.
  • Use that index as the foundation for future custom pack compilation.
• M12A.3: Protocol Pack Naming Normalization
  • Migrate protocol filenames from domain-first style such as academic.nl.protocol.yaml to locale-first style such as nl.protocol.academic.yaml.
  • Align authoring conventions with contributor intuition and sorted file grouping by locale.
• M12A.4: Harvester Alignment
  • Update harvester output paths and maintenance documentation to align with the reorganized data/packs/ structure.
  • Keep harvester organization conceptually consistent with explicit scope axes used by pack sources.

• M12.1: Event Augmentation Mechanism
  • Implement WikiData-based merging and de-duplication in resolveV1.
  • Add support for property precedence (promoting categories to official).
  • Implement ID Stability & Promotion logic for reliable rule matching.
• M12.2: Belgian Cultural Data & Harvester
  • Develop BelgiumHarvester for automated procurement from Wikipedia.
  • Populate and verify Belgian regional data (BE.events.yaml, BE.regions.yaml).
• M12.3: Data Deduplication & Refinement
  • Create international.base.events.yaml to centralize shared holidays.
  • Refactor regional packs (BE, el-GR) to use WikiData-based augmentation.

• M13.1: Core EU Support
  • aims to support all 24 official EU languages: bg, hr, cs, da, nl, en, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv.
• M13.2: Major World Languages
  • aims to support: ar (Arabic), ru (Russian), tr (Turkish), zh (Chinese).
• M13.3: Regional Dialects
  • expand support for regional specificities (e.g., Flemish nl-BE).

• M14.1: Universal Holiday Inventory
  • Target 200+ countries/territories for public holiday coverage.
  • Implement master harvester for Wikipedia: Lists of holidays by country and Category: Lists of public holidays by country.
  • Implement harvester for Wikipedia: Bank holidays and Bank holidays in other countries.
• M14.2: Religious Heritage & Festival Expansion
  • Implement dedicated harvesters and calendar plugins for major world traditions.
  • Implement festival harvester based on Wikipedia: Lists of festivals (covering Country, Continent, and Sublists by type/topic).
  • Integrate multinational festivals and holidays.
• M14.3: Address & Protocol Data Procurement
  • Implement harvesters and curate authoritative sources to populate address and protocol packs to full coverage.
  • Implement harvester for Wikipedia: Style (form of address) — English-language honorifics, styles, and modes of address across civil, academic, judicial, diplomatic, religious, military, and royal/noble domains.
  • Implement harvester for Wikipedia: Anrede — German-language title stacking, academic titles, pronoun choice, and formal/informal address conventions.
  • Implement harvester for Wikipedia: Prédicat honorifique — French-language honorific predicates and addressing conventions across Francophone countries.
  • Implement harvester for Wikipedia: Aanspreekvorm — Dutch-language protocols of addressing, including civility, academic, judicial, diplomatic, clerical, and royal/noble titulature.
  • Implement harvester for Wikipedia: Academische graad — Dutch/Belgian academic degree system and associated predicates.
  • Implement harvester for Wikipedia: Predicaat (titel) — Dutch honorific predicates in royal, noble, clerical, academic, and judicial contexts.
  • Implement harvester for Taaladvies: Titels en titulatuur in Nederland — authoritative NL title and addressing guide.
  • Implement harvester for Taaladvies: Titels en titulatuur in België — authoritative BE title and addressing guide.
  • Curate address and protocol data from Van Dale Groot woordenboek der Nederlandse taal — manual extraction of honorific titles, professional titles, and formal usage conventions.
  • Curate address and protocol data from The Chicago Manual of Style (17th ed.) — English-language forms of address, title usage, and correspondence conventions.
• M14.4: Automated Maintenance Pipeline
  • Scale the harvester framework to handle daily/weekly monitoring of global holiday shifts.
• M14.5: Harvester Generalization & Pattern Extraction
  • Once 3-5 specific harvesters are stable, refactor the core logic into a generalized, configuration-driven harvester to minimize custom code for new Wikipedia-based sources.