From 70131560c4f86c010d73fd61b09cc74ceb96076c Mon Sep 17 00:00:00 2001 From: Jack Lukic Date: Fri, 20 Nov 2026 17:02:22 -0500 Subject: [PATCH 1/4] Harness: Group decision logs under decisions/ with D1-D17 IDs --- AGENTS.md | 9 +- ai/contributing/README.md | 12 +- ai/contributing/decisions-index.md | 104 -------- ai/contributing/decisions.md | 225 ++++++++---------- ai/contributing/decisions/README.md | 46 ++++ ai/contributing/decisions/package.md | 105 ++++++++ ai/contributing/decisions/project.md | 3 + ai/contributing/project-decisions.md | 5 - .../workflows/clean-room-dx-review.md | 2 +- tools/gates/decisions-index.js | 50 ++-- tools/gates/decisions-index.test.js | 56 +++-- 11 files changed, 331 insertions(+), 286 deletions(-) delete mode 100644 ai/contributing/decisions-index.md create mode 100644 ai/contributing/decisions/README.md create mode 100644 ai/contributing/decisions/package.md create mode 100644 ai/contributing/decisions/project.md delete mode 100644 ai/contributing/project-decisions.md diff --git a/AGENTS.md b/AGENTS.md index fa3f5eb..5e86c9f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,10 +12,11 @@ Before authoring or editing code in this repository, read: 4. **[`ai/contributing/standards/coding-standards.md`](ai/contributing/standards/coding-standards.md)** and **[`ai/contributing/standards/code-comments.md`](ai/contributing/standards/code-comments.md)**: Class anatomy with `Symbol.for` branding, plus folder homogeneity and comment standards. 5. **[`ai/contributing/reference/architecture.md`](ai/contributing/reference/architecture.md)**: Package boundaries across `native-dates` (`src/`), `@native-dates/plugins` (`packages/plugins/`), `@native-dates/polyfill` (`packages/polyfill/`), and `ai/skills/`, plus invariants and size measurement. 6. **[`ai/contributing/budget.md`](ai/contributing/budget.md)**: Bundle ceilings, per-PR byte limits, and the size budget rules. -7. **[`ai/contributing/decisions.md`](ai/contributing/decisions.md)**: Package design decisions. Grep the noun you are about to touch and check the latest dated entry. +7. **[`ai/contributing/decisions.md`](ai/contributing/decisions.md)**: Generated topic and chronological index of package design decisions (`D1`..`Dn`), linking into [`ai/contributing/decisions/package.md`](ai/contributing/decisions/package.md). Grep the noun you are about to touch and check the latest entry. Load task-specific guides when relevant: +- **[`ai/contributing/decisions/README.md`](ai/contributing/decisions/README.md)**: Adding or reopening a decision in `decisions/package.md` or `decisions/project.md` (what belongs vs. normal features and bug fixes, `D` format, and confidence calibration). - **[`ai/contributing/standards/legibility/`](ai/contributing/standards/legibility/README.md)**: Craft guides for `code-structures`, `errors-and-logs`, `folders-and-filenames`, `tests-and-test-names`, and `traces-and-timelines`. Paths in those files reference the upstream repo they were written in, while the rules apply here. - **[`ai/contributing/workflows/author-user-skill.md`](ai/contributing/workflows/author-user-skill.md)** and **[`ai/contributing/standards/ai-author-context.md`](ai/contributing/standards/ai-author-context.md)**: Authoring, chunking, and evaluating downstream user skills in `ai/skills/`. - **[`ai/contributing/workflows/clean-room-dx-review.md`](ai/contributing/workflows/clean-room-dx-review.md)**: Running a quarantined fresh-reader DX review over candidate public API surface. @@ -42,7 +43,7 @@ Files in [`ai/contributing/standards/`](ai/contributing/standards/README.md) are - **Structured errors:** Build every error via `refuse()` or `refuseType()` in `src/helpers/errors.js` (`dates refused [code] at`). Explanations are gated behind `isDevelopment` (`NODE_ENV !== 'production'`) so production builds omit diagnostic prose (`ai/contributing/standards/legibility/errors-and-logs.md`, checked by `npm run errors` and `npm run size`). - **Behavioral tests and environments:** Assert `error.code` and `error.at` rather than matching prose sentences (`ai/contributing/standards/legibility/tests-and-test-names.md`). Each package's tests live with it (`test/` for `native-dates` and `packages//test/` for the others) and import packages by their public names; repo and CI tooling tests live under `tools/`. Place pure Node tests in `test/` (core nouns at the top, cross-cutting suites in subfolders like `test/format/` and `test/helpers/`), DOM tests in `test/dom/`, and real Chromium Playwright tests in `test/browser/` (`vitest.config.js`). - **Category-grouped helpers:** Group free functions by domain in `src/helpers/` (`intl.js`, `zones.js`, `parse.js`, `format.js`, `errors.js`, `utils.js`, `environment.js`). -- **Decision records:** Record package behavior decisions in `ai/contributing/decisions.md` and repository process decisions in `ai/contributing/project-decisions.md`, each dated with a reopen condition and an optional maintainer confidence score. +- **Decision records:** Read [`ai/contributing/decisions/README.md`](ai/contributing/decisions/README.md) before recording a decision. Only log entries in `ai/contributing/decisions/package.md` (`D`) or `ai/contributing/decisions/project.md` (`P`) when choosing between competing mental models, rejecting a tempting alternative, or reverting a measured experiment (never for normal features, enhancements, or bug fixes), then run `npm run ai:index` to update `ai/contributing/decisions.md`. - **Scratch directory:** Put temporary plans and notes in git-ignored `ai/workspace/`. ## Undecided @@ -59,8 +60,8 @@ Ask the maintainer rather than inventing conventions for: - `npm run types`: Type-check `.d.ts` declarations via `tsc --noEmit` under NodeNext and `bundler` resolution (`test/types.ts`) - `npm run errors`: Check error and log prose register (`tools/gates/errors.js`) - `npm run comments`: Check comment density, overlap, and banned jargon (`tools/gates/comments.js`) -- `npm run ai`: Validate markdown links, `#anchors`, GFM tables, `ai/` paths, `decisions-index.md`, and `AGENTS.md` symlinks (`tools/gates/ai.js`) -- `npm run ai:index`: Regenerate `ai/contributing/decisions-index.md` from `ai/contributing/decisions.md` (`tools/gates/decisions-index.js`) +- `npm run ai`: Validate markdown links, `#anchors`, GFM tables, `ai/` paths, `decisions.md`, and `AGENTS.md` symlinks (`tools/gates/ai.js`) +- `npm run ai:index`: Regenerate `ai/contributing/decisions.md` from `ai/contributing/decisions/package.md` (`tools/gates/decisions-index.js`) - `npm run size`: Measure minified and Brotli-11 sizes for `native-dates` and every plugin in `@native-dates/plugins`, and check `ai/contributing/budget.md` ([`tools/ci/bundle/README.md`](tools/ci/bundle/README.md)) - `npm run docs`: Start the Astro docs dev server (`docs/`, see [`docs/README.md`](docs/README.md)) - `npm run format`: Format files with `dprint` diff --git a/ai/contributing/README.md b/ai/contributing/README.md index d4ab24f..c36e126 100644 --- a/ai/contributing/README.md +++ b/ai/contributing/README.md @@ -7,7 +7,7 @@ Internal records and workflows for developing `native-dates`. Application develo | Task | Reading order | |---|---| | Fix a bug, add a feature, or file a bug report | [`CONTRIBUTING.md`](../../CONTRIBUTING.md), then [`workflows/contribute.md`](workflows/contribute.md) | -| Check design or process rulings | [`decisions-index.md`](decisions-index.md) and [`decisions.md`](decisions.md) for package behavior, [`project-decisions.md`](project-decisions.md) for repo process | +| Check or record design and process decisions | [`decisions.md`](decisions.md) for the topic index, [`decisions/README.md`](decisions/README.md) before adding or reopening an entry, [`decisions/package.md`](decisions/package.md) (`D1`..`Dn`), and [`decisions/project.md`](decisions/project.md) (`P1`..`Pn`) | | Check bundle size limits | [`budget.md`](budget.md), checked by `npm run size` | | Configure GitHub secrets, bots, and Vercel deploys | [`reference/setup.md`](reference/setup.md) | | View pending and completed launch tasks | [`plan/roadmap.md`](plan/roadmap.md) and [`plan/landed.md`](plan/landed.md) | @@ -25,8 +25,8 @@ Internal records and workflows for developing `native-dates`. Application develo | Record | Path | Policy | |---|---|---| | North star | [`north-star.md`](north-star.md) | Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings (do not edit or polish) | -| Package decisions | [`decisions.md`](decisions.md), [`decisions-index.md`](decisions-index.md) | Append-only dated entries with reopen conditions and optional maintainer confidence scores (`npm run ai:index` updates the index) | -| Project decisions | [`project-decisions.md`](project-decisions.md) | Append-only dated entries for repo process, CI, and docs conventions | +| Decisions index | [`decisions.md`](decisions.md) | Generated topic and chronological index of package decisions (`npm run ai:index`) | +| Decision logs | [`decisions/`](decisions/README.md) | Authoring rules in `README.md`, package rationales in `package.md` (`D1`..`Dn`), and repo/CI process calls in `project.md` (`P1`..`Pn`) | | Size budget | [`budget.md`](budget.md) | Entry bundles, Brotli ceilings, and per-PR growth rules, updated only by the maintainer | | Launch plan | [`plan/`](plan/roadmap.md) | Pending rows in `roadmap.md`, completed rows in `landed.md`, and briefs in `plan/scopes/` | | Shared standards | [`standards/`](standards/README.md) | Synced from upstream Semantic repos and not edited directly here | @@ -38,9 +38,9 @@ Create `reopened-decisions.md` or folders for research and archived records only ## Conventions -- Decisions that constrain package behavior or public API belong in `decisions.md`. Repo process and tooling calls belong in `project-decisions.md`. -- Supersede an older decision by appending a new dated entry rather than editing history. The latest date wins. -- `decisions.md` records intent, while `plan/landed.md` records what merged. Source code and tests define current behavior. +- Read [`decisions/README.md`](decisions/README.md) before recording a decision: features, enhancements, and bug fixes do not belong in `decisions/package.md`, and repo process calls belong in `decisions/project.md`. +- Supersede an older decision by appending a new `D` entry and marking the earlier entry `Superseded by D ().` rather than deleting history. +- `decisions/package.md` records non-obvious design constraints, while `plan/landed.md` records milestones that merged. Source code and tests define current behavior. - Bundle ceilings and benchmark settings are calibrated per package. Only [`standards/`](standards/README.md) is shared across repos. - Open mutable reference docs with a dated status line instead of writing "not yet built" in body paragraphs. - Run `npm run ai` after editing files here to check links, heading anchors, Markdown tables, and root symlinks. diff --git a/ai/contributing/decisions-index.md b/ai/contributing/decisions-index.md deleted file mode 100644 index b08eef3..0000000 --- a/ai/contributing/decisions-index.md +++ /dev/null @@ -1,104 +0,0 @@ -# Decisions Index - -> Generated from [`decisions.md`](decisions.md) by `npm run ai:index` and checked by `npm run ai`. Do not edit by hand. - -## By Topic - -Active decisions grouped by area, newest first. - -### Zones, Offsets, and Serialization - -- [L27](decisions.md#datetime-serializes-to-iso-8601-utc-rather-than-temporals-bracketed-zone-string-2026-11-05) · `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05) - - Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON. -- [L21](decisions.md#trailing-z-and-numeric-offsets-in-datetime-set-the-instant-not-zone-2026-11-05) · Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05) - - Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`. - -### Ranges - -- [L111](decisions.md#ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) · Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17) - - Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics. -- [L45](decisions.md#daterange-includes-its-end-date-while-datetimerange-and-timerange-are-half-open-2026-11-12) · `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12) - - Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`. - -### Durations - -- [L105](decisions.md#duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) · `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17) - - Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`. - -### Arithmetic, Boundaries, and Weekdays - -- [L117](decisions.md#adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) · Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) - - Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`. -- [L99](decisions.md#numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) · Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17) - - Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`. -- [L57](decisions.md#default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) · Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14) - - Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags. - -### Formatting, Tokens, and Locales - -- [L81](decisions.md#custom-weekdaynames-ordinals-and-named-formats-live-in-configure-instead-of-locale-plugins-2026-11-16) · Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16) - - Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table. -- [L63](decisions.md#format-tokens-output-ascii-digits-and-gregorian-years-while-presets-localize-the-calendar-2026-11-14) · Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14) - - Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates. -- [L51](decisions.md#locale-attaches-a-formatting-locale-to-values-without-affecting-equality-or-json-2026-11-14) · `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14) - - Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality. - -### Parsing, Inputs, and Comparisons - -- [L87](decisions.md#core-parses-unambiguous-non-iso-inputs-and-refuses-inputs-with-two-readings-2026-11-16) · Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16) - - Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate. - -### Nouns, Instances, and Epoch - -- [L93](decisions.md#unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) · Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17) - - Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs. -- [L33](decisions.md#instances-freeze-on-construction-with-text-as-an-eager-own-property-2026-11-05) · Instances freeze on construction with `text` as an eager own property (2026-11-05) - - Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops. - -### Plugins, Errors, and Dependencies - -- [L75](decisions.md#error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16) · Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) - - Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper. -- [L69](decisions.md#core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16) · Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) - - Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies. -- [L39](decisions.md#plugins-attach-on-subpath-import-instead-of-requiring-use-or-extend-2026-11-08) · Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08) - - Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`. - -## Chronological - -Every entry in file order. - -- [L21](decisions.md#trailing-z-and-numeric-offsets-in-datetime-set-the-instant-not-zone-2026-11-05) · Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05) - - Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`. -- [L27](decisions.md#datetime-serializes-to-iso-8601-utc-rather-than-temporals-bracketed-zone-string-2026-11-05) · `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05) - - Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON. -- [L33](decisions.md#instances-freeze-on-construction-with-text-as-an-eager-own-property-2026-11-05) · Instances freeze on construction with `text` as an eager own property (2026-11-05) - - Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops. -- [L39](decisions.md#plugins-attach-on-subpath-import-instead-of-requiring-use-or-extend-2026-11-08) · Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08) - - Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`. -- [L45](decisions.md#daterange-includes-its-end-date-while-datetimerange-and-timerange-are-half-open-2026-11-12) · `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12) - - Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`. -- [L51](decisions.md#locale-attaches-a-formatting-locale-to-values-without-affecting-equality-or-json-2026-11-14) · `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14) - - Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality. -- [L57](decisions.md#default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) · Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14) - - Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags. -- [L63](decisions.md#format-tokens-output-ascii-digits-and-gregorian-years-while-presets-localize-the-calendar-2026-11-14) · Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14) - - Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates. -- [L69](decisions.md#core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16) · Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) - - Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies. -- [L75](decisions.md#error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16) · Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) - - Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper. -- [L81](decisions.md#custom-weekdaynames-ordinals-and-named-formats-live-in-configure-instead-of-locale-plugins-2026-11-16) · Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16) - - Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table. -- [L87](decisions.md#core-parses-unambiguous-non-iso-inputs-and-refuses-inputs-with-two-readings-2026-11-16) · Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16) - - Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate. -- [L93](decisions.md#unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) · Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17) - - Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs. -- [L99](decisions.md#numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) · Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17) - - Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`. -- [L105](decisions.md#duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) · `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17) - - Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`. -- [L111](decisions.md#ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) · Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17) - - Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics. -- [L117](decisions.md#adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) · Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) - - Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`. diff --git a/ai/contributing/decisions.md b/ai/contributing/decisions.md index ebbc0af..b40654a 100644 --- a/ai/contributing/decisions.md +++ b/ai/contributing/decisions.md @@ -1,121 +1,104 @@ -# Decisions: Package Design Log - -Append-only log of decisions governing what `native-dates` exports and how it behaves: semantics, public API names, option shapes, bundle ceilings, and constraints on future surface. Entries are ordered chronologically, and the latest entry on a topic supersedes earlier ones while preserving prior entries for context (see [`decisions-index.md`](decisions-index.md) for the generated topic and chronological index). - -**Inclusion test.** Record decisions here when they bind package behavior across multiple changes. One-off implementation choices belong in the PR, obvious facts already visible in source stay tacit, and repository conventions (CI, docs workflow, release process) belong in [`project-decisions.md`](project-decisions.md). Ask: *Does someone modifying this package two years from now need to follow this rule?* - -**Prose style.** Keep entries brief and human-scannable. Write the heading as a plain claim (`A uses B instead of C`), followed by 2-3 sentences on the tradeoff or failure mode that ruled out the alternative. Skip signatures or mechanics already readable in source or API docs, and omit PR numbers and session history. - -**Entry format.** `## ()`, an optional `*<0-100>% confident*` line when scored (omitted when unscored), a concise rationale, and a closing `Reopen: ` line. When a later decision overturns an earlier one, add `Superseded by .` to the earlier entry. - -**Confidence scores.** Optional 0-100 probability assigned by the maintainer at decision time. Calibrated scores reflect actual odds of reversal rather than rhetorical finality: a 70 expects roughly 3 in 10 such calls to flip with new evidence, and a 90 still expects 1 in 10 to turn out wrong: - -- **90+:** High confidence, though roughly 1 in 10 calls at 90 will still prove wrong. Reopen when its `Reopen:` condition is met or concrete counter-evidence appears. -- **~60-75:** Working decision under real tradeoffs, with a meaningful chance real-world usage flips it. -- **<50:** Provisional default chosen to unblock shipping until usage data arrives. - -**Reopening a decision.** Any decision may be reopened when concrete evidence shows its `Reopen:` condition has been met, surfaces a tradeoff not weighed in the original entry, or exposes a clear usability hazard for downstream callers. - ---- - -## Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05) - -Database and JSON timestamps normally arrive with `Z` (`'2026-03-08T04:30:00Z'`). Adopting `'UTC'` or a fixed offset from the input string (like Moment's `parseZone`) would silently disable DST rules on subsequent `.plus(1, 'day')` or `.startOf('day')` calls unless callers remember `.in(zone)`. - -Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`. - -## `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05) - -`Temporal.ZonedDateTime.prototype.toString()` appends `-05:00[America/New_York]`, which `Date.parse()`, PostgreSQL `timestamptz`, and standard ISO 8601 parsers reject. `toString()` and `toJSON()` output standard UTC strings (`...Z`) so `DateTime` values work directly in JSON payloads and database parameters. - -Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON. - -## Instances freeze on construction with `text` as an eager own property (2026-11-05) - -Setting `text` as the first enumerable own property shows the human-readable value first in `console.log()` and object spreads without clicking prototype getters in DevTools or Node. On `Duration`, eager `Intl.DurationFormat` formatting (~14 µs in Node) was accepted over a lazy getter so console output behaves the same across every class. - -Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops. - -## Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08) - -Explicit registration (`use(plugin)`, used initially and removed) recreates Day.js's load-order bug when a module parses or formats a date before startup code runs, and requires TypeScript callers to keep runtime `use()` calls in sync with type imports. Because prototype methods and parser hooks are process-wide anyway, `use()` added ordering bugs without isolating instances. - -Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`. - -## `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12) - -In everyday English, SQL `BETWEEN`, and date pickers, "Monday to Friday" means 5 days rather than 4, so half-open `DateRange` bounds would cause off-by-one end dates. Timestamps and clock times use `[start, end)` so adjacent slots (`09:00` to `10:00`, `10:00` to `11:00`) share `10:00` without overlap or a 1 ms gap, and `TimeRange` treats `end < start` as crossing midnight (`22:00` to `06:00`) for overnight shifts. - -Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`. - -## `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14) - -Process-wide `configure({ locale })` leaks across concurrent requests on Node servers, so instances carry an optional locale (+320 B Brotli) through method chains while keeping `equals()`, `compare()`, `toString()`, and `toJSON()` locale-independent. `.locale()` also accepts POSIX `'en_US'` tags and HTTP `Accept-Language` headers in core (+130 B) because `.locale()` has no `{ loose: true }` option. - -Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality. - -## Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14) - -Defaulting `startOf('week')`, `endOf('week')`, `range('week')`, and `weekdayNames()` to Monday produced the wrong calendar week out of the box in Sunday-start (`en-US`, `ja-JP`, `pt-BR`) and Saturday-start (`ar-EG`, `fa-IR`) locales (+70 B Brotli via `Intl.Locale.prototype.getWeekInfo`). `weekOfYear` and the `W` token keep ISO 8601 Monday numbering because business week numbers are an unlocalized standard. - -Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags. - -## Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14) - -Developers use `'YYYY-MM-DD'` for URLs, filenames, and API payloads that need ASCII digits and Gregorian years even when the active locale uses Arabic-Indic digits (`ar-EG`) or non-Gregorian calendars (`fa-IR`, `th-TH`). `MonthDay` and `YearMonth` also use Gregorian months because ISO anniversaries fall on different Persian or Islamic dates each year, and `YearMonth` `'short'` uses 4-digit years (`'11/2026'`) so `'11/26'` is not misread as November 26. - -Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates. - -## Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) - -Depending on `@semantic-ui/utils` was tried and reverted because zero dependencies is a common requirement when picking a date library. Copying the shared helpers verbatim saved apps already bundling `@semantic-ui/utils` 61 B Brotli while costing standalone consumers 300 B from unused branches in `each()` and `createErrors` that bundlers could not tree-shake, so `src/helpers/utils.js` keeps only the branches `native-dates` uses. - -Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies. - -## Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) - -Error calls pass `explanation: isDevelopment ? '...' : 0` inline at the callsite because minifiers cannot strip string literals passed unconditionally into a helper. When `{ loose: true }` is enabled, only malformed input data returns `null`, while invalid caller options (`unknownZone`, `unknownLocale`, `unknownFormat`) still throw. - -Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper. - -## Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16) - -`dd` and `Do` are the only Moment/Day.js tokens with no `Intl` field. A `@native-dates/plugins/weekdays` plugin and hard-coded French `1er` rule were removed once `Intl`-derived defaults covered nearly all locales (+220 B for `weekdayNames`/`ordinals`, +70 B for `formats`), avoiding per-language tables in core and a plugin name suggesting weekdays required an extra import. `weekdayNames` keys days by name (`fri`, `sun`) rather than array index to avoid Sunday-0 vs. Monday-1 off-by-one bugs. - -Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table. - -## Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16) - -Year-first `'2026/1/5'`, leading epoch-ms numbers in `compare(Date.now(), dt)`, and fixed-ratio duration borrowing (`years(1).minus(months(1))` -> 11 months, `weeks(1).minus(days(1))` -> 6 days) each have a single valid interpretation (+230 B total). Core still refuses `'11/06/2026'` (ambiguous between US and European order), `days(1).minus(hours(1))` (differs by an hour from `.plus(days(1)).minus(hours(1))` across DST), and `compare(CalendarDate, DateTime)` (treating dates as midnight contradicts `isBefore()`, while tying across the day breaks `Array.prototype.sort`). - -Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate. - -## Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17) - -Shells, Python, SQL, and JWT `exp`/`iat` claims count Unix time in seconds while `Date.now()` uses milliseconds, so an unqualified `.epoch` or `.timestamp` makes `claims.exp = dt.epoch` silently 1,000x too large. Requiring the unit in the property name gives up short round-tripping with `datetime(ms)` to prevent seconds-vs-milliseconds bugs at API boundaries. - -Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs. - -## Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17) - -Naming the `1`-`7` property `.weekday` made `sunday.weekday` return `7` while `sunday.isWeekday()` returned `false`, and collided with custom display names in `configure({ weekdayNames })`. Format token `d` keeps `0` = Sunday through `6` = Saturday to match Moment and Day.js alongside `E` for ISO `1`-`7`. - -Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`. - -## `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17) - -Blind naming reviewers guessed `normalize()` for cascading `90 minutes` into `1 hour 30 minutes` and preferred `hours(36).in('days')` for numeric conversion. Aliasing `normalize` to `balance` was rejected because Luxon's `Duration.prototype.normalize()` leaves `{ minutes: 90 }` unchanged instead of promoting into absent units, and `.in()` returns an object instance everywhere else (`datetime.in(zone)`, `monthDay.in(year)`, `range.in(zone)`). - -Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`. - -## Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17) - -Cold readers misread `start.to(3, 'days')` as a unit conversion and ranked `start.for(3, 'days')` first (+10 B), which also avoids inclusive-end off-by-one math on `CalendarDate`. `.to()` still accepts durations because restricting `.to()` to endpoints would make `time('9am').to(8, 'hours')` parse `8` as `08:00` and return a 23-hour range, while `.through()` is limited to `CalendarDate` because `DateTimeRange` and `TimeRange` exclude their end. - -Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics. - -## Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) - -Overloading `next('month')` conflicts with `DateTime.prototype.next('friday')`, which preserves the time of day (`09:30`) while a unit boundary resets to `00:00`, and callers split on whether `next('month')` means the 1st of next month or `plus(1, 'month')`. Numeric weekdays are rejected in `startOfNext()` so misplaced counts like `startOfNext(2, 'months')` cannot silently resolve `2` as Tuesday. - -Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`. +# Decisions + +> Generated from [`decisions/package.md`](decisions/package.md) by `npm run ai:index` and checked by `npm run ai`. Do not edit by hand. Read [`decisions/README.md`](decisions/README.md) before adding or reopening an entry (features and bug fixes do not belong here, and repo process calls belong in [`decisions/project.md`](decisions/project.md)). + +## By Topic + +Active package decisions grouped by area, newest first. + +### Zones, Offsets, and Serialization + +- **D2:** `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05) [L11-L15](decisions/package.md#d2-datetime-serializes-to-iso-8601-utc-rather-than-temporals-bracketed-zone-string-2026-11-05) + - Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON. +- **D1:** Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05) [L5-L9](decisions/package.md#d1-trailing-z-and-numeric-offsets-in-datetime-set-the-instant-not-zone-2026-11-05) + - Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`. + +### Ranges + +- **D16:** Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17) [L95-L99](decisions/package.md#d16-ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) + - Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics. +- **D5:** `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12) [L29-L33](decisions/package.md#d5-daterange-includes-its-end-date-while-datetimerange-and-timerange-are-half-open-2026-11-12) + - Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`. + +### Durations + +- **D15:** `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17) [L89-L93](decisions/package.md#d15-duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) + - Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`. + +### Arithmetic, Boundaries, and Weekdays + +- **D17:** Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) [L101-L105](decisions/package.md#d17-adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) + - Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`. +- **D14:** Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17) [L83-L87](decisions/package.md#d14-numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) + - Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`. +- **D7:** Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14) [L41-L45](decisions/package.md#d7-default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) + - Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags. + +### Formatting, Tokens, and Locales + +- **D11:** Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16) [L65-L69](decisions/package.md#d11-custom-weekdaynames-ordinals-and-named-formats-live-in-configure-instead-of-locale-plugins-2026-11-16) + - Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table. +- **D8:** Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14) [L47-L51](decisions/package.md#d8-format-tokens-output-ascii-digits-and-gregorian-years-while-presets-localize-the-calendar-2026-11-14) + - Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates. +- **D6:** `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14) [L35-L39](decisions/package.md#d6-locale-attaches-a-formatting-locale-to-values-without-affecting-equality-or-json-2026-11-14) + - Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality. + +### Parsing, Inputs, and Comparisons + +- **D12:** Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16) [L71-L75](decisions/package.md#d12-core-parses-unambiguous-non-iso-inputs-and-refuses-inputs-with-two-readings-2026-11-16) + - Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate. + +### Nouns, Instances, and Epoch + +- **D13:** Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17) [L77-L81](decisions/package.md#d13-unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) + - Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs. +- **D3:** Instances freeze on construction with `text` as an eager own property (2026-11-05) [L17-L21](decisions/package.md#d3-instances-freeze-on-construction-with-text-as-an-eager-own-property-2026-11-05) + - Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops. + +### Plugins, Errors, and Dependencies + +- **D10:** Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) [L59-L63](decisions/package.md#d10-error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16) + - Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper. +- **D9:** Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) [L53-L57](decisions/package.md#d9-core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16) + - Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies. +- **D4:** Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08) [L23-L27](decisions/package.md#d4-plugins-attach-on-subpath-import-instead-of-requiring-use-or-extend-2026-11-08) + - Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`. + +## Chronological + +Every package decision (`D1`..`Dn`) in file order. + +- **D1:** Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05) [L5-L9](decisions/package.md#d1-trailing-z-and-numeric-offsets-in-datetime-set-the-instant-not-zone-2026-11-05) + - Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`. +- **D2:** `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05) [L11-L15](decisions/package.md#d2-datetime-serializes-to-iso-8601-utc-rather-than-temporals-bracketed-zone-string-2026-11-05) + - Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON. +- **D3:** Instances freeze on construction with `text` as an eager own property (2026-11-05) [L17-L21](decisions/package.md#d3-instances-freeze-on-construction-with-text-as-an-eager-own-property-2026-11-05) + - Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops. +- **D4:** Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08) [L23-L27](decisions/package.md#d4-plugins-attach-on-subpath-import-instead-of-requiring-use-or-extend-2026-11-08) + - Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`. +- **D5:** `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12) [L29-L33](decisions/package.md#d5-daterange-includes-its-end-date-while-datetimerange-and-timerange-are-half-open-2026-11-12) + - Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`. +- **D6:** `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14) [L35-L39](decisions/package.md#d6-locale-attaches-a-formatting-locale-to-values-without-affecting-equality-or-json-2026-11-14) + - Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality. +- **D7:** Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14) [L41-L45](decisions/package.md#d7-default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) + - Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags. +- **D8:** Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14) [L47-L51](decisions/package.md#d8-format-tokens-output-ascii-digits-and-gregorian-years-while-presets-localize-the-calendar-2026-11-14) + - Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates. +- **D9:** Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) [L53-L57](decisions/package.md#d9-core-has-zero-runtime-dependencies-and-trims-forked-semantic-uiutils-helpers-to-used-branches-2026-11-16) + - Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies. +- **D10:** Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) [L59-L63](decisions/package.md#d10-error-explanations-use-inline-isdevelopment-checks-and--loose-true--still-throws-on-bad-options-2026-11-16) + - Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper. +- **D11:** Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16) [L65-L69](decisions/package.md#d11-custom-weekdaynames-ordinals-and-named-formats-live-in-configure-instead-of-locale-plugins-2026-11-16) + - Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table. +- **D12:** Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16) [L71-L75](decisions/package.md#d12-core-parses-unambiguous-non-iso-inputs-and-refuses-inputs-with-two-readings-2026-11-16) + - Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate. +- **D13:** Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17) [L77-L81](decisions/package.md#d13-unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) + - Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs. +- **D14:** Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17) [L83-L87](decisions/package.md#d14-numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) + - Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`. +- **D15:** `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17) [L89-L93](decisions/package.md#d15-duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) + - Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`. +- **D16:** Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17) [L95-L99](decisions/package.md#d16-ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) + - Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics. +- **D17:** Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) [L101-L105](decisions/package.md#d17-adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) + - Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`. diff --git a/ai/contributing/decisions/README.md b/ai/contributing/decisions/README.md new file mode 100644 index 0000000..cd7f2eb --- /dev/null +++ b/ai/contributing/decisions/README.md @@ -0,0 +1,46 @@ +# Using and Recording Decisions + +Read this guide before appending to or reopening an entry in [`package.md`](package.md) or [`project.md`](project.md). For browsing existing decisions by topic, start at [`../decisions.md`](../decisions.md). + +## Files + +| File | Role | +|---|---| +| [`../decisions.md`](../decisions.md) | Generated topic and chronological index (`npm run ai:index`). Do not edit by hand | +| [`package.md`](package.md) | Append-only package design log (`D1`, `D2`, ...) | +| [`project.md`](project.md) | Append-only repository, CI, docs workflow, and release process log (`P1`, `P2`, ...) | + +## What Belongs Here + +Record a decision only when reading `src/`, `types/`, and `docs/` alone would leave a future contributor guessing why another reasonable option was not taken: + +- **Competing mental models:** Choosing one position among ambiguous or overlapping options (`Z` setting the instant rather than `.zone`, `DateRange` closed vs `DateTimeRange` half-open, `weekStart` following locale while `weekOfYear` stays ISO Monday). +- **Deliberate omissions and rejected names:** Leaving out an API or alias that callers or contributors would naturally propose (`no bare .epoch`, `no Duration.prototype.normalize()`, `no next('month')`, `no use(plugin)`). +- **Tried-and-reverted experiments:** Approaches built, measured, and removed so nobody repeats them (`@semantic-ui/utils` verbatim copy costing standalone apps +300 B Brotli, `days(1).minus(hours(1))` diverging across DST, `@native-dates/plugins/weekdays`). + +## What Does Not Belong Here + +- **Features and enhancements** whose behavior follows expected conventions (adding an ISO token like `E`, adding `fromNow()`). Source, types, docs, and `git log` already record what shipped. +- **Bug fixes** where prior behavior was simply broken rather than an intentional tradeoff. +- **Unbuilt backlog notes** (*"omitted until requested"*). Deferred work belongs in [`../plan/roadmap.md`](../plan/roadmap.md) or nowhere, never inside a decision entry where building it later creates churn. +- **Single-site implementation details** explainable by a one-line code comment at the callsite. + +**Gut check:** *If a capable engineer only read the code and docs two years from now, would they reasonably propose the rejected option and reintroduce a bug, ambiguity, or bundle cost?* If no, do not write an entry. + +## Entry Format + +Append new entries to the bottom of [`package.md`](package.md) (next `D`) or [`project.md`](project.md) (next `P`), then run `npm run ai:index`: + +```markdown +## D18: A uses B instead of C (2026-11-20) + +*85% confident* + +2-3 sentences on the tradeoff, failure mode, or measurement that ruled out C. Skip signatures or mechanics already readable in source or API docs, and omit PR numbers and session history. + +Reopen: observable condition that justifies revisiting this call. +``` + +- **Confidence line (`*0-100% confident*`):** Optional probability assigned by the maintainer at decision time; omit the line when unscored. Calibrated scores reflect actual reversal odds rather than finality: a `70%` call expects roughly 3 in 10 such calls to flip with new evidence, and a `90%` call still expects 1 in 10 to prove wrong (`~60-75%` working tradeoff, `<50%` provisional default). +- **Superseding an earlier entry:** Append the new `D` entry at the bottom and replace the earlier entry's `Reopen:` line with `Superseded by D ().` so history stays intact while the topic index shows only active calls. +- **Reopening:** Surface an entry to reopen whenever concrete evidence shows its `Reopen:` condition has been met, exposes a tradeoff not weighed in the entry, or reveals a clear usability hazard. diff --git a/ai/contributing/decisions/package.md b/ai/contributing/decisions/package.md new file mode 100644 index 0000000..e431dcb --- /dev/null +++ b/ai/contributing/decisions/package.md @@ -0,0 +1,105 @@ +# Package Decisions + +> Append-only package design log (`D1`..`Dn`). Read [`README.md`](README.md) before adding or reopening an entry (features and bug fixes do not belong here), and run `npm run ai:index` to update [`../decisions.md`](../decisions.md). + +## D1: Trailing `Z` and numeric offsets in `datetime()` set the instant, not `.zone` (2026-11-05) + +Database and JSON timestamps normally arrive with `Z` (`'2026-03-08T04:30:00Z'`). Adopting `'UTC'` or a fixed offset from the input string (like Moment's `parseZone`) would silently disable DST rules on subsequent `.plus(1, 'day')` or `.startOf('day')` calls unless callers remember `.in(zone)`. + +Reopen: downstream bug reports show callers passing `Z` strings expecting `.hour` and `.zone` to default to `'UTC'`. + +## D2: `DateTime` serializes to ISO 8601 UTC rather than Temporal's bracketed `[Zone]` string (2026-11-05) + +`Temporal.ZonedDateTime.prototype.toString()` appends `-05:00[America/New_York]`, which `Date.parse()`, PostgreSQL `timestamptz`, and standard ISO 8601 parsers reject. `toString()` and `toJSON()` output standard UTC strings (`...Z`) so `DateTime` values work directly in JSON payloads and database parameters. + +Reopen: RFC 9557 bracketed zone strings gain broad database and parser support and callers request round-tripping `.zone` through JSON. + +## D3: Instances freeze on construction with `text` as an eager own property (2026-11-05) + +Setting `text` as the first enumerable own property shows the human-readable value first in `console.log()` and object spreads without clicking prototype getters in DevTools or Node. On `Duration`, eager `Intl.DurationFormat` formatting (~14 µs in Node) was accepted over a lazy getter so console output behaves the same across every class. + +Reopen: benchmark profiles in `bench/` show eager `text` construction dominating hot arithmetic or `range.points()` loops. + +## D4: Plugins attach on subpath import instead of requiring `use()` or `extend()` (2026-11-08) + +Explicit registration (`use(plugin)`, used initially and removed) recreates Day.js's load-order bug when a module parses or formats a date before startup code runs, and requires TypeScript callers to keep runtime `use()` calls in sync with type imports. Because prototype methods and parser hooks are process-wide anyway, `use()` added ordering bugs without isolating instances. + +Reopen: a standard bundler configuration tree-shakes an imported `@native-dates/plugins/*` module despite `"sideEffects": ["./src/*.js"]`. + +## D5: `DateRange` includes its end date while `DateTimeRange` and `TimeRange` are half-open (2026-11-12) + +In everyday English, SQL `BETWEEN`, and date pickers, "Monday to Friday" means 5 days rather than 4, so half-open `DateRange` bounds would cause off-by-one end dates. Timestamps and clock times use `[start, end)` so adjacent slots (`09:00` to `10:00`, `10:00` to `11:00`) share `10:00` without overlap or a 1 ms gap, and `TimeRange` treats `end < start` as crossing midnight (`22:00` to `06:00`) for overnight shifts. + +Reopen: bug reports show callers frequently off by one day when converting between `DateRange` and `DateTimeRange`. + +## D6: `.locale()` attaches a formatting locale to values without affecting equality or JSON (2026-11-14) + +Process-wide `configure({ locale })` leaks across concurrent requests on Node servers, so instances carry an optional locale (+320 B Brotli) through method chains while keeping `equals()`, `compare()`, `toString()`, and `toJSON()` locale-independent. `.locale()` also accepts POSIX `'en_US'` tags and HTTP `Accept-Language` headers in core (+130 B) because `.locale()` has no `{ loose: true }` option. + +Reopen: callers hit assertion bugs because two `.equals()` values in different locales have different `.text` own properties under deep-object equality. + +## D7: Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14) + +Defaulting `startOf('week')`, `endOf('week')`, `range('week')`, and `weekdayNames()` to Monday produced the wrong calendar week out of the box in Sunday-start (`en-US`, `ja-JP`, `pt-BR`) and Saturday-start (`ar-EG`, `fa-IR`) locales (+70 B Brotli via `Intl.Locale.prototype.getWeekInfo`). `weekOfYear` and the `W` token keep ISO 8601 Monday numbering because business week numbers are an unlocalized standard. + +Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags. + +## D8: Format tokens output ASCII digits and Gregorian years while presets localize the calendar (2026-11-14) + +Developers use `'YYYY-MM-DD'` for URLs, filenames, and API payloads that need ASCII digits and Gregorian years even when the active locale uses Arabic-Indic digits (`ar-EG`) or non-Gregorian calendars (`fa-IR`, `th-TH`). `MonthDay` and `YearMonth` also use Gregorian months because ISO anniversaries fall on different Persian or Islamic dates each year, and `YearMonth` `'short'` uses 4-digit years (`'11/2026'`) so `'11/26'` is not misread as November 26. + +Reopen: native speakers request an opt-in localized-numeral token mode or non-Gregorian partial dates. + +## D9: Core has zero runtime dependencies and trims forked `@semantic-ui/utils` helpers to used branches (2026-11-16) + +Depending on `@semantic-ui/utils` was tried and reverted because zero dependencies is a common requirement when picking a date library. Copying the shared helpers verbatim saved apps already bundling `@semantic-ui/utils` 61 B Brotli while costing standalone consumers 300 B from unused branches in `each()` and `createErrors` that bundlers could not tree-shake, so `src/helpers/utils.js` keeps only the branches `native-dates` uses. + +Reopen: `@semantic-ui/utils` publishes tree-shakeable single-branch entrypoints with zero unreached bytes and consumers favor cross-package deduplication over zero dependencies. + +## D10: Error explanations use inline `isDevelopment` checks, and `{ loose: true }` still throws on bad options (2026-11-16) + +Error calls pass `explanation: isDevelopment ? '...' : 0` inline at the callsite because minifiers cannot strip string literals passed unconditionally into a helper. When `{ loose: true }` is enabled, only malformed input data returns `null`, while invalid caller options (`unknownZone`, `unknownLocale`, `unknownFormat`) still throw. + +Reopen: callers building dynamic zone or format inputs from untrusted user text need a non-throwing validation helper. + +## D11: Custom `weekdayNames`, `ordinals`, and named `formats` live in `configure()` instead of locale plugins (2026-11-16) + +`dd` and `Do` are the only Moment/Day.js tokens with no `Intl` field. A `@native-dates/plugins/weekdays` plugin and hard-coded French `1er` rule were removed once `Intl`-derived defaults covered nearly all locales (+220 B for `weekdayNames`/`ordinals`, +70 B for `formats`), avoiding per-language tables in core and a plugin name suggesting weekdays required an extra import. `weekdayNames` keys days by name (`fri`, `sun`) rather than array index to avoid Sunday-0 vs. Monday-1 off-by-one bugs. + +Reopen: multiple downstream apps duplicate the same locale ordinal or `dd` overrides and warrant a shared community table. + +## D12: Core parses unambiguous non-ISO inputs and refuses inputs with two readings (2026-11-16) + +Year-first `'2026/1/5'`, leading epoch-ms numbers in `compare(Date.now(), dt)`, and fixed-ratio duration borrowing (`years(1).minus(months(1))` -> 11 months, `weeks(1).minus(days(1))` -> 6 days) each have a single valid interpretation (+230 B total). Core still refuses `'11/06/2026'` (ambiguous between US and European order), `days(1).minus(hours(1))` (differs by an hour from `.plus(days(1)).minus(hours(1))` across DST), and `compare(CalendarDate, DateTime)` (treating dates as midnight contradicts `isBefore()`, while tying across the day breaks `Array.prototype.sort`). + +Reopen: a non-ISO form accepted in core misparses real input, or callers repeatedly hit one of the remaining refusals where an explicit option could disambiguate. + +## D13: Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17) + +Shells, Python, SQL, and JWT `exp`/`iat` claims count Unix time in seconds while `Date.now()` uses milliseconds, so an unqualified `.epoch` or `.timestamp` makes `claims.exp = dt.epoch` silently 1,000x too large. Requiring the unit in the property name gives up short round-tripping with `datetime(ms)` to prevent seconds-vs-milliseconds bugs at API boundaries. + +Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs. + +## D14: Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17) + +Naming the `1`-`7` property `.weekday` made `sunday.weekday` return `7` while `sunday.isWeekday()` returned `false`, and collided with custom display names in `configure({ weekdayNames })`. Format token `d` keeps `0` = Sunday through `6` = Saturday to match Moment and Day.js alongside `E` for ISO `1`-`7`. + +Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`. + +## D15: `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17) + +Blind naming reviewers guessed `normalize()` for cascading `90 minutes` into `1 hour 30 minutes` and preferred `hours(36).in('days')` for numeric conversion. Aliasing `normalize` to `balance` was rejected because Luxon's `Duration.prototype.normalize()` leaves `{ minutes: 90 }` unchanged instead of promoting into absent units, and `.in()` returns an object instance everywhere else (`datetime.in(zone)`, `monthDay.in(year)`, `range.in(zone)`). + +Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`. + +## D16: Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17) + +Cold readers misread `start.to(3, 'days')` as a unit conversion and ranked `start.for(3, 'days')` first (+10 B), which also avoids inclusive-end off-by-one math on `CalendarDate`. `.to()` still accepts durations because restricting `.to()` to endpoints would make `time('9am').to(8, 'hours')` parse `8` as `08:00` and return a 23-hour range, while `.through()` is limited to `CalendarDate` because `DateTimeRange` and `TimeRange` exclude their end. + +Reopen: callers pass endpoints to `.for()` expecting runtime rejection, or expect `.through()` on `DateTime` with inclusive end semantics. + +## D17: Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19) + +Overloading `next('month')` conflicts with `DateTime.prototype.next('friday')`, which preserves the time of day (`09:30`) while a unit boundary resets to `00:00`, and callers split on whether `next('month')` means the 1st of next month or `plus(1, 'month')`. Numeric weekdays are rejected in `startOfNext()` so misplaced counts like `startOfNext(2, 'months')` cannot silently resolve `2` as Tuesday. + +Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`. diff --git a/ai/contributing/decisions/project.md b/ai/contributing/decisions/project.md new file mode 100644 index 0000000..c513d6b --- /dev/null +++ b/ai/contributing/decisions/project.md @@ -0,0 +1,3 @@ +# Project Decisions + +> Append-only log (`P1`..`Pn`) governing repository process, CI gates, documentation workflow, and releases. Read [`README.md`](README.md) before adding an entry; package API and runtime behavior belong in [`package.md`](package.md), never here. diff --git a/ai/contributing/project-decisions.md b/ai/contributing/project-decisions.md deleted file mode 100644 index 3ffb5a7..0000000 --- a/ai/contributing/project-decisions.md +++ /dev/null @@ -1,5 +0,0 @@ -# Project Decisions: Repository and Process Log - -Append-only log of decisions governing how the repository, CI checks, documentation site, and releases operate. Package API and runtime semantics belong in [`decisions.md`](decisions.md), never here. Entries use the same dated format, confidence scores, and reopen conditions defined in [`decisions.md`](decisions.md). - ---- diff --git a/ai/contributing/workflows/clean-room-dx-review.md b/ai/contributing/workflows/clean-room-dx-review.md index 32fc884..8377f7f 100644 --- a/ai/contributing/workflows/clean-room-dx-review.md +++ b/ai/contributing/workflows/clean-room-dx-review.md @@ -60,6 +60,6 @@ Treat every finding as a hypothesis. Verify each claim against `src/` before pre After landing approved changes: -1. Record settled naming or signature choices in [`../decisions.md`](../decisions.md) so later rounds do not flip-flop on taste calls. +1. Record non-obvious naming or signature tradeoffs in [`../decisions/package.md`](../decisions/package.md) (following [`../decisions/README.md`](../decisions/README.md)) so later rounds do not flip-flop on taste calls. 2. Regenerate `ai/workspace/surface-capture.txt`. 3. If substantive API changes were merged, run a second round using a **brand-new** subagent with zero mention of round 1. Convergence shows up when round 1's fixes appear in round 2's "What must not change" list. diff --git a/tools/gates/decisions-index.js b/tools/gates/decisions-index.js index c3a3ad0..7e114f0 100644 --- a/tools/gates/decisions-index.js +++ b/tools/gates/decisions-index.js @@ -1,14 +1,14 @@ -// builds and checks ai/contributing/decisions-index.md from ai/contributing/decisions.md +// builds and checks ai/contributing/decisions.md from ai/contributing/decisions/package.md import { existsSync, readFileSync, writeFileSync } from 'node:fs'; import { dirname, relative, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); -const decisionsPath = resolve(root, 'ai/contributing/decisions.md'); -const indexPath = resolve(root, 'ai/contributing/decisions-index.md'); +const packagePath = resolve(root, 'ai/contributing/decisions/package.md'); +const indexPath = resolve(root, 'ai/contributing/decisions.md'); -const headingPattern = /^##\s+(.+?)\s+\((\d{4}-\d{2}-\d{2})\)\s*$/; +const headingPattern = /^##\s+D(\d+):\s+(.+?)\s+\((\d{4}-\d{2}-\d{2})\)\s*$/; const confidencePattern = /^\*(\d{1,3})%\s+confident\*$/i; const reopenPattern = /^Reopen:\s*(.+)$/i; const supersededPattern = /^Superseded by\s+(.+?)\.?\s*$/i; @@ -70,15 +70,24 @@ export function parseDecisions(source) { if (!line.startsWith('## ')) { return; } const parsed = headingPattern.exec(line); if (!parsed) { - findings.push(`L${index + 1}: expected '## ()' heading`); + findings.push(`L${index + 1}: expected '## D: ()' heading`); return; } - headings.push({ line: index + 1, title: parsed[1].trim(), date: parsed[2], anchor }); + const id = Number(parsed[1]); + const expectedId = headings.length + 1; + if (id !== expectedId) { + findings.push(`L${index + 1}: expected sequential ID D${expectedId}, got D${id}`); + } + headings.push({ id, line: index + 1, title: parsed[2].trim(), date: parsed[3], anchor }); }); const entries = headings.map((entry, index) => { - const nextLine = index + 1 < headings.length ? headings[index + 1].line - 1 : lines.length; - const paragraphs = paragraphsOf(lines.slice(entry.line, nextLine).join('\n')); + const bound = index + 1 < headings.length ? headings[index + 1].line - 1 : lines.length; + let endLine = bound; + while (endLine > entry.line && lines[endLine - 1].trim() === '') { + endLine--; + } + const paragraphs = paragraphsOf(lines.slice(entry.line, bound).join('\n')); let confidence = null; let reopen = ''; let supersededBy = ''; @@ -115,7 +124,7 @@ export function parseDecisions(source) { findings.push(`L${entry.line}: date ${entry.date} precedes earlier entry ${headings[index - 1].date}`); } - return { ...entry, confidence, reopen, supersededBy, topic }; + return { ...entry, endLine, confidence, reopen, supersededBy, topic }; }); return { entries, findings }; @@ -123,7 +132,8 @@ export function parseDecisions(source) { const formatItem = (entry) => { const stamp = entry.confidence === null ? entry.date : `${entry.date}, ${entry.confidence}% confident`; - const lines = [`- [L${entry.line}](decisions.md#${entry.anchor}) · ${entry.title} (${stamp})`]; + const range = `L${entry.line}-L${entry.endLine}`; + const lines = [`- **D${entry.id}:** ${entry.title} (${stamp}) [${range}](decisions/package.md#${entry.anchor})`]; if (entry.supersededBy) { lines.push(` - Superseded by ${entry.supersededBy}`); } @@ -135,20 +145,20 @@ const formatItem = (entry) => { export function renderDecisionsIndex(entries) { const out = [ - '# Decisions Index', + '# Decisions', '', - '> Generated from [`decisions.md`](decisions.md) by `npm run ai:index` and checked by `npm run ai`. Do not edit by hand.', + '> Generated from [`decisions/package.md`](decisions/package.md) by `npm run ai:index` and checked by `npm run ai`. Do not edit by hand. Read [`decisions/README.md`](decisions/README.md) before adding or reopening an entry (features and bug fixes do not belong here, and repo process calls belong in [`decisions/project.md`](decisions/project.md)).', '', '## By Topic', '', - 'Active decisions grouped by area, newest first.', + 'Active package decisions grouped by area, newest first.', '', ]; for (const [name] of topicGroups) { const matching = entries .filter((entry) => entry.topic === name && !entry.supersededBy) - .sort((a, b) => b.date.localeCompare(a.date) || b.line - a.line); + .sort((a, b) => b.date.localeCompare(a.date) || b.id - a.id); if (!matching.length) { continue; } out.push(`### ${name}`, ''); for (const entry of matching) { @@ -157,7 +167,7 @@ export function renderDecisionsIndex(entries) { out.push(''); } - out.push('## Chronological', '', 'Every entry in file order.', ''); + out.push('## Chronological', '', 'Every package decision (`D1`..`Dn`) in file order.', ''); for (const entry of entries) { out.push(formatItem(entry)); } @@ -166,22 +176,22 @@ export function renderDecisionsIndex(entries) { } export function checkDecisions( - source = readFileSync(decisionsPath, 'utf8'), + source = readFileSync(packagePath, 'utf8'), indexSource = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : '', ) { const { entries, findings } = parseDecisions(source); - const issues = findings.map((finding) => `ai/contributing/decisions.md: ${finding}`); + const issues = findings.map((finding) => `ai/contributing/decisions/package.md: ${finding}`); if (!findings.length && indexSource !== renderDecisionsIndex(entries)) { - issues.push('ai/contributing/decisions-index.md: stale index (run `npm run ai:index`)'); + issues.push('ai/contributing/decisions.md: stale index (run `npm run ai:index`)'); } return issues; } if (process.argv[1] === fileURLToPath(import.meta.url)) { - const { entries, findings } = parseDecisions(readFileSync(decisionsPath, 'utf8')); + const { entries, findings } = parseDecisions(readFileSync(packagePath, 'utf8')); if (findings.length) { for (const finding of findings) { - console.error(` x ai/contributing/decisions.md: ${finding}`); + console.error(` x ai/contributing/decisions/package.md: ${finding}`); } process.exitCode = 1; } diff --git a/tools/gates/decisions-index.test.js b/tools/gates/decisions-index.test.js index 9b92d7d..65a7938 100644 --- a/tools/gates/decisions-index.test.js +++ b/tools/gates/decisions-index.test.js @@ -4,15 +4,15 @@ import { checkDecisions, parseDecisions, renderDecisionsIndex } from './decision describe('decisions-index', () => { const sample = [ - '# Decisions', + '# Package Decisions', '', - '## `DateRange` includes its end date while `TimeRange` is half-open (2026-11-10)', + '## D1: `DateRange` includes its end date while `TimeRange` is half-open (2026-11-10)', '', 'Old range entry.', '', - 'Superseded by 2026-11-12.', + 'Superseded by D2 (2026-11-12).', '', - '## `DateRange` includes its end date and `TimeRange` wraps midnight (2026-11-12)', + '## D2: `DateRange` includes its end date and `TimeRange` wraps midnight (2026-11-12)', '', '*90% confident*', '', @@ -20,7 +20,7 @@ describe('decisions-index', () => { '', 'Reopen: callers hit off-by-one bugs when converting ranges.', '', - '## `Duration` uses `balance()` without a `normalize()` alias (2026-11-17)', + '## D3: `Duration` uses `balance()` without a `normalize()` alias (2026-11-17)', '', 'Luxon `normalize()` leaves `{ minutes: 90 }` unchanged.', '', @@ -28,37 +28,42 @@ describe('decisions-index', () => { '', ].join('\n'); - it('parses optional confidence lines, reopen clauses, and supersession notes into topic and file-order indexes', () => { + it('parses sequential D IDs, line ranges, confidence lines, reopen clauses, and supersessions', () => { const { entries, findings } = parseDecisions(sample); expect(findings).toEqual([]); - expect(entries.map((entry) => [entry.topic, entry.confidence, Boolean(entry.supersededBy)])).toEqual([ - ['Ranges', null, true], - ['Ranges', 90, false], - ['Durations', null, false], + expect( + entries.map(( + entry, + ) => [entry.id, entry.line, entry.endLine, entry.topic, entry.confidence, Boolean(entry.supersededBy)]), + ).toEqual([ + [1, 3, 7, 'Ranges', null, true], + [2, 9, 15, 'Ranges', 90, false], + [3, 17, 21, 'Durations', null, false], ]); const rendered = renderDecisionsIndex(entries); - expect(rendered).toContain('### Ranges\n\n- [L9](decisions.md#'); - expect(rendered).toContain('(2026-11-12, 90% confident)'); + expect(rendered).toContain( + '### Ranges\n\n- **D2:** `DateRange` includes its end date and `TimeRange` wraps midnight (2026-11-12, 90% confident) [L9-L15](decisions/package.md#', + ); // superseded entries appear only in the chronological section - expect(rendered.split('## Chronological')[0]).not.toContain('2026-11-10'); - expect(rendered.split('## Chronological')[1]).toContain('Superseded by 2026-11-12'); + expect(rendered.split('## Chronological')[0]).not.toContain('**D1:**'); + expect(rendered.split('## Chronological')[1]).toContain('Superseded by D2 (2026-11-12)'); expect(checkDecisions(sample, rendered)).toEqual([]); }); - it('flags malformed headings, out-of-order dates, missing reopen lines, unsorted titles, and stale indexes', () => { + it('flags malformed headings, non-sequential IDs, out-of-order dates, missing reopen lines, unsorted titles, and stale indexes', () => { const broken = [ - '# Decisions', + '# Package Decisions', '', - '## Missing date heading', + '## Missing ID and date', '', - '## `Duration` uses `balance()` (2026-11-18)', + '## D3: `Duration` uses `balance()` (2026-11-18)', '', '*120% confident*', '', 'Body without reopen.', '', - '## Unmatched widget knob (2026-11-15)', + '## D2: Unmatched widget knob (2026-11-15)', '', 'Body.', '', @@ -66,15 +71,16 @@ describe('decisions-index', () => { ].join('\n'); expect(checkDecisions(broken, '')).toEqual([ - "ai/contributing/decisions.md: L3: expected '## ()' heading", - "ai/contributing/decisions.md: L5: confidence line must lead the entry as '*0-100% confident*'", - "ai/contributing/decisions.md: L5: missing 'Reopen: ' line", - "ai/contributing/decisions.md: L11: no topic group matched 'Unmatched widget knob'", - 'ai/contributing/decisions.md: L11: date 2026-11-15 precedes earlier entry 2026-11-18', + "ai/contributing/decisions/package.md: L3: expected '## D: ()' heading", + 'ai/contributing/decisions/package.md: L5: expected sequential ID D1, got D3', + "ai/contributing/decisions/package.md: L5: confidence line must lead the entry as '*0-100% confident*'", + "ai/contributing/decisions/package.md: L5: missing 'Reopen: ' line", + "ai/contributing/decisions/package.md: L11: no topic group matched 'Unmatched widget knob'", + 'ai/contributing/decisions/package.md: L11: date 2026-11-15 precedes earlier entry 2026-11-18', ]); expect(checkDecisions(sample, 'stale')).toEqual([ - 'ai/contributing/decisions-index.md: stale index (run `npm run ai:index`)', + 'ai/contributing/decisions.md: stale index (run `npm run ai:index`)', ]); }); }); From a599b49899e4fba8f4b3abffa4e59353a60b782a Mon Sep 17 00:00:00 2001 From: Jack Lukic Date: Fri, 20 Nov 2026 17:05:44 -0500 Subject: [PATCH 2/4] Harness: Split human setup from agent curriculum.md --- AGENTS.md | 31 ++----------------- CONTRIBUTING.md | 24 +++++---------- ai/contributing/README.md | 2 ++ ai/contributing/curriculum.md | 40 +++++++++++++++++++++++++ ai/contributing/workflows/contribute.md | 13 +------- package.json | 1 + 6 files changed, 54 insertions(+), 57 deletions(-) create mode 100644 ai/contributing/curriculum.md diff --git a/AGENTS.md b/AGENTS.md index 5e86c9f..2f7fa9a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,8 @@ # Working in `native-dates` -Read [`ai/contributing/README.md`](ai/contributing/README.md) first for the contributor routing table (`ai/skills/` is reserved for downstream user skills published with the npm package, while `ai/contributing/` holds internal repository records). +Read [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md) before authoring or editing code (`ai/skills/` is reserved for downstream user skills published with the npm package, while [`ai/contributing/`](ai/contributing/README.md) holds internal agent context and repository records). -**Fixing or reporting a bug, or adding a feature?** Read [`CONTRIBUTING.md`](CONTRIBUTING.md), then load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) for the reading order, workflow steps, and human-author requirements. - -Before authoring or editing code in this repository, read: - -1. **[`ai/contributing/north-star.md`](ai/contributing/north-star.md)**: Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings. Read with the weight of a live user turn, and never edit or polish its human voice. -2. **[`ai/contributing/standards/lessons/naming-lessons.md`](ai/contributing/standards/lessons/naming-lessons.md)**: Hand-authored by the maintainer on callsite legibility, plain industry terms over metaphors, function signatures, and naming. Read with the weight of a live user turn. -3. **[`ai/contributing/standards/lessons/simplicity-lessons.md`](ai/contributing/standards/lessons/simplicity-lessons.md)**: Mental-model simplicity over clever mechanisms, synthetic adapters, or cross-module monkey-patching. -4. **[`ai/contributing/standards/coding-standards.md`](ai/contributing/standards/coding-standards.md)** and **[`ai/contributing/standards/code-comments.md`](ai/contributing/standards/code-comments.md)**: Class anatomy with `Symbol.for` branding, plus folder homogeneity and comment standards. -5. **[`ai/contributing/reference/architecture.md`](ai/contributing/reference/architecture.md)**: Package boundaries across `native-dates` (`src/`), `@native-dates/plugins` (`packages/plugins/`), `@native-dates/polyfill` (`packages/polyfill/`), and `ai/skills/`, plus invariants and size measurement. -6. **[`ai/contributing/budget.md`](ai/contributing/budget.md)**: Bundle ceilings, per-PR byte limits, and the size budget rules. -7. **[`ai/contributing/decisions.md`](ai/contributing/decisions.md)**: Generated topic and chronological index of package design decisions (`D1`..`Dn`), linking into [`ai/contributing/decisions/package.md`](ai/contributing/decisions/package.md). Grep the noun you are about to touch and check the latest entry. - -Load task-specific guides when relevant: - -- **[`ai/contributing/decisions/README.md`](ai/contributing/decisions/README.md)**: Adding or reopening a decision in `decisions/package.md` or `decisions/project.md` (what belongs vs. normal features and bug fixes, `D` format, and confidence calibration). -- **[`ai/contributing/standards/legibility/`](ai/contributing/standards/legibility/README.md)**: Craft guides for `code-structures`, `errors-and-logs`, `folders-and-filenames`, `tests-and-test-names`, and `traces-and-timelines`. Paths in those files reference the upstream repo they were written in, while the rules apply here. -- **[`ai/contributing/workflows/author-user-skill.md`](ai/contributing/workflows/author-user-skill.md)** and **[`ai/contributing/standards/ai-author-context.md`](ai/contributing/standards/ai-author-context.md)**: Authoring, chunking, and evaluating downstream user skills in `ai/skills/`. -- **[`ai/contributing/workflows/clean-room-dx-review.md`](ai/contributing/workflows/clean-room-dx-review.md)**: Running a quarantined fresh-reader DX review over candidate public API surface. -- **[`ai/contributing/workflows/read-ci-reports.md`](ai/contributing/workflows/read-ci-reports.md)**: Interpreting Bundle Size and Bench pull request comments (`Unsure` is unresolved noise, and within budget does not mean free). -- **[`ai/contributing/workflows/extend-bench-suite.md`](ai/contributing/workflows/extend-bench-suite.md)**: Adding or modifying benchmark operations in `bench/`. -- **[`ai/contributing/workflows/docs-writing.md`](ai/contributing/workflows/docs-writing.md)**: Writing or editing guide, API, or plugin pages under `docs/src/content/`. -- **[`ai/contributing/workflows/docs-authoring.md`](ai/contributing/workflows/docs-authoring.md)**: Updating the Astro docs site and its required features. -- **[`ai/contributing/workflows/docs-i18n.md`](ai/contributing/workflows/docs-i18n.md)**: Translating finalized documentation before a release or changing locale routing. -- **[`ai/contributing/standards/name-public-api.md`](ai/contributing/standards/name-public-api.md)** and **[`ai/contributing/standards/author-pull-requests.md`](ai/contributing/standards/author-pull-requests.md)**: Naming public API symbols and titling pull requests. -- **[`ai/contributing/standards/types.md`](ai/contributing/standards/types.md)**: Hand-authoring `.d.ts` files in `types/` and `packages/plugins/types/`. Their doc comments power editor hover/autocomplete, and each `@see` link opens the matching docs page on `nativedates.dev`. -- **[`ai/contributing/standards/utility-functions.md`](ai/contributing/standards/utility-functions.md)**: Reference for `@semantic-ui/utils`. **`native-dates` has zero runtime dependencies** — never install or import `@semantic-ui/utils`; check here for canonical names and behavior, then copy only the minimal reached implementation into `src/helpers/utils.js` or `src/helpers/environment.js`. - -Files in [`ai/contributing/standards/`](ai/contributing/standards/README.md) are synced from upstream Semantic repositories. Some internal links reference skills outside this repo, and those files are not edited directly here. +**Fixing or reporting a bug, or adding a feature?** Read [`CONTRIBUTING.md`](CONTRIBUTING.md), follow [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md), and load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) for the workflow steps and human-author requirements. ## House Rules diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97b8e08..9fc5725 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,21 +7,14 @@ Short guide for contributors and coding agents working on their behalf. | Goal | Starting point | |---|---| | Report a bug | Follow [Bug Reports](#4-bug-reports) | -| Fix a bug | Complete [Required Reading](#2-required-reading), then open a pull request | +| Fix a bug | Check [Before Coding](#2-before-coding), then open a pull request | | Add a feature or change public exports | Open an issue first to agree on scope and API before writing code | | Fix a typo or broken link | Open a pull request directly | -## 2. Required Reading +## 2. Before Coding -Read these files in order so new code matches existing conventions: - -1. [`ai/contributing/north-star.md`](ai/contributing/north-star.md): hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings -2. [`ai/contributing/standards/lessons/naming-lessons.md`](ai/contributing/standards/lessons/naming-lessons.md) and [`ai/contributing/standards/lessons/simplicity-lessons.md`](ai/contributing/standards/lessons/simplicity-lessons.md): callsite design, naming, and mental-model simplicity across Semantic packages -3. [`ai/contributing/standards/coding-standards.md`](ai/contributing/standards/coding-standards.md) and [`ai/contributing/standards/code-comments.md`](ai/contributing/standards/code-comments.md) -4. [`ai/contributing/budget.md`](ai/contributing/budget.md): bundle size ceilings and per-PR limits -5. [`ai/contributing/decisions.md`](ai/contributing/decisions.md): prior design decisions and reopen conditions - -**Using a coding agent?** Point it at [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) for the workflow and handoff checklist. +- **Human developers:** Scan [`ai/contributing/decisions.md`](ai/contributing/decisions.md) (and [`ai/contributing/decisions/project.md`](ai/contributing/decisions/project.md) for repo process) to see prior design decisions on the area you are touching, and run `npm install` so the pre-commit hook formats staged files with `dprint` automatically. You do not need to read the agent curriculum files under `ai/contributing/`. +- **Coding agents:** Read [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md) before working, and load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) when assisting on an issue or pull request. ## 3. Pull Requests @@ -29,8 +22,8 @@ Read these files in order so new code matches existing conventions: - **Description:** Fill out the [PR template](.github/pull_request_template.md) in your own words. One sentence of context and a few bullets is usually enough. - **Single scope:** Separate bug fixes and refactors into independent pull requests. - **Regression test:** Include a test that failed before the fix. Back up any size or performance claim with measurements. -- **Size budget:** The Bundle Size check compares production Brotli sizes against [`ai/contributing/budget.md`](ai/contributing/budget.md). Bug fixes aim for 0 added bytes. If a change exceeds the budget, follow the options in `ai/contributing/budget.md` (see [`ai/contributing/workflows/read-ci-reports.md`](ai/contributing/workflows/read-ci-reports.md)). -- **Checks and formatting:** Run `npm run check`, `npm run types`, `npm run errors`, `npm run comments`, and `npm run format`, or run `npm run setup` once to install git hooks. +- **Size budget:** The Bundle Size check compares production Brotli sizes against [`ai/contributing/budget.md`](ai/contributing/budget.md). Bug fixes aim for 0 added bytes. +- **Checks and formatting:** `npm install` sets up git hooks that run `dprint` on staged files. Run `npm run check` and `npm run types` before opening a pull request. ## 4. Bug Reports @@ -61,12 +54,11 @@ Every pull request in this repository is reviewed and merged by a human maintain ## Local Setup ```sh -npm install # install all workspaces -npm run setup # install git hooks once +npm install # install workspaces and git hooks (dprint on commit) npm run docs # start docs dev server npm run check # run tests, ai markdown checks, and bundle size budget npm run types # type-check .d.ts declarations npm run errors # check error prose register npm run comments # check comment density and voice -npm run format # format with dprint +npm run format # format all files with dprint ``` diff --git a/ai/contributing/README.md b/ai/contributing/README.md index c36e126..384dd74 100644 --- a/ai/contributing/README.md +++ b/ai/contributing/README.md @@ -6,6 +6,7 @@ Internal records and workflows for developing `native-dates`. Application develo | Task | Reading order | |---|---| +| Onboard a coding agent before working | [`curriculum.md`](curriculum.md) (stages 1–4) | | Fix a bug, add a feature, or file a bug report | [`CONTRIBUTING.md`](../../CONTRIBUTING.md), then [`workflows/contribute.md`](workflows/contribute.md) | | Check or record design and process decisions | [`decisions.md`](decisions.md) for the topic index, [`decisions/README.md`](decisions/README.md) before adding or reopening an entry, [`decisions/package.md`](decisions/package.md) (`D1`..`Dn`), and [`decisions/project.md`](decisions/project.md) (`P1`..`Pn`) | | Check bundle size limits | [`budget.md`](budget.md), checked by `npm run size` | @@ -24,6 +25,7 @@ Internal records and workflows for developing `native-dates`. Application develo | Record | Path | Policy | |---|---|---| +| Agent curriculum | [`curriculum.md`](curriculum.md) | Ordered 4-stage reading list for coding agents (not required for human developers) | | North star | [`north-star.md`](north-star.md) | Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings (do not edit or polish) | | Decisions index | [`decisions.md`](decisions.md) | Generated topic and chronological index of package decisions (`npm run ai:index`) | | Decision logs | [`decisions/`](decisions/README.md) | Authoring rules in `README.md`, package rationales in `package.md` (`D1`..`Dn`), and repo/CI process calls in `project.md` (`P1`..`Pn`) | diff --git a/ai/contributing/curriculum.md b/ai/contributing/curriculum.md new file mode 100644 index 0000000..f8d71c5 --- /dev/null +++ b/ai/contributing/curriculum.md @@ -0,0 +1,40 @@ +# Agent Curriculum + +Required reading order for coding agents before authoring or modifying code in `native-dates`. Human contributors do not need to read these context files (see [`CONTRIBUTING.md`](../../CONTRIBUTING.md)). + +## 1. Goals and Maintainer Lessons + +Hand-authored by the maintainer in his own voice. Read with the weight of a live user turn, and never edit or polish them: + +1. **[`north-star.md`](north-star.md)**: Project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings. +2. **[`standards/lessons/naming-lessons.md`](standards/lessons/naming-lessons.md)**: Callsite legibility, plain industry terms over metaphors, function signatures, and naming. +3. **[`standards/lessons/simplicity-lessons.md`](standards/lessons/simplicity-lessons.md)**: Mental-model simplicity over synthetic adapters or cross-module monkey-patching. + +## 2. Architecture, Decisions, and Budget + +Check package boundaries and constraints before designing a change: + +1. **[`reference/architecture.md`](reference/architecture.md)**: Boundaries across `native-dates` (`src/`), `@native-dates/plugins` (`packages/plugins/`), `@native-dates/polyfill` (`packages/polyfill/`), and `ai/skills/`, plus zero-dependency invariants. +2. **[`decisions.md`](decisions.md)**: Topic and chronological index (`D1`..`Dn`) linking into [`decisions/package.md`](decisions/package.md). Grep the noun you are touching, and read [`decisions/README.md`](decisions/README.md) before recording or reopening a decision. +3. **[`budget.md`](budget.md)**: Brotli ceilings, per-PR byte limits, and zero-prose production bundle rules (`npm run size`). + +## 3. Code, Comments, Errors, and Types + +Match codebase structure and static gates (`npm run comments`, `npm run errors`, `npm run types`): + +1. **[`standards/coding-standards.md`](standards/coding-standards.md)** and **[`standards/code-comments.md`](standards/code-comments.md)**: Class anatomy with `Symbol.for` branding, folder homogeneity, and intent-only comments. +2. **[`standards/legibility/`](standards/legibility/README.md)**: Craft guides for [`errors-and-logs.md`](standards/legibility/errors-and-logs.md), [`tests-and-test-names.md`](standards/legibility/tests-and-test-names.md), [`code-structures.md`](standards/legibility/code-structures.md), [`folders-and-filenames.md`](standards/legibility/folders-and-filenames.md), and [`traces-and-timelines.md`](standards/legibility/traces-and-timelines.md). +3. **[`standards/utility-functions.md`](standards/utility-functions.md)**: Canonical `@semantic-ui/utils` signatures (`native-dates` has zero runtime dependencies, so copy only minimal used branches into `src/helpers/utils.js` or `src/helpers/environment.js`). +4. **[`standards/types.md`](standards/types.md)**: Hand-authored `.d.ts` declarations in `types/` and `packages/plugins/types/` with `@see` links to `nativedates.dev`. + +Files in [`standards/`](standards/README.md) are synced from upstream Semantic repositories and are not edited directly here. + +## 4. Task-Specific Workflows + +Load only the guides relevant to your current task, then read the target source files and tests directly on `HEAD`: + +- **Bug fixes, features, and PRs:** [`workflows/contribute.md`](workflows/contribute.md), [`standards/name-public-api.md`](standards/name-public-api.md), [`standards/author-pull-requests.md`](standards/author-pull-requests.md), [`workflows/read-ci-reports.md`](workflows/read-ci-reports.md), and [`workflows/clean-room-dx-review.md`](workflows/clean-room-dx-review.md) +- **Decisions:** [`decisions/README.md`](decisions/README.md) (what belongs vs. normal features and bug fixes) +- **Documentation and i18n (`docs/`):** [`workflows/docs-writing.md`](workflows/docs-writing.md), [`workflows/docs-authoring.md`](workflows/docs-authoring.md), and [`workflows/docs-i18n.md`](workflows/docs-i18n.md) +- **Downstream user skills (`ai/skills/`):** [`workflows/author-user-skill.md`](workflows/author-user-skill.md) and [`standards/ai-author-context.md`](standards/ai-author-context.md) +- **Benchmarks (`bench/`):** [`workflows/extend-bench-suite.md`](workflows/extend-bench-suite.md) diff --git a/ai/contributing/workflows/contribute.md b/ai/contributing/workflows/contribute.md index 5fb6982..5daef61 100644 --- a/ai/contributing/workflows/contribute.md +++ b/ai/contributing/workflows/contribute.md @@ -26,18 +26,7 @@ Every issue and pull request has a human author accountable for the submission ( ## Required Reading Order -Read these documents before editing code: - -1. [`ai/contributing/north-star.md`](../north-star.md): hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings. -2. [`ai/contributing/standards/lessons/naming-lessons.md`](../standards/lessons/naming-lessons.md): maintainer-authored lessons on callsite signatures, industry terms over metaphors, and naming. -3. [`ai/contributing/standards/lessons/simplicity-lessons.md`](../standards/lessons/simplicity-lessons.md): class boundaries and simple data flow over synthetic adapters or monkey-patching. -4. [`ai/contributing/standards/coding-standards.md`](../standards/coding-standards.md) and [`ai/contributing/standards/code-comments.md`](../standards/code-comments.md): class anatomy, `Symbol.for` branding, folder homogeneity, and comment style. -5. [`ai/contributing/reference/architecture.md`](../reference/architecture.md): workspace package responsibilities, zero-dependency rules, and invariants. -6. [`ai/contributing/budget.md`](../budget.md): bundle ceilings and per-PR byte limits. -7. [`ai/contributing/standards/legibility/errors-and-logs.md`](../standards/legibility/errors-and-logs.md): required whenever adding or editing error explanations (`npm run errors`). -8. [`ai/contributing/decisions.md`](../decisions.md): grep the relevant noun and read the latest dated decision. Surface a decision to reopen when its `reopen:` condition is met or new counter-evidence appears rather than silently overriding it. - -Next, read the target source files and tests directly on `HEAD` rather than relying on prior assumptions. +Complete stages 1–3 of [`ai/contributing/curriculum.md`](../curriculum.md) (and load any relevant stage 4 workflows) before editing code, then read the target source files and tests directly on `HEAD` rather than relying on prior assumptions. Surface a decision to reopen when its `Reopen:` condition is met or new counter-evidence appears rather than silently overriding it. ## Fixing a Bug diff --git a/package.json b/package.json index 4298e3e..872e7a3 100644 --- a/package.json +++ b/package.json @@ -42,6 +42,7 @@ "types": "tsc --noEmit && tsc --noEmit --module preserve --moduleResolution bundler", "check": "npm test && npm run ai && npm run size", "format": "npx dprint fmt", + "prepare": "simple-git-hooks", "setup": "npx simple-git-hooks" }, "devDependencies": { From 52436694ba55fb454bcc4a9bf453eef16c5bf88e Mon Sep 17 00:00:00 2001 From: Jack Lukic Date: Fri, 20 Nov 2026 17:07:09 -0500 Subject: [PATCH 3/4] Chore: Trim redundant human-reading disclaimer --- CONTRIBUTING.md | 2 +- ai/contributing/README.md | 2 +- ai/contributing/curriculum.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9fc5725..12084cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ Short guide for contributors and coding agents working on their behalf. ## 2. Before Coding -- **Human developers:** Scan [`ai/contributing/decisions.md`](ai/contributing/decisions.md) (and [`ai/contributing/decisions/project.md`](ai/contributing/decisions/project.md) for repo process) to see prior design decisions on the area you are touching, and run `npm install` so the pre-commit hook formats staged files with `dprint` automatically. You do not need to read the agent curriculum files under `ai/contributing/`. +- **Human developers:** Scan [`ai/contributing/decisions.md`](ai/contributing/decisions.md) (and [`ai/contributing/decisions/project.md`](ai/contributing/decisions/project.md) for repo process) to see prior design decisions on the area you are touching, and run `npm install` so the pre-commit hook formats staged files with `dprint` automatically. - **Coding agents:** Read [`ai/contributing/curriculum.md`](ai/contributing/curriculum.md) before working, and load [`ai/contributing/workflows/contribute.md`](ai/contributing/workflows/contribute.md) when assisting on an issue or pull request. ## 3. Pull Requests diff --git a/ai/contributing/README.md b/ai/contributing/README.md index 384dd74..6e7d76a 100644 --- a/ai/contributing/README.md +++ b/ai/contributing/README.md @@ -25,7 +25,7 @@ Internal records and workflows for developing `native-dates`. Application develo | Record | Path | Policy | |---|---|---| -| Agent curriculum | [`curriculum.md`](curriculum.md) | Ordered 4-stage reading list for coding agents (not required for human developers) | +| Agent curriculum | [`curriculum.md`](curriculum.md) | Ordered 4-stage reading list for coding agents | | North star | [`north-star.md`](north-star.md) | Hand-authored by the maintainer on project goals, the Golden Rule, call-site SNR, lowercase-"c" correctness, conciseness, and Bayesian rulings (do not edit or polish) | | Decisions index | [`decisions.md`](decisions.md) | Generated topic and chronological index of package decisions (`npm run ai:index`) | | Decision logs | [`decisions/`](decisions/README.md) | Authoring rules in `README.md`, package rationales in `package.md` (`D1`..`Dn`), and repo/CI process calls in `project.md` (`P1`..`Pn`) | diff --git a/ai/contributing/curriculum.md b/ai/contributing/curriculum.md index f8d71c5..cf2345d 100644 --- a/ai/contributing/curriculum.md +++ b/ai/contributing/curriculum.md @@ -1,6 +1,6 @@ # Agent Curriculum -Required reading order for coding agents before authoring or modifying code in `native-dates`. Human contributors do not need to read these context files (see [`CONTRIBUTING.md`](../../CONTRIBUTING.md)). +Required reading order for coding agents before authoring or modifying code in `native-dates` (see [`CONTRIBUTING.md`](../../CONTRIBUTING.md)). ## 1. Goals and Maintainer Lessons From 51c38747f168ee26f898e280361f1bc7020d7c76 Mon Sep 17 00:00:00 2001 From: Jack Lukic Date: Fri, 20 Nov 2026 17:11:14 -0500 Subject: [PATCH 4/4] Chore: Say contributor rather than maintainer on confidence scores --- ai/contributing/decisions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/contributing/decisions/README.md b/ai/contributing/decisions/README.md index cd7f2eb..f8c5cf4 100644 --- a/ai/contributing/decisions/README.md +++ b/ai/contributing/decisions/README.md @@ -41,6 +41,6 @@ Append new entries to the bottom of [`package.md`](package.md) (next `D`) or Reopen: observable condition that justifies revisiting this call. ``` -- **Confidence line (`*0-100% confident*`):** Optional probability assigned by the maintainer at decision time; omit the line when unscored. Calibrated scores reflect actual reversal odds rather than finality: a `70%` call expects roughly 3 in 10 such calls to flip with new evidence, and a `90%` call still expects 1 in 10 to prove wrong (`~60-75%` working tradeoff, `<50%` provisional default). +- **Confidence line (`*0-100% confident*`):** Optional probability decided by the contributor at decision time (omit the line when unscored). Calibrated scores reflect actual reversal odds rather than finality: a `70%` call expects roughly 3 in 10 such calls to flip with new evidence, and a `90%` call still expects 1 in 10 to prove wrong (`~60-75%` working tradeoff, `<50%` provisional default). - **Superseding an earlier entry:** Append the new `D` entry at the bottom and replace the earlier entry's `Reopen:` line with `Superseded by D ().` so history stays intact while the topic index shows only active calls. - **Reopening:** Surface an entry to reopen whenever concrete evidence shows its `Reopen:` condition has been met, exposes a tradeoff not weighed in the entry, or reveals a clear usability hazard.