feat(quando-4bh): implement Unit type and constants

- Define Unit type as int for type-safe time unit constants
- Implement all 8 unit constants (Seconds through Years) using iota
- Add String() method for debugging and error messages
- Comprehensive unit tests verifying constants, ordering, and comparability
- Type safety tests demonstrating compile-time safety
- Example tests showing usage patterns
- 100% test coverage (exceeds 95% requirement)

All acceptance criteria met:
✓ Unit type defined as int
✓ All 8 unit constants defined (Seconds through Years)
✓ Units use iota for ordering
✓ Godoc comments for Unit type and constants
✓ Unit tests verifying constants

.beads/issues.jsonl

@@ -1,7 +1,7 @@
 {"id":"quando-10t","title":"Human-readable duration format with i18n","description":"Implement Human() method on Duration for human-readable output with internationalization.\n\n**API:**\n```go\nfunc (dur Duration) Human() string\nfunc (dur Duration) Human(lang Lang) string\n```\n\n**Adaptive Granularity:**\nAlways show the two largest relevant units:\n\n| Difference | EN Output | DE Output |\n|------------|-----------|-----------|\n| 10 months, 16 days | \"10 months, 16 days\" | \"10 Monate, 16 Tage\" |\n| 2 days, 5 hours | \"2 days, 5 hours\" | \"2 Tage, 5 Stunden\" |\n| 3 hours, 20 minutes | \"3 hours, 20 minutes\" | \"3 Stunden, 20 Minuten\" |\n| 45 seconds | \"45 seconds\" | \"45 Sekunden\" |\n| 0 | \"0 seconds\" | \"0 Sekunden\" |\n\n**Language Support (Phase 1):**\n- EN (English) - default\n- DE (Deutsch) - must-have\n\n## Acceptance Criteria\n- [ ] Human() without argument returns English\n- [ ] Human(Lang) accepts language parameter\n- [ ] Adaptive granularity: two largest units\n- [ ] English translations complete\n- [ ] German translations complete\n- [ ] Zero duration handled (\"0 seconds\")\n- [ ] Singular/plural forms correct (1 day vs 2 days)\n- [ ] Unit tests for all granularity levels\n- [ ] Unit tests for both EN and DE\n- [ ] Benchmark meets \u003c10µs target with i18n\n- [ ] Godoc comments with examples in both languages","status":"open","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:12.954367096+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:12.954367096+01:00","dependencies":[{"issue_id":"quando-10t","depends_on_id":"quando-ljj","type":"blocks","created_at":"2026-02-11T16:23:09.100489733+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-10t","depends_on_id":"quando-zbr","type":"blocks","created_at":"2026-02-11T16:23:09.139531731+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-36t","title":"Error types and handling","description":"Define custom error types and establish error handling patterns for the library.\n\n**Sentinel Errors:**\n```go\nvar (\n    ErrInvalidFormat   = errors.New(\"invalid date format\")\n    ErrInvalidTimezone = errors.New(\"invalid timezone\")\n    ErrOverflow        = errors.New(\"date overflow\")\n)\n```\n\n**Error Handling Principles:**\n1. NEVER panic (except Must* variants)\n2. Use sentinel errors for known error types\n3. Wrap errors with fmt.Errorf(\"%w\") for context\n4. Return clear, actionable error messages\n\n**Error Categories:**\n- Parse errors: Invalid formats, ambiguous inputs\n- Timezone errors: Unknown IANA names\n- Overflow errors: Date arithmetic outside Go's time.Time range\n\n**Documentation:**\n- Document that library never panics in normal operation\n- Document that Must* variants DO panic\n- Provide error handling examples\n\n## Acceptance Criteria\n- [ ] errors.go file created\n- [ ] ErrInvalidFormat defined\n- [ ] ErrInvalidTimezone defined\n- [ ] ErrOverflow defined\n- [ ] Godoc for each error with usage context\n- [ ] Documentation of no-panic policy\n- [ ] Documentation of Must* panic behavior\n- [ ] Example tests showing error handling patterns","status":"open","priority":1,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:22.314746489+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:22.314746489+01:00","dependencies":[{"issue_id":"quando-36t","depends_on_id":"quando-91w","type":"blocks","created_at":"2026-02-11T16:23:05.380454674+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-41g","title":"Timezone support and conversion","description":"Implement timezone conversion with proper DST handling.\n\n**API:**\n```go\nfunc (d Date) In(location string) (Date, error)\n```\n\n**Behavior:**\n- Convert date to specified IANA timezone\n- Return error for invalid timezone names (never panic)\n- Use IANA Timezone Database\n- Default timezone: UTC if not specified\n\n**DST Handling:**\nCritical: `Add(1, Days)` means \"same time next calendar day\", NOT 24 hours\n- Example: 2026-03-31 02:00 CET + 1 Day = 2026-04-01 02:00 CEST\n- This is only 23 actual hours due to DST transition\n- Rationale: Humans think in calendar days, not hour deltas\n\n**Error Handling:**\n- Validate IANA timezone names\n- Return clear error for unknown timezones\n- Return clear error for empty timezone string\n\n## Acceptance Criteria\n- [ ] In(location) implemented\n- [ ] Uses IANA Timezone Database\n- [ ] Converts to specified timezone correctly\n- [ ] Invalid timezone names return error\n- [ ] Empty string returns error\n- [ ] Never panics on invalid input\n- [ ] DST handling: Add(Days) preserves wall clock time\n- [ ] Tests across DST transitions (spring and fall)\n- [ ] Tests for multiple timezones (Europe/Berlin, America/New_York, etc.)\n- [ ] Unit tests with 95%+ coverage\n- [ ] Godoc with DST behavior clearly explained\n- [ ] Example showing DST-safe arithmetic","status":"open","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:14.704688038+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:14.704688038+01:00","dependencies":[{"issue_id":"quando-41g","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:13.346573362+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-41g","depends_on_id":"quando-36t","type":"blocks","created_at":"2026-02-11T16:23:13.384247178+01:00","created_by":"Oliver Jakoubek"}]}
-{"id":"quando-4bh","title":"Unit type and constants","description":"Define Unit type for time unit constants used in arithmetic operations.\n\n**Technical Details:**\n```go\ntype Unit int\n\nconst (\n    Seconds Unit = iota\n    Minutes\n    Hours\n    Days\n    Weeks\n    Months\n    Quarters\n    Years\n)\n```\n\n**Design:**\n- Type-safe constants (compile-time safety)\n- Use iota for clear ordering\n- Optional internal ParseUnit(string) for external inputs\n\n## Acceptance Criteria\n- [ ] Unit type defined as int\n- [ ] All 8 unit constants defined (Seconds through Years)\n- [ ] Units use iota for ordering\n- [ ] Godoc comments for Unit type and constants\n- [ ] Unit tests verifying constants","status":"open","priority":0,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:20:37.246514285+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:20:37.246514285+01:00","dependencies":[{"issue_id":"quando-4bh","depends_on_id":"quando-91w","type":"blocks","created_at":"2026-02-11T16:23:05.349519431+01:00","created_by":"Oliver Jakoubek"}]}
+{"id":"quando-4bh","title":"Unit type and constants","description":"Define Unit type for time unit constants used in arithmetic operations.\n\n**Technical Details:**\n```go\ntype Unit int\n\nconst (\n    Seconds Unit = iota\n    Minutes\n    Hours\n    Days\n    Weeks\n    Months\n    Quarters\n    Years\n)\n```\n\n**Design:**\n- Type-safe constants (compile-time safety)\n- Use iota for clear ordering\n- Optional internal ParseUnit(string) for external inputs\n\n## Acceptance Criteria\n- [ ] Unit type defined as int\n- [ ] All 8 unit constants defined (Seconds through Years)\n- [ ] Units use iota for ordering\n- [ ] Godoc comments for Unit type and constants\n- [ ] Unit tests verifying constants","status":"in_progress","priority":0,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:20:37.246514285+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:33:36.286525071+01:00","dependencies":[{"issue_id":"quando-4bh","depends_on_id":"quando-91w","type":"blocks","created_at":"2026-02-11T16:23:05.349519431+01:00","created_by":"Oliver Jakoubek"}],"comments":[{"id":4,"issue_id":"quando-4bh","author":"Oliver Jakoubek","text":"Plan: 1) Create unit.go with Unit type as int, 2) Define all 8 unit constants (Seconds, Minutes, Hours, Days, Weeks, Months, Quarters, Years) using iota, 3) Add String() method for better debugging, 4) Add comprehensive godoc comments, 5) Write unit tests verifying constants and ordering, 6) Add example tests","created_at":"2026-02-11T15:33:41Z"}]}
 {"id":"quando-5ib","title":"Date inspection methods","description":"Implement date inspection methods for querying metadata about a date.\n\n**Individual Methods:**\n```go\nfunc (d Date) WeekNumber() int\nfunc (d Date) Quarter() int\nfunc (d Date) DayOfYear() int\nfunc (d Date) IsWeekend() bool\nfunc (d Date) IsLeapYear() bool\n```\n\n**Aggregated Method:**\n```go\ntype DateInfo struct {\n    WeekNumber int\n    Quarter    int\n    DayOfYear  int\n    IsWeekend  bool\n    IsLeapYear bool\n    Unix       int64\n}\n\nfunc (d Date) Info() DateInfo\n```\n\n**Specifications:**\n- **WeekNumber**: ISO 8601 (Monday first, Week 1 = first week containing Thursday)\n- **Quarter**: 1-4 (Q1=Jan-Mar, Q2=Apr-Jun, Q3=Jul-Sep, Q4=Oct-Dec)\n- **DayOfYear**: 1-366 (considering leap years)\n- **IsWeekend**: Saturday or Sunday (not configurable in Phase 1)\n- **IsLeapYear**: Divisible by 4, except centuries, except divisible by 400\n\n## Acceptance Criteria\n- [ ] WeekNumber() returns ISO 8601 week number\n- [ ] Quarter() returns 1-4\n- [ ] DayOfYear() returns 1-366\n- [ ] IsWeekend() returns true for Sat/Sun\n- [ ] IsLeapYear() returns true for leap years\n- [ ] Info() returns struct with all fields\n- [ ] ISO 8601 week compliance (Week 1 contains Thursday)\n- [ ] Leap year rules correct (4, 100, 400 rule)\n- [ ] Unit tests for all methods\n- [ ] Edge cases: year boundaries, week 53, leap years\n- [ ] Benchmarks meet \u003c1µs target\n- [ ] Godoc for each method with conventions documented","status":"open","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:06.966079923+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:06.966079923+01:00","dependencies":[{"issue_id":"quando-5ib","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:13.310800388+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-5ol","title":"Format presets and constants","description":"Implement preset format constants and Format() method.\n\n**API:**\n```go\ntype Format int\n\nconst (\n    ISO Format = iota     // \"2026-02-09\"\n    EU                    // \"09.02.2026\"\n    US                    // \"02/09/2026\"\n    Long                  // \"February 9, 2026\" (language-dependent)\n    RFC2822               // \"Mon, 09 Feb 2026 00:00:00 +0000\"\n)\n\nfunc (d Date) Format(format Format) string\n```\n\n**Language Dependency:**\n- ISO, EU, US, RFC2822: Always language-independent\n- Long: Uses Lang setting\n  - EN: \"February 9, 2026\"\n  - DE: \"9. Februar 2026\"\n\n**Implementation:**\n- Map Format constants to Go layout strings\n- Use Lang() setting for Long format\n- Delegate to time.Format() internally\n\n## Acceptance Criteria\n- [ ] Format type and constants defined\n- [ ] Format() method implemented\n- [ ] ISO format outputs \"YYYY-MM-DD\"\n- [ ] EU format outputs \"DD.MM.YYYY\"\n- [ ] US format outputs \"MM/DD/YYYY\"\n- [ ] RFC2822 format correct\n- [ ] Long format respects Lang setting (EN and DE)\n- [ ] Non-Long formats ignore Lang setting\n- [ ] Unit tests for all formats\n- [ ] Unit tests for Long with both EN and DE\n- [ ] Benchmark meets \u003c5µs without i18n, \u003c10µs with i18n\n- [ ] Godoc for each format constant\n- [ ] Example tests showing each format","status":"open","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:53.217816331+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:53.217816331+01:00","dependencies":[{"issue_id":"quando-5ol","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:12.164278602+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-5ol","depends_on_id":"quando-zbr","type":"blocks","created_at":"2026-02-11T16:23:12.20045666+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-6c3","title":"CI/CD pipeline setup","description":"Set up GitHub Actions CI/CD pipeline for automated testing and quality checks.\n\n**CI Workflow:**\n- Run on push and pull requests\n- Test on multiple Go versions (1.22, 1.23, latest)\n- Test on multiple platforms (Linux, macOS, Windows)\n- Run go fmt check\n- Run go vet\n- Run tests with coverage\n- Run benchmarks (informational)\n- Optional: golangci-lint\n\n**Coverage Reporting:**\n- Generate coverage report\n- Fail if coverage \u003c95% for core calculation functions\n- Optional: Upload to codecov.io or similar\n\n**Performance Monitoring:**\n- Run benchmarks on each commit\n- Report benchmark results (informational, no fail)\n\n## Acceptance Criteria\n- [ ] .github/workflows/ci.yml created\n- [ ] Tests run on push and PR\n- [ ] Multi-version Go support (1.22+)\n- [ ] Multi-platform support (Linux, macOS, Windows)\n- [ ] go fmt check passes\n- [ ] go vet check passes\n- [ ] Tests run with coverage report\n- [ ] Coverage requirement enforced (95%+)\n- [ ] Benchmarks run (informational)\n- [ ] CI badge in README (if applicable)","status":"open","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:51.928117055+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:51.928117055+01:00","dependencies":[{"issue_id":"quando-6c3","depends_on_id":"quando-r1o","type":"blocks","created_at":"2026-02-11T16:23:16.259739409+01:00","created_by":"Oliver Jakoubek"}]}
@@ -17,6 +17,6 @@
 {"id":"quando-ljj","title":"Duration type and Diff calculation","description":"Implement Duration type and Diff function for calculating differences between dates.\n\n**API:**\n```go\nfunc Diff(a, b time.Time) Duration\n\ntype Duration struct {\n    // private fields\n}\n\n// Integer methods (rounded down)\nfunc (dur Duration) Seconds() int64\nfunc (dur Duration) Minutes() int64\nfunc (dur Duration) Hours() int64\nfunc (dur Duration) Days() int\nfunc (dur Duration) Weeks() int\nfunc (dur Duration) Months() int\nfunc (dur Duration) Years() int\n\n// Float methods (precise)\nfunc (dur Duration) MonthsFloat() float64\nfunc (dur Duration) YearsFloat() float64\n```\n\n**Precision:**\n- Integer variants return rounded-down values\n- Float variants for precise calculations\n- Handle negative differences (date1 \u003c date2)\n- Cross year boundaries correctly\n- Handle leap years correctly\n\n## Acceptance Criteria\n- [ ] Duration type defined\n- [ ] Diff(a, b) returns Duration\n- [ ] All integer methods implemented (Seconds through Years)\n- [ ] Float methods for Months and Years implemented\n- [ ] Negative differences handled correctly\n- [ ] Calculations correct across year boundaries\n- [ ] Leap year handling correct\n- [ ] Unit tests with 95%+ coverage\n- [ ] Table-driven tests for various date ranges\n- [ ] Benchmarks meet \u003c1µs (int) and \u003c2µs (float) targets\n- [ ] Godoc comments with precision explanation","status":"open","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:06.159742785+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:06.159742785+01:00","dependencies":[{"issue_id":"quando-ljj","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:08.127266864+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-r1o","title":"Comprehensive test suite and benchmarks","description":"Ensure comprehensive test coverage (95%+) and performance benchmarks for all features.\n\n**Test Requirements:**\n- Minimum 95% coverage for all calculation functions\n- Table-driven tests for edge cases\n- Example tests for godoc\n- Separate benchmark file\n\n**Critical Test Scenarios:**\n1. Month arithmetic: Overflow, leap years, negative\n2. Snap operations: All units, edge cases\n3. Next/Prev: Same weekday edge case\n4. Diff calculations: Year boundaries, leap years, negative\n5. DST handling: Add across DST transitions\n6. Parsing: All formats, ambiguous, invalid\n7. WeekNumber: ISO 8601 compliance\n8. Formatting: All formats, i18n\n\n**Benchmarks:**\nTarget performance:\n- Add/Sub: \u003c1µs\n- Diff: \u003c1µs (int), \u003c2µs (float)\n- Format: \u003c5µs (no i18n), \u003c10µs (with i18n)\n- Parse: \u003c10µs (auto), \u003c20µs (relative)\n\n## Acceptance Criteria\n- [ ] Test coverage ≥95% for all calculation functions\n- [ ] Table-driven tests for all edge cases\n- [ ] Example tests in example_test.go\n- [ ] Benchmark file with all critical operations\n- [ ] All benchmarks meet performance targets\n- [ ] CI/CD runs tests and reports coverage\n- [ ] Tests use FixedClock for determinism\n- [ ] Edge cases documented in test names/comments","status":"open","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:22:38.100200304+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:22:38.100200304+01:00","dependencies":[{"issue_id":"quando-r1o","depends_on_id":"quando-b4r","type":"blocks","created_at":"2026-02-11T16:23:15.418358186+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-dsx","type":"blocks","created_at":"2026-02-11T16:23:15.474799177+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-9sf","type":"blocks","created_at":"2026-02-11T16:23:15.513811922+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-10t","type":"blocks","created_at":"2026-02-11T16:23:15.545561332+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-gr5","type":"blocks","created_at":"2026-02-11T16:23:15.578273993+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-5ol","type":"blocks","created_at":"2026-02-11T16:23:15.609031891+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-5ib","type":"blocks","created_at":"2026-02-11T16:23:15.640381484+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-r1o","depends_on_id":"quando-41g","type":"blocks","created_at":"2026-02-11T16:23:15.672161997+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-tn3","title":"Relative date parsing","description":"Implement ParseRelative for parsing relative date expressions.\n\n**API:**\n```go\nfunc ParseRelative(s string) (Date, error)\n```\n\n**Supported Expressions (Phase 1):**\n- \"today\" → Today 00:00:00\n- \"tomorrow\" → Tomorrow 00:00:00\n- \"yesterday\" → Yesterday 00:00:00\n- \"+2 days\" → Today + 2 days\n- \"-1 week\" → Today - 1 week\n- \"+3 months\" → Today + 3 months\n\n**Format:**\n- Relative offsets: [+|-]\u003cnumber\u003e \u003cunit\u003e\n- Units: day(s), week(s), month(s), quarter(s), year(s)\n- Singular and plural forms supported\n\n**Out of Scope (Phase 1):**\n- Complex expressions (\"next monday\", \"start of month\")\n- These are nice-to-have for later versions\n\n## Acceptance Criteria\n- [ ] ParseRelative() implemented\n- [ ] \"today\" returns today 00:00:00\n- [ ] \"tomorrow\" returns tomorrow 00:00:00\n- [ ] \"yesterday\" returns yesterday 00:00:00\n- [ ] \"+N \u003cunit\u003e\" adds N units to today\n- [ ] \"-N \u003cunit\u003e\" subtracts N units from today\n- [ ] Singular and plural units both work\n- [ ] All Phase 1 units supported (days, weeks, months, quarters, years)\n- [ ] Invalid expressions return clear errors\n- [ ] Never panics\n- [ ] Unit tests for all supported expressions\n- [ ] Unit tests for invalid inputs\n- [ ] Benchmark meets \u003c20µs target\n- [ ] Godoc with supported expressions listed\n- [ ] Note about future complex expressions","status":"open","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:40.790156181+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:40.790156181+01:00","dependencies":[{"issue_id":"quando-tn3","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:11.247985003+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-tn3","depends_on_id":"quando-36t","type":"blocks","created_at":"2026-02-11T16:23:11.278394998+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-tn3","depends_on_id":"quando-b4r","type":"blocks","created_at":"2026-02-11T16:23:11.309549914+01:00","created_by":"Oliver Jakoubek"}]}
-{"id":"quando-vih","title":"Clock abstraction for testability","description":"Implement Clock interface to enable dependency injection and deterministic testing.\n\n**Technical Details:**\n```go\ntype Clock interface {\n    Now() Date\n    From(t time.Time) Date\n}\n```\n\n**Implementations:**\n- DefaultClock: Uses time.Now()\n- FixedClock: Returns fixed time for tests\n\n**API:**\n- `NewClock()` - returns DefaultClock\n- `NewFixedClock(time.Time)` - returns FixedClock for tests\n\n## Acceptance Criteria\n- [ ] Clock interface defined\n- [ ] DefaultClock implementation using time.Now()\n- [ ] FixedClock implementation with fixed time\n- [ ] NewClock() factory function\n- [ ] NewFixedClock(time.Time) factory function\n- [ ] Unit tests demonstrating deterministic test patterns\n- [ ] Godoc comments\n- [ ] Example test showing test usage pattern","status":"in_progress","priority":0,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:20:33.357927572+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:31:38.756484443+01:00","dependencies":[{"issue_id":"quando-vih","depends_on_id":"quando-91w","type":"blocks","created_at":"2026-02-11T16:23:05.308383809+01:00","created_by":"Oliver Jakoubek"}],"comments":[{"id":3,"issue_id":"quando-vih","author":"Oliver Jakoubek","text":"Plan: 1) Create clock.go with Clock interface (Now, From methods), 2) Implement DefaultClock using time.Now(), 3) Implement FixedClock with fixed time for deterministic tests, 4) Add factory functions NewClock() and NewFixedClock(time.Time), 5) Write comprehensive unit tests demonstrating deterministic test patterns, 6) Add example tests showing test usage, 7) Ensure all exports have godoc comments","created_at":"2026-02-11T15:31:45Z"}]}
+{"id":"quando-vih","title":"Clock abstraction for testability","description":"Implement Clock interface to enable dependency injection and deterministic testing.\n\n**Technical Details:**\n```go\ntype Clock interface {\n    Now() Date\n    From(t time.Time) Date\n}\n```\n\n**Implementations:**\n- DefaultClock: Uses time.Now()\n- FixedClock: Returns fixed time for tests\n\n**API:**\n- `NewClock()` - returns DefaultClock\n- `NewFixedClock(time.Time)` - returns FixedClock for tests\n\n## Acceptance Criteria\n- [ ] Clock interface defined\n- [ ] DefaultClock implementation using time.Now()\n- [ ] FixedClock implementation with fixed time\n- [ ] NewClock() factory function\n- [ ] NewFixedClock(time.Time) factory function\n- [ ] Unit tests demonstrating deterministic test patterns\n- [ ] Godoc comments\n- [ ] Example test showing test usage pattern","status":"closed","priority":0,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:20:33.357927572+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:33:26.936900547+01:00","closed_at":"2026-02-11T16:33:26.936900547+01:00","close_reason":"Closed","dependencies":[{"issue_id":"quando-vih","depends_on_id":"quando-91w","type":"blocks","created_at":"2026-02-11T16:23:05.308383809+01:00","created_by":"Oliver Jakoubek"}],"comments":[{"id":3,"issue_id":"quando-vih","author":"Oliver Jakoubek","text":"Plan: 1) Create clock.go with Clock interface (Now, From methods), 2) Implement DefaultClock using time.Now(), 3) Implement FixedClock with fixed time for deterministic tests, 4) Add factory functions NewClock() and NewFixedClock(time.Time), 5) Write comprehensive unit tests demonstrating deterministic test patterns, 6) Add example tests showing test usage, 7) Ensure all exports have godoc comments","created_at":"2026-02-11T15:31:45Z"}]}
 {"id":"quando-wny","title":"Explicit parsing with layout","description":"Implement explicit parsing using Go's standard layout format.\n\n**API:**\n```go\nfunc ParseWithLayout(s, layout string) (Date, error)\n```\n\n**Purpose:**\nHandle ambiguous or custom formats by providing explicit layout\n\n**Examples:**\n```go\nParseWithLayout(\"01/02/2026\", \"02/01/2006\")  // EU format\nParseWithLayout(\"01/02/2026\", \"01/02/2006\")  // US format\nParseWithLayout(\"9. Februar 2026\", \"2. January 2006\")  // German custom\n```\n\n**Implementation:**\n- Delegate to time.Parse() with layout\n- Wrap result in quando.Date\n- Return clear errors for invalid inputs\n\n## Acceptance Criteria\n- [ ] ParseWithLayout() implemented\n- [ ] Uses Go's standard layout format (reference date)\n- [ ] Wraps time.Parse() correctly\n- [ ] Returns Date on success\n- [ ] Returns error on parse failure\n- [ ] Never panics\n- [ ] Unit tests for various layouts\n- [ ] Unit tests for invalid inputs\n- [ ] Benchmark meets \u003c10µs target\n- [ ] Godoc with Go layout format explanation\n- [ ] Example tests showing EU vs US disambiguation","status":"open","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:33.246073999+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:33.246073999+01:00","dependencies":[{"issue_id":"quando-wny","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:11.182490834+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"quando-wny","depends_on_id":"quando-36t","type":"blocks","created_at":"2026-02-11T16:23:11.216169487+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"quando-zbr","title":"Language constants and i18n infrastructure","description":"Define language constants and i18n infrastructure for multi-language support.\n\n**API:**\n```go\ntype Lang string\n\nconst (\n    LangEN Lang = \"en\"  // English (Default)\n    LangDE Lang = \"de\"  // Deutsch\n)\n\nfunc (d Date) Lang(lang Lang) Date  // Fluent API\n```\n\n**Phase 1 Languages:**\n- EN (English) - default\n- DE (Deutsch) - must-have\n\n**i18n Applies To:**\n- Format(Long) - \"February 9, 2026\" vs \"9. Februar 2026\"\n- Custom layouts with month/weekday names\n- Human() duration format\n\n**i18n Does NOT Apply To:**\n- ISO, EU, US, RFC2822 formats (always language-independent)\n- Numeric outputs (WeekNumber, Quarter, etc.)\n\n## Acceptance Criteria\n- [ ] Lang type defined as string\n- [ ] LangEN and LangDE constants defined\n- [ ] Lang() method on Date for fluent API\n- [ ] Month names in EN and DE\n- [ ] Weekday names in EN and DE\n- [ ] Time unit names for Human() in EN and DE\n- [ ] Unit tests for language switching\n- [ ] Godoc comments\n- [ ] Documentation noting future language expansion (21 more)","status":"open","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-02-11T16:21:19.72536676+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-02-11T16:21:19.72536676+01:00","dependencies":[{"issue_id":"quando-zbr","depends_on_id":"quando-j2s","type":"blocks","created_at":"2026-02-11T16:23:09.056424359+01:00","created_by":"Oliver Jakoubek"}]}

example_test.go

@@ -112,3 +112,38 @@ func ExampleFixedClock_deterministic() {
 	// Date 2: 2026-02-09 12:00:00
 	// Same: true
 }
+
+// ExampleUnit demonstrates the Unit type
+func ExampleUnit() {
+	// Units are used with Add, Sub, StartOf, EndOf operations
+	units := []quando.Unit{
+		quando.Seconds,
+		quando.Minutes,
+		quando.Hours,
+		quando.Days,
+		quando.Weeks,
+		quando.Months,
+		quando.Quarters,
+		quando.Years,
+	}
+
+	for _, u := range units {
+		fmt.Println(u.String())
+	}
+	// Output:
+	// seconds
+	// minutes
+	// hours
+	// days
+	// weeks
+	// months
+	// quarters
+	// years
+}
+
+// ExampleUnit_String demonstrates the String method
+func ExampleUnit_String() {
+	unit := quando.Days
+	fmt.Printf("Unit: %s\n", unit)
+	// Output: Unit: days
+}

unit.go

@@ -0,0 +1,57 @@
+package quando
+
+// Unit represents a time unit for arithmetic operations like Add and Sub,
+// and for snap operations like StartOf and EndOf.
+//
+// Use the predefined constants (Seconds, Minutes, Hours, Days, Weeks, Months,
+// Quarters, Years) rather than creating Unit values directly.
+type Unit int
+
+// Time unit constants for use with arithmetic and snap operations.
+// These constants are ordered from smallest to largest unit, except for Quarters
+// which is a special alias for 3 months.
+const (
+	// Seconds represents the seconds time unit.
+	Seconds Unit = iota
+	// Minutes represents the minutes time unit.
+	Minutes
+	// Hours represents the hours time unit.
+	Hours
+	// Days represents the days time unit.
+	// When used with Add, this means calendar days (not 24-hour periods).
+	Days
+	// Weeks represents the weeks time unit (7 days).
+	Weeks
+	// Months represents the months time unit.
+	// Adding months handles month-end overflow (e.g., Jan 31 + 1 month = Feb 28).
+	Months
+	// Quarters represents the quarters time unit (3 months).
+	Quarters
+	// Years represents the years time unit.
+	Years
+)
+
+// String returns the string representation of the Unit.
+// This is primarily useful for debugging and error messages.
+func (u Unit) String() string {
+	switch u {
+	case Seconds:
+		return "seconds"
+	case Minutes:
+		return "minutes"
+	case Hours:
+		return "hours"
+	case Days:
+		return "days"
+	case Weeks:
+		return "weeks"
+	case Months:
+		return "months"
+	case Quarters:
+		return "quarters"
+	case Years:
+		return "years"
+	default:
+		return "unknown"
+	}
+}

unit_test.go

@@ -0,0 +1,147 @@
+package quando
+
+import (
+	"testing"
+)
+
+func TestUnitConstants(t *testing.T) {
+	// Verify that all constants are defined and have expected values
+	tests := []struct {
+		name     string
+		unit     Unit
+		expected int
+		str      string
+	}{
+		{"Seconds", Seconds, 0, "seconds"},
+		{"Minutes", Minutes, 1, "minutes"},
+		{"Hours", Hours, 2, "hours"},
+		{"Days", Days, 3, "days"},
+		{"Weeks", Weeks, 4, "weeks"},
+		{"Months", Months, 5, "months"},
+		{"Quarters", Quarters, 6, "quarters"},
+		{"Years", Years, 7, "years"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Verify the numeric value
+			if int(tt.unit) != tt.expected {
+				t.Errorf("%s = %d, want %d", tt.name, int(tt.unit), tt.expected)
+			}
+
+			// Verify the string representation
+			if tt.unit.String() != tt.str {
+				t.Errorf("%s.String() = %q, want %q", tt.name, tt.unit.String(), tt.str)
+			}
+		})
+	}
+}
+
+func TestUnitOrdering(t *testing.T) {
+	// Verify that units are ordered from smallest to largest (except Quarters)
+	if Seconds >= Minutes {
+		t.Error("Seconds should be < Minutes")
+	}
+	if Minutes >= Hours {
+		t.Error("Minutes should be < Hours")
+	}
+	if Hours >= Days {
+		t.Error("Hours should be < Days")
+	}
+	if Days >= Weeks {
+		t.Error("Days should be < Weeks")
+	}
+	if Weeks >= Months {
+		t.Error("Weeks should be < Months")
+	}
+	if Months >= Quarters {
+		t.Error("Months should be < Quarters")
+	}
+	if Quarters >= Years {
+		t.Error("Quarters should be < Years")
+	}
+}
+
+func TestUnitString(t *testing.T) {
+	tests := []struct {
+		name     string
+		unit     Unit
+		expected string
+	}{
+		{"Seconds", Seconds, "seconds"},
+		{"Minutes", Minutes, "minutes"},
+		{"Hours", Hours, "hours"},
+		{"Days", Days, "days"},
+		{"Weeks", Weeks, "weeks"},
+		{"Months", Months, "months"},
+		{"Quarters", Quarters, "quarters"},
+		{"Years", Years, "years"},
+		{"Unknown", Unit(999), "unknown"},
+		{"Negative", Unit(-1), "unknown"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := tt.unit.String()
+			if result != tt.expected {
+				t.Errorf("Unit(%d).String() = %q, want %q", tt.unit, result, tt.expected)
+			}
+		})
+	}
+}
+
+// TestUnitTypeSafety verifies that Unit provides compile-time type safety
+func TestUnitTypeSafety(t *testing.T) {
+	// This test primarily exists to demonstrate type safety at compile time
+	// If this compiles, the type safety is working
+
+	var u Unit
+	u = Seconds
+	u = Minutes
+	u = Hours
+	u = Days
+	u = Weeks
+	u = Months
+	u = Quarters
+	u = Years
+
+	// Verify last assignment worked
+	if u != Years {
+		t.Error("Type safety test failed")
+	}
+}
+
+// TestUnitComparability verifies that Units can be compared
+func TestUnitComparability(t *testing.T) {
+	if Seconds == Minutes {
+		t.Error("Seconds should not equal Minutes")
+	}
+	if Seconds == Seconds {
+		// This should be true
+	} else {
+		t.Error("Seconds should equal itself")
+	}
+
+	// Test in switch statement (common usage pattern)
+	u := Days
+	switch u {
+	case Seconds, Minutes, Hours:
+		t.Error("Days matched wrong case")
+	case Days:
+		// Expected
+	case Weeks, Months, Quarters, Years:
+		t.Error("Days matched wrong case")
+	default:
+		t.Error("Days didn't match any case")
+	}
+}
+
+// BenchmarkUnitString benchmarks the String() method
+func BenchmarkUnitString(b *testing.B) {
+	units := []Unit{Seconds, Minutes, Hours, Days, Weeks, Months, Quarters, Years}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		u := units[i%len(units)]
+		_ = u.String()
+	}
+}