@northguild/gmt 1.14.2 → 1.16.0

package/skills/interval-ops/SKILL.md

@@ -1,432 +0,0 @@
----
-name: interval-ops
-description: >
-  Interval and range math over ISO datetime/zoned/unix strings. Use
-  isValid*Interval to validate start/end pairs, intervalContains* for
-  point-or-interval containment, intervalsOverlap* for overlap booleans,
-  intervalIntersection*/intervalUnion* for set-theoretic combine/difference
-  returning { start, end } | null, intervalDifference*/intervalXor*/
-  intervalAbuts*/intervalEngulfs* for set operations, intervalFromDuration* to
-  build an interval from a point plus an ISO 8601 duration, splitIntervalByUnit*
-  to tile an interval by duration unit, intervalCount* for calendar-unit
-  boundaries crossed, intervalLength* for exact fractional duration in a unit,
-  intervalDivideEqually* to split into n equal parts, intervalSplitAt* to split
-  at arbitrary points, mergeIntervals*/intervalXorAll* as list-form
-  generalizations of intervalUnion*/intervalXor*, and intervalOverlappingDays*
-  for shared calendar dates between two intervals. Covers plain, zoned, unix,
-  utc. Returns false/null/[] on invalid input — never throws.
-sources:
-  - 'northguild/gmt:packages/gmt/src/plain/interval/index.ts'
-  - 'northguild/gmt:packages/gmt/src/zoned/interval/index.ts'
-  - 'northguild/gmt:packages/gmt/src/unix/interval/index.ts'
-  - 'northguild/gmt:packages/gmt/src/utc/interval/index.ts'
-  - 'northguild/gmt:packages/gmt/src/duration/validate/isValidDuration.ts'
-metadata:
-  type: core
-  library: '@northguild/gmt'
-  library_version: '1.14.2'
----
-
-# Interval Operations
-
-Use this skill when working with two-point ranges (start/end pairs) across plain, zoned, unix, or UTC values.
-
-## Setup
-
-```ts
-import {
-  isValidDateInterval,
-  intervalContainsDate,
-  intervalsOverlapDate,
-  intervalIntersectionDate,
-  intervalUnionDate,
-  intervalDifferenceDate,
-  intervalXorDate,
-  intervalAbutsDate,
-  intervalEngulfsDate,
-  intervalFromDurationDate,
-  splitIntervalByUnitDate,
-  intervalCountDate,
-  intervalLengthDate,
-  intervalDivideEquallyDate,
-  intervalSplitAtDate,
-  mergeIntervalsDate,
-  intervalXorAllDate,
-  intervalOverlappingDaysDate,
-} from "@northguild/gmt";
-```
-
-Every function has `Time`, `DateTime`, `Zoned`, `Unix`, and `Utc` siblings. Replace the suffix to match your value type.
-
-## Function Reference
-
-| Family | Signature | Returns | Invalid |
-| --- | --- | --- | --- |
-| `isValid*Interval` | `(start, end)` | `boolean` | `false` |
-| `intervalContains*` | `(start, end, pointOrInnerStart, innerEnd?)` | `boolean` | `false` |
-| `intervalsOverlap*` | `(aStart, aEnd, bStart, bEnd)` | `boolean` | `false` |
-| `intervalIntersection*` | `(aStart, aEnd, bStart, bEnd)` | `{ start, end } \| null` | `null` |
-| `intervalUnion*` | `(aStart, aEnd, bStart, bEnd)` | `{ start, end } \| null` | `null` |
-| `intervalDifference*` | `(aStart, aEnd, bStart, bEnd)` | `Array<{ start, end }>` | `[]` |
-| `intervalXor*` | `(aStart, aEnd, bStart, bEnd)` | `Array<{ start, end }>` | `[]` |
-| `intervalAbuts*` | `(aStart, aEnd, bStart, bEnd)` | `boolean` | `false` |
-| `intervalEngulfs*` | `(aStart, aEnd, bStart, bEnd)` | `boolean` | `false` |
-| `intervalFromDuration*` | `(value, duration, anchor, options?)` | `{ start, end } \| null` | `null` |
-| `splitIntervalByUnit*` | `(start, end, unit, amount)` | `Array<{ start, end }>` | `[]` |
-| `intervalCount*` | `(start, end, unit)` | `number \| null` | `null` |
-| `intervalLength*` | `(start, end, unit)` | `number \| null` (fractional) | `null` |
-| `intervalDivideEqually*` | `(start, end, n)` | `Array<{ start, end }>` | `[]` |
-| `intervalSplitAt*` | `(start, end, points)` | `Array<{ start, end }>` | `[]` |
-| `mergeIntervals*` | `(intervals: Array<{ start, end }>)` | `Array<{ start, end }>` | `[]` |
-| `intervalXorAll*` | `(intervals: Array<{ start, end }>)` | `Array<{ start, end }>` | `[]` |
-| `intervalOverlappingDays*` | `(aStart, aEnd, bStart, bEnd)` — `Unix` variant takes a 5th `options?: { epochUnit?, timeZone? }` | `number \| null` | `null` (`0` when disjoint) |
-
-`intervalOverlappingDays*` has no `Time` sibling — `PlainTime` has no calendar, so a day count is undefined for it.
-
-`intervalContains*` supports two modes:
-- 3-arg: `intervalContains(start, end, point)` — point-in-interval
-- 4-arg: `intervalContains(start, end, innerStart, innerEnd)` — interval-in-interval
-
-`intervalEngulfs*` is equivalent to `intervalContains*`'s 4-argument mode.
-
-## Core Patterns
-
-### Validate an interval
-
-```ts
-isValidDateInterval("2024-01-01", "2024-12-31"); // true
-isValidDateInterval("2024-12-31", "2024-01-01"); // false (inverted)
-isValidDateInterval("invalid", "2024-12-31");    // false
-```
-
-### Point inside interval
-
-```ts
-intervalContainsDate("2024-01-01", "2024-12-31", "2024-06-15"); // true
-intervalContainsTime("09:00:00", "17:00:00", "12:00:00");       // true
-```
-
-### Interval inside interval
-
-```ts
-intervalContainsDate("2024-01-01", "2024-12-31", "2024-03-01", "2024-09-01"); // true
-```
-
-### Overlap vs adjacency
-
-`intervalsOverlap*` returns `true` only when intervals share actual time. Adjacent intervals (one's end equals the other's start) do **not** overlap:
-
-```ts
-intervalsOverlapDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31"); // true
-intervalsOverlapDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31"); // false
-```
-
-`intervalAbuts*` is the complementary check — `true` only when intervals touch at exactly one boundary with zero gap and zero overlap:
-
-```ts
-intervalAbutsDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31"); // true
-intervalAbutsDate("2024-01-01", "2024-06-29", "2024-06-30", "2024-12-31"); // false (gap)
-intervalAbutsDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31"); // false (overlap)
-```
-
-### Intersection and union
-
-```ts
-intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
-// { start: "2024-04-01", end: "2024-06-30" }
-
-intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31");
-// null (disjoint)
-
-intervalUnionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
-// { start: "2024-01-01", end: "2024-12-31" }
-
-intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31");
-// null (disjoint with gap)
-```
-
-Adjacent intervals count as overlapping for intersection and as mergeable for union.
-
-### Set difference and symmetric difference
-
-```ts
-intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01");
-// [{ start: "2024-01-01", end: "2024-05-31" }, { start: "2024-07-02", end: "2024-12-31" }]
-
-intervalXorDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
-// [{ start: "2024-01-01", end: "2024-03-31" }, { start: "2024-07-01", end: "2024-12-31" }]
-```
-
-Both return `[]` when B fully covers A or on invalid input.
-
-### Construct an interval from a point + duration
-
-`intervalFromDuration*` builds an interval from a single point and an ISO 8601 duration string, anchored at either end — Luxon's `Interval.after`/`Interval.before` as one function with an `anchor` param:
-
-```ts
-intervalFromDurationDate("2024-01-01", "P1M", "start");
-// { start: "2024-01-01", end: "2024-02-01" }
-
-intervalFromDurationDate("2024-02-01", "P1M", "end");
-// { start: "2024-01-01", end: "2024-02-01" }
-
-intervalFromDurationZoned(
-  "2024-03-09T02:30:00-05:00[America/New_York]",
-  "P1D",
-  "start",
-);
-// { start: "2024-03-09T02:30:00-05:00[America/New_York]", end: "2024-03-10T03:30:00-04:00[America/New_York]" }
-```
-
-Calendar units (years/months/weeks) resolve against `value` itself via Temporal's `add()`/`subtract()` — no separate `relativeTo` is needed. `intervalFromDurationZoned` accepts the same `disambiguation`/`offset`/`overflow` options as `addZoned`; `intervalFromDurationUnix` accepts `addUnix`'s `epochUnit`/`timeZone`/`overflow` options. A negative `duration` that inverts the computed span returns `null`, same as any other invalid input.
-
-`intervalFromDurationTime` is the one exception: `PlainTime` has no calendar, so a `duration` with a nonzero years/months/weeks/days component returns `null` rather than silently ignoring those fields:
-
-```ts
-intervalFromDurationTime("12:00:00", "PT1H", "start"); // { start: "12:00:00", end: "13:00:00" }
-intervalFromDurationTime("12:00:00", "P1D", "start");  // null (date units need relativeTo, unsupported)
-```
-
-### Split by duration unit
-
-```ts
-splitIntervalByUnitDate("2024-01-01", "2024-01-10", "day", 2);
-// [{ start: "2024-01-01", end: "2024-01-03" }, ..., { start: "2024-01-09", end: "2024-01-10" }]
-```
-
-The final slice is trimmed so its `end` never exceeds the original `end`.
-
-### Count unit boundaries crossed
-
-```ts
-intervalCountDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day");
-// 2 — two minutes long, but it crosses a day boundary
-
-intervalCountDate("2024-01-01", "2024-01-03", "day"); // 2 (end boundary excluded)
-intervalCountDate("2024-01-15", "2024-03-10", "month"); // 3
-```
-
-This is calendar-boundary counting, not duration. Use `diff*` when you want exact elapsed time.
-
-### Exact interval length vs boundary count
-
-`intervalLength*` answers "how long is this interval" as a real, possibly fractional number — `intervalCount*` answers "how many `unit` boundaries does it touch". They read as synonyms but are not:
-
-```ts
-intervalCountDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day");
-// 2 — touches 2 day boundaries
-
-intervalLengthDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day");
-// 0.001388888888888889 — the interval is only ~2 minutes long
-```
-
-`intervalLength*` uses `Duration.prototype.total`, so calendar units (month, year) resolve against the interval's own `start` rather than truncating: `intervalLengthDate("2024-01-01", "2024-01-16", "month")` is `15/31`, not `0`. `intervalLengthZoned`/`intervalLengthUnix`/`intervalLengthUtc` are DST-aware the same way `intervalCountZoned` is — a spring-forward day is `23` hours via `intervalLengthZoned(..., "hour")` but exactly `1` via `intervalLengthZoned(..., "day")`.
-
-### Split an interval into n equal parts
-
-```ts
-intervalDivideEquallyDate("2024-01-01", "2024-01-05", 4);
-// [{ start: "2024-01-01", end: "2024-01-02" }, ..., { start: "2024-01-04", end: "2024-01-05" }]
-```
-
-`n` must be a positive integer (`n <= 0` or non-integer returns `[]`). `n === 1` returns the original interval as a single-element array. A zero-length interval returns `n` identical zero-length sub-intervals. `PlainDate` has no fractional-day representation, so `intervalDivideEquallyDate` rounds internal boundaries to the nearest whole day when the total doesn't divide evenly by `n`; every other variant computes boundaries from total elapsed nanoseconds and is exact (`intervalDivideEquallyZoned` splits by real elapsed time, so a DST-crossing interval's midpoint lands on the real midpoint, not the local-clock midpoint).
-
-### Split an interval at arbitrary points
-
-```ts
-intervalSplitAtDate("2024-01-01", "2024-01-10", ["2024-01-07", "2024-01-03"]);
-// [{ start: "2024-01-01", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-10" }]
-```
-
-Points need not be sorted — `intervalSplitAt*` sorts them internally. Points outside `[start, end]` or exactly on a boundary are dropped (they cannot introduce a new sub-interval). An empty `points` array, or one containing only out-of-range/duplicate points, returns `[{ start, end }]` — the whole interval, unsplit.
-
-### Merge and XOR a list of intervals
-
-`mergeIntervals*` and `intervalXorAll*` are the list-form generalizations of `intervalUnion*` and `intervalXor*`, which are pairwise only:
-
-```ts
-mergeIntervalsDate([
-  { start: "2024-01-01", end: "2024-01-10" },
-  { start: "2024-01-05", end: "2024-01-15" },
-  { start: "2024-02-01", end: "2024-02-05" },
-]);
-// [{ start: "2024-01-01", end: "2024-01-15" }, { start: "2024-02-01", end: "2024-02-05" }]
-
-intervalXorAllDate([
-  { start: "2024-01-01", end: "2024-01-10" },
-  { start: "2024-01-05", end: "2024-01-15" },
-  { start: "2024-01-08", end: "2024-01-20" },
-]);
-// [{ start: "2024-01-01", end: "2024-01-04" }, { start: "2024-01-08", end: "2024-01-10" }, { start: "2024-01-16", end: "2024-01-20" }]
-```
-
-Both take a single array of `{ start, end }` records (order doesn't matter) instead of two flat 4-arg intervals. `mergeIntervals*` collapses overlapping/adjacent intervals into the minimum non-overlapping set. `intervalXorAll*` returns the set covered by an odd number of the input intervals — two identical intervals cancel out to `[]`, and for exactly two intervals the result is identical to the pairwise `intervalXor*`.
-
-### Count shared days between two intervals
-
-`intervalOverlappingDays*` is the numeric counterpart to `intervalIntersection*` — how many distinct calendar dates the two intervals' closed intersection touches, inclusive of both endpoints:
-
-```ts
-intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31");
-// 91
-
-intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31");
-// 1 (adjacent, shares one date)
-
-intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31");
-// 0 (disjoint — a well-defined answer, not invalid input)
-
-intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" });
-// 2
-```
-
-`intervalOverlappingDaysZoned` and `intervalOverlappingDaysUnix` count days in `aStart`'s zone (`intervalOverlappingDaysUnix` defaults to the system zone, overridable via `{ timeZone }`), same rule as `intervalCountZoned`/`intervalCountUnix` — so `intervalOverlappingDaysZoned` is not commutative when the two intervals carry different zones.
-
-## Return Conventions
-
-- `boolean` families (`isValid*Interval`, `intervalContains*`, `intervalsOverlap*`, `intervalAbuts*`, `intervalEngulfs*`): `false` on invalid input.
-- Object families (`intervalIntersection*`, `intervalUnion*`, `intervalFromDuration*`): `null` on no-result or invalid input.
-- Array families (`intervalDifference*`, `intervalXor*`, `splitIntervalByUnit*`, `intervalDivideEqually*`, `intervalSplitAt*`, `mergeIntervals*`, `intervalXorAll*`): `[]` on no-result or invalid input.
-- Number families (`intervalCount*`, `intervalLength*`, `intervalOverlappingDays*`): `null` on invalid input; `intervalOverlappingDays*` additionally returns `0` for a disjoint pair (not invalid — a well-defined "zero shared days").
-
-Never throws. Wrap in try-catch only if you need to distinguish "invalid input" from other errors.
-
-## Namespace selection
-
-- `plain/*` — timezone-free dates, times, or datetimes.
-- `zoned/*` — IANA-timezone-aware strings (`"2024-01-01T00:00:00+00:00[UTC]"`). Rejects any `[u-ca=...]` calendar annotation (E5) — calendar-system awareness is `plain/`-only.
-- `unix/*` — epoch-second numbers (returns arrays of numbers, not strings).
-- `utc/*` — UTC instants (`"2024-01-01T00:00:00Z"`).
-
-## Calendar-aware `Date` intervals (E5)
-
-Every `Date`-suffixed function in this namespace (`intervalContainsDate`, `intervalUnionDate`, `intervalCountDate`, `splitIntervalByUnitDate`, and the rest) accepts a GMT calendar-annotated `PlainDate` string (as produced by `convertDateToCalendar`), not just bare ISO strings. The policy differs by return family:
-
-- **Ordering/count families accept mixed calendars** — `intervalContains*`, `intervalsOverlap*`, `intervalAbuts*`, `intervalEngulfs*`, `isValidDateInterval`, `intervalOverlappingDaysDate` compare or count regardless of which calendar each argument is tagged with, since ordering and day-counting are calendar-independent.
-- **Value-returning families require all arguments to share one calendar** — `intervalUnion*`, `intervalIntersection*`, `intervalDifference*`, `intervalXor*`, `intervalXorAll*`, `mergeIntervals*`, `intervalDivideEqually*`, `intervalSplitAt*` return their sentinel (`null`/`[]`) on a calendar mismatch, since there's no principled output calendar to pick for a returned date value.
-- **Calendar-unit arithmetic families measure in the shared calendar, falling back to Gregorian on a mismatch** — `intervalCountDate`, `intervalLengthDate`, `splitIntervalByUnitDate`, `intervalFromDurationDate`. A Hebrew leap year crosses **13** month boundaries, not 12:
-
-```ts
-import { intervalCountDate, splitIntervalByUnitDate } from "@northguild/gmt";
-
-intervalCountDate(
-  "5784-01-01[u-ca=hebrew]",
-  "5785-01-01[u-ca=hebrew]",
-  "month",
-); // 13, not 12 — Hebrew leap years insert Adar I
-
-splitIntervalByUnitDate(
-  "5784-01-01[u-ca=hebrew]",
-  "5785-01-01[u-ca=hebrew]",
-  "month",
-  1,
-).length; // 13 slices, each a real Hebrew month
-```
-
-`*DateTime`/`*Time`/`unix/*`/`utc/*` intervals are unaffected — no calendar-annotated `PlainDateTime` grammar exists, and `PlainTime` has no calendar. See `packages/gmt/README.md`'s "Calendar-aware interval and duration arithmetic" and `context/roadmap/issues/E.md`'s E5 outcome for the full per-function audit.
-
-## Common Mistakes
-
-### Mixing calendar systems across interval endpoints
-
-Both `plain/` and `zoned/` interval families split by return type:
-
-- **Ordering / counting functions accept mixed calendars** — `intervalContains*`,
-  `intervalsOverlap*`, `intervalAbuts*`, `intervalEngulfs*`, `intervalOverlappingDays*`,
-  `isValidDateInterval` / `isValidCalendarZonedInterval`. Ordering does not depend on calendar.
-- **Value-returning set operations reject a mismatch** — `intervalUnion*`, `intervalIntersection*`,
-  `intervalDifference*`, `intervalXor*`, `intervalXorAll*`, `mergeIntervals*`,
-  `intervalDivideEqually*`, `intervalSplitAt*` return their sentinel (`null`/`[]`) unless every
-  endpoint names the same calendar. There is no principled output calendar to pick, and four of
-  them return arrays whose elements would otherwise disagree.
-- **Measurement functions fall back to Gregorian** — `intervalCount*`, `intervalLength*`,
-  `splitIntervalByUnit*` measure in the shared calendar when both tags match, else in
-  Gregorian/ISO. They do **not** return the sentinel on a mismatch.
-
-For `zoned/`, use `isValidCalendarZonedInterval` (not `isValidZonedInterval`, which still rejects
-every `[u-ca=...]` annotation).
-
-### Building a calendar-annotated zoned string by hand
-
-GMT's zoned calendar grammar puts `[u-ca=...]` **before** `[timeZone]` — the reverse of RFC 9557
-and of Temporal's own `toString()`:
-
-```
-5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]   // correct
-5784-06-15T14:30:00-05:00[America/New_York][u-ca=hebrew]   // WRONG — silently misparses in Temporal
-```
-
-Always produce these with `convertZonedToCalendar`, never by concatenation. See the
-`zoned-date-ops` skill's Common Mistakes for the full trap.
-
-### HIGH: Confusing `intervalsOverlap` with `intervalAbuts`
-
-Adjacent intervals (A ends where B starts) do **not** overlap. `intervalsOverlap` returns `false`; `intervalAbuts` returns `true`. They are complementary, not interchangeable.
-
-### HIGH: Assuming `intervalEngulfs` is new logic
-
-`intervalEngulfs(start, end, innerStart, innerEnd)` is identical to `intervalContains(start, end, innerStart, innerEnd)` with 4 arguments. Use whichever name reads better at the call site — do not implement duplicate logic.
-
-### MEDIUM: Mutating intersection/union results
-
-`intervalIntersection*` / `intervalUnion*` return plain `{ start, end }` records. Mutating them does not affect the original intervals (which are string inputs, not objects). Safe to treat as immutable.
-
-### MEDIUM: Off-by-one on `splitIntervalByUnit` final slice
-
-The last sub-interval's `end` is **trimmed** to the original `end`, not advanced by `amount × unit`. Do not assume all slices have equal length.
-
-### HIGH: Using `intervalCount` where you meant a duration
-
-`intervalCount*` counts calendar-unit boundaries the half-open interval `[start, end)` touches, not
-elapsed time. `intervalCountDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day")` is `2`
-for a two-minute interval. Use `diffDateTime`/`diffUnix`/etc. for exact duration.
-
-### MEDIUM: Expecting a zero-length interval to count 1
-
-A zero-length interval counts `1` only when it sits mid-unit. Exactly on a boundary it counts `0` —
-`intervalCountDate("2024-01-01", "2024-01-01", "month")` is `0`, while
-`intervalCountDate("2024-01-15", "2024-01-15", "month")` is `1`.
-
-### LOW: Using `intervalContains` 3-arg for intervals
-
-`intervalContains(start, end, innerStart)` treats the third arg as a single point. To test interval-in-interval, pass all four arguments.
-
-### HIGH: Assuming `intervalFromDurationTime` applies a calendar-unit duration
-
-`Temporal.PlainTime.prototype.add`/`.subtract` silently discard `years`/`months`/`weeks`/`days` fields rather than throwing — `intervalFromDurationTime` guards this explicitly and returns `null` instead of producing a misleadingly zero-length interval. Only `PlainTime` has this restriction; `Date`/`DateTime`/`Utc`/`Unix`/`Zoned` all resolve calendar units against the point itself with no `relativeTo` needed.
-
-### MEDIUM: Forgetting a negative `duration` can invert the span
-
-`intervalFromDuration*("2024-01-05", "-P10D", "start")` computes an end before the start and returns `null`, same as any other invalid input — it does not swap the endpoints for you.
-
-### HIGH: Expecting date-fns's `getOverlappingDaysInIntervals` number from `intervalOverlappingDays*`
-
-date-fns's `getOverlappingDaysInIntervals` rounds up elapsed 24-hour periods; GMT's `intervalOverlappingDays*` counts inclusive calendar dates instead — they disagree at every exact-day boundary. date-fns's own doc example:
-
-```ts
-// date-fns: getOverlappingDaysInIntervals(Jan 10–20, Jan 17–21) → 3
-intervalOverlappingDaysDate("2014-01-10", "2014-01-20", "2014-01-17", "2014-01-21");
-// 4 — not 3
-```
-
-To reproduce date-fns's number exactly, compose `intervalIntersection*` with `intervalCount*` instead:
-
-```ts
-const span = intervalIntersectionDate(aStart, aEnd, bStart, bEnd);
-span ? intervalCountDate(span.start, span.end, "day") : 0; // date-fns semantics
-```
-
-### HIGH: Confusing `intervalLength` with `intervalCount`
-
-Same trap as above, one level deeper: `intervalLength*` and `intervalCount*` read as synonyms but answer different questions. The same interval returns different numbers from each:
-
-```ts
-intervalCountDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day");  // 2  — boundaries crossed
-intervalLengthDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day"); // 0.0014 — exact elapsed duration
-```
-
-Use `intervalCount*` for "how many `unit`s does this span touch" (calendar-boundary counting) and `intervalLength*` for "how long is this, expressed in `unit`" (exact, possibly fractional duration).
-
-### MEDIUM: Expecting `intervalXorAll`/`mergeIntervals` to take flat arguments like their pairwise siblings
-
-`intervalXor*`/`intervalUnion*` take four flat string/number arguments (`aStart, aEnd, bStart, bEnd`). Their list-form generalizations `intervalXorAll*`/`mergeIntervals*` take one array of `{ start, end }` records instead, since the list can be any length. Passing flat arguments to the list form is a type error, not a runtime sentinel.

package/skills/issue-creation/SKILL.md

@@ -1,118 +0,0 @@
----
-name: issue-creation
-description: >
-  Create feature requests for missing @northguild/gmt functionality with proper
-  context, examples, and details that help maintainers understand and implement
-  the requested feature.
-metadata:
-  library_version: 1.14.2
----
-
-# Issue Creation
-
-Use this skill when a user needs functionality that gmt does not currently provide.
-
-## When to Create an Issue
-
-- A needed date/time operation is not available in gmt
-- Existing gmt methods don't handle a specific edge case
-- Documentation is unclear and causes confusion
-- A bug is found in existing functionality
-
-## Required Issue Details
-
-### 1. Problem Statement
-
-Describe what you're trying to accomplish:
-
-```
-I need to [specific task] but gmt doesn't support this.
-Current workaround: [what you currently do]
-```
-
-### 2. Expected Behavior
-
-Show what you expect:
-
-```js
-// Input
-"2024-03-15"
-
-// Expected output
-"Q1 2024"
-```
-
-### 3. Plain vs Zoned
-
-Clarify timezone requirements:
-
-- **Plain** (timezone-free): Operations that work regardless of timezone
-- **Zoned** (timezone-aware): Operations in a specific IANA timezone
-
-### 4. Invalid Input Handling
-
-Specify what should happen with invalid inputs:
-
-- String return: `""` (empty string)
-- Number return: `null`
-- Boolean return: `false`
-
-### 5. Locale Requirements
-
-If locale affects output, specify which locales need support.
-
-## Issue Template
-
-```markdown
-## Problem
-[What you need but gmt doesn't provide]
-
-## Expected Behavior
-[Code example showing input and expected output]
-
-## Plain or Zoned?
-[Does this need timezone awareness?]
-
-## Invalid Input
-[What should happen with invalid inputs?]
-
-## Use Case
-[Why do you need this? What's the business context?]
-```
-
-## Example Issues
-
-### Good Issue
-
-```markdown
-## Problem
-I need to get the ISO week number from a date string.
-
-## Expected Behavior
-getWeekOfYear("2024-01-01") // returns 1
-getWeekOfYear("2024-12-31") // returns 1 (ISO weeks start Monday)
-
-## Plain or Zoned?
-Plain (no timezone needed)
-
-## Invalid Input
-Return null on invalid input
-```
-
-### What to Avoid
-
-- "Add date formatting" (too vague)
-- "Add support for [framework]" (gmt is framework-agnostic)
-- "It's broken" (no reproduction steps)
-
-## After Creating
-
-1. Check for duplicate issues first
-2. Add to existing issue if duplicates found
-3. Monitor the issue for maintainer responses
-4. Be ready to provide additional context
-
-## Related Skills
-
-- **pr-contribution**: If you want to implement the feature yourself
-- **new-method-implementation**: For maintainer guidance on implementation

package/skills/lint-package-suggestion/SKILL.md

@@ -1,37 +0,0 @@
----
-name: lint-package-suggestion
-description: >
-  Recommend the right @northguild lint package(s) from the repository toolchain
-  (ESLint, Biome, Oxlint), and suggest adding @northguild/gmt when lint-only
-  setups need safe Date-to-Temporal refactor helpers.
-metadata:
-  library_version: 1.14.2
----
-
-# Lint Package Suggestion
-
-Use this skill when working in a project that already uses `@northguild/gmt` or is adopting it.
-
-## Decision policy
-
-1. Detect current lint stack
-- If project uses ESLint, suggest `@northguild/gmt-eslint`.
- - If project uses Biome, suggest `@northguild/gmt-biome` (or suggest selecting individual plugins via `@northguild/gmt-biome/plugins/<name>` when only a subset of rules is desired). Both `.../<name>` and `.../<name>.grit` forms are supported; prefer the extensionless form.
-- If project uses Oxlint, suggest `@northguild/gmt-oxlint`.
-
-2. Respect developer choice
-- These packages can be used individually or together.
-- Do not force all tools; recommend what matches current tooling.
-
-3. Runtime + lint bridge
-- If a project has a gmt lint package but not `@northguild/gmt`, suggest installing `@northguild/gmt` to support safe Date-to-Temporal refactors.
-
-4. Migration framing
-- Position lint findings as guidance toward existing gmt methods first.
-- If no gmt helper exists for a violation pattern, explain Temporal custom method path and suggest opening a GitHub issue.
-
-## Recommendation examples
-
-- ESLint repo + gmt runtime: suggest `@northguild/gmt-eslint`.
-- Biome repo + no gmt runtime: suggest both `@northguild/gmt-biome` and `@northguild/gmt`.
-- Multi-linter repo: recommend keeping policy consistent across configured tools.

package/skills/new-method-implementation/SKILL.md

@@ -1,71 +0,0 @@
----
-name: new-method-implementation
-description: >
-  Implement or extend a gmt API in packages/gmt/src by reusing existing gmt
-  helpers first, then Temporal only when needed, while preserving string-first
-  I/O, plain/zoned separation, and fallback-return rules.
-metadata:
-  library_version: 1.14.2
----
-
-# New Method Implementation
-
-Use this skill when adding a new method under `packages/gmt/src`.
-
-## Required behavior
-
-1. Use existing gmt methods first.
-2. If no existing gmt method covers the need, use Temporal to implement a new custom method.
-3. Keep public I/O string-first unless the established module pattern is different.
-4. Enforce strict input/output shapes: prefer ISO 8601 strings, IANA timezone identifiers, and explicit Unix epoch numbers for inputs. Do not accept fuzzy or ambiguous formats — require callers to canonicalize input or use parse/validate helpers.
-5. Keep plain and zoned logic separate.
-6. Do not use `Date`, `Date.now`, or manual date parsing.
-
-## Naming conventions
-
-Follow existing patterns for method names:
-
-- ForDate/ForDateTime/ForZoned suffixes for type-specific variants (e.g., `getQuarterForDate`, `getQuarterForZoned`)
-- startOf* / endOf* for boundaries (e.g., `startOfQuarterForDate`)
-- isBetween* for range checks (e.g., `isBetweenDate`, `isBetweenZoned`)
-- get* for getters (e.g., `getQuarterForDate`)
-
-## Implementation flow
-
-1. Discover existing method
-- Search `packages/gmt/src/plain` and `packages/gmt/src/zoned` for an existing helper.
-- If one exists, use it and do not add duplicate API surface.
-
-2. Decide module boundary
-- Put timezone-free logic in `plain/*`.
-- Put timezone-aware logic in `zoned/*`.
-
-3. Build with Temporal
-- Parse using Temporal constructors.
-- Perform immutable Temporal operations.
-- Return normalized output in the module's expected shape.
-
-4. Apply fallback policy
-- String return type: return `""` on invalid input.
-- Number return type: return `null` on invalid input.
-- Boolean return type: return `false` on invalid input.
-
-5. Add tests
-- Add strong unit tests for valid, invalid, and boundary scenarios.
-- Include DST and timezone boundaries for zoned methods.
-- Use `it.each` template tables for matrixed test cases.
-
-6. Update exports and docs
-- Add to relevant `index.ts` file in the module.
-- Add to package.json exports if new subpath needed.
-- Update README.md API Surface section.
-
-## Prompter guidance when method does not exist
-
-If requested behavior is not currently covered by gmt:
-
-1. Tell the prompter it is possible via Temporal because gmt ships Temporal.
-2. State this requires a new custom gmt method.
-3. Ask them to open a GitHub issue requesting the functionality.
-4. If they proceed locally, implement the method plus solid unit tests.
-5. Recommend they open a PR or include exact proposal details in the issue.