From f8b262dc123dff82ebe00bb9120903526ad50d76 Mon Sep 17 00:00:00 2001
From: Gustavo Freze <gustavo.freze@outlook.com>
Date: Thu, 23 Jul 2026 17:49:20 -0300
Subject: [PATCH] feat: Add month and year arithmetic to LocalDate and Instant.

The new plusMonths, minusMonths, plusYears, and minusYears methods clamp
to the last valid day of the target month, and on Instant they reanchor
through a timezone before normalizing back to UTC. Shifts crossing the
supported 0001 to 9999 range raise InvalidLocalDate. This change also
adopts the Slevomat coding standard and migrates phpcs to it.
---
 .claude/hooks/php-ordering-conformance.py     | 609 ++++++++++++++++++
 .../php-prose-punctuation-conformance.py      | 203 ++++++
 .claude/rules/php-library-code-style.md       |  48 +-
 .claude/rules/php-library-tooling.md          |  27 +-
 .claude/settings.json                         |  17 +
 .claude/skills/tiny-blocks-create/SKILL.md    |   5 +-
 .../assets/config/.gitattributes              |   3 +
 .../assets/config/.gitignore                  |   2 +
 .../assets/config/composer.json               |   2 +
 .../assets/config/phpcs.xml                   |  88 ++-
 .gitattributes                                |   3 +
 .gitignore                                    |   2 +
 README.md                                     | 129 +++-
 composer.json                                 |   4 +-
 phpcs.xml                                     |  88 ++-
 phpstan.neon.dist                             |   4 +
 src/DayOfWeek.php                             |   6 +-
 src/Duration.php                              |   6 +-
 src/Elapsed.php                               |   2 +-
 src/Exceptions/InvalidLocalDate.php           |   5 +
 src/Instant.php                               | 112 +++-
 src/Internal/CalendarDay.php                  |  23 +
 src/Internal/Seconds.php                      |   4 +-
 src/Internal/ZonedShift.php                   |  30 +
 src/LocalDate.php                             | 116 +++-
 src/Stopwatch.php                             |   2 +-
 src/TimeOfDay.php                             |   4 +-
 src/Timezones.php                             |   2 +-
 tests/Unit/CalendarDayTest.php                |  25 +
 tests/Unit/DayOfWeekTest.php                  |   2 +-
 tests/Unit/DurationTest.php                   |   2 +-
 tests/Unit/InstantSerializationTest.php       |   2 +-
 tests/Unit/InstantTest.php                    | 225 ++++++-
 tests/Unit/LocalDateTest.php                  | 404 +++++++++++-
 tests/Unit/PeriodTest.php                     |   2 +-
 tests/Unit/SystemMonotonicClockTest.php       |   2 +-
 tests/Unit/TimeOfDayTest.php                  |   2 +-
 tests/Unit/ZonedShiftTest.php                 |  25 +
 38 files changed, 2067 insertions(+), 170 deletions(-)
 create mode 100644 .claude/hooks/php-ordering-conformance.py
 create mode 100644 .claude/hooks/php-prose-punctuation-conformance.py
 create mode 100644 src/Internal/CalendarDay.php
 create mode 100644 src/Internal/ZonedShift.php
 create mode 100644 tests/Unit/CalendarDayTest.php
 create mode 100644 tests/Unit/ZonedShiftTest.php

diff --git a/.claude/hooks/php-ordering-conformance.py b/.claude/hooks/php-ordering-conformance.py
new file mode 100644
index 0000000..cdabb98
--- /dev/null
+++ b/.claude/hooks/php-ordering-conformance.py
@@ -0,0 +1,609 @@
+#!/usr/bin/env python3
+"""PHP ordering conformance hook for tiny-blocks PHP libraries.
+
+Self-contained PostToolUse hook on Edit|Write|MultiEdit. Verifies the deterministic
+ordering conventions for PHP declarations:
+
+- Parameter ordering: declaration parameters (constructors, factories, methods,
+  property promotion) in three tiers, required parameters first, then defaulted
+  parameters, then a variadic, each tier by identifier length ascending,
+  alphabetical tie-breaker, semantic pairs preserved. A PHPUnit test method fed by
+  a data provider is exempt, its parameters are the columns of its data set.
+- Member ordering: constants, enum cases, constructor, static methods, instance
+  methods, in that group order, each group length-ascending with alphabetical
+  tie-breaker. PHPUnit test classes instead order methods as lifecycle hooks (in
+  execution order), then other methods, then data providers.
+
+The analysis is pure (FileUnit in, Violation out) and runs in three passes over
+well-formed PHP: a lexical pass blanks every comment, string, and heredoc/nowdoc
+body (LITERALS), a structural pass maps every bracket to its pair (bracket_spans);
+extraction assigns tokens of interest to their containers by flat walks. Control
+flow uses guard clauses only and nesting never exceeds two levels. Reports
+violations to stderr and exits 2 to prompt Claude, exits 0 silently if no violations
+or the file is out of scope.
+"""
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from functools import cached_property
+from pathlib import Path
+from typing import Final
+
+# --- Configuration ----------------------------------------------------------
+
+# In-scope files: PHP sources under src/ or tests/.
+SCOPE_PATTERN: Final = re.compile(r"(^|/)(src|tests)/.+\.php$")
+
+# Semantic groups. When two or more members of a group appear in the same parameter
+# list, they keep their natural order, sorting as a unit at the lead member's key.
+# Groups of arbitrary length are supported (calendar and clock components included).
+SEMANTIC_GROUPS: Final = (
+    ("start", "end"),
+    ("from", "to"),
+    ("startAt", "endAt"),
+    ("createdAt", "updatedAt"),
+    ("before", "after"),
+    ("min", "max"),
+    ("year", "month", "day"),
+    ("hour", "minute", "second", "nanosecond"),
+)
+
+# Each member maps to (lead, position, members). The members present in the same list
+# keep their natural intra-group order, sorting as a unit at the lead member's key.
+GROUP_MEMBER: Final = {
+    member: (group[0], position, group)
+    for group in SEMANTIC_GROUPS
+    for position, member in enumerate(group)
+}
+
+MODIFIERS: Final = ("abstract", "final", "private", "protected", "public", "static")
+
+# The lexical grammar: every PHP construct that must not be scanned as code.
+# Alternatives are ordered, the heredoc label closes via backreference.
+LITERALS: Final = re.compile(
+    r"""
+      /\*.*?\*/                                  # block comment
+    | //[^\n]*                                   # line comment
+    | \#(?!\[)[^\n]*                             # hash comment, never a #[ attribute
+    | <<<[ \t]*(?P<quote>['"]?)(?P<label>\w+)(?P=quote)[^\n]*\n
+      .*?\n[ \t]*(?P=label)\b                    # heredoc and nowdoc body
+    | '(?:\\.|[^'\\])*'                          # single-quoted string
+    | "(?:\\.|[^"\\])*"                          # double-quoted string
+    """,
+    re.DOTALL | re.MULTILINE | re.VERBOSE,
+)
+
+TYPE_DECLARATION: Final = re.compile(
+    r"^[ \t]*(?:(?:abstract|final|readonly)\s+)*(class|interface|trait|enum)\s+(\w+)",
+    re.MULTILINE,
+)
+FUNCTION_DECLARATION: Final = re.compile(r"\bfunction\s+&?(\w+)\s*\(")
+METHOD_LINE: Final = re.compile(
+    rf"^\s*((?:(?:{'|'.join(MODIFIERS)})\s+)+)function\s+&?(\w+)\s*\("
+)
+CONST_LINE: Final = re.compile(
+    r"^\s*(?:(?:final|private|protected|public)\s+)*const\s+(?:[?\w|&()\s]+\s)?(\w+)\s*="
+)
+CASE_LINE: Final = re.compile(r"^\s*case\s+(\w+)\s*[=;]")
+
+PARAMETER: Final = re.compile(r"\$(\w+)")
+VARIADIC: Final = re.compile(r"\.\.\.\s*\$")
+# A default assignment is a lone `=`, never `=>` in an array or arrow function,
+# never a comparison (`==`, `!=`, `<=`, `>=`).
+DEFAULT_ASSIGNMENT: Final = re.compile(r"(?<![=!<>])=(?![=>])")
+
+# PHPUnit lifecycle hooks in fixed execution order, with detection patterns for a
+# test class and for the data providers its methods reference.
+LIFECYCLE_ORDER: Final = ("setUpBeforeClass", "setUp", "tearDown", "tearDownAfterClass")
+LIFECYCLE_HOOKS: Final = frozenset(LIFECYCLE_ORDER)
+EXTENDS_TESTCASE: Final = re.compile(r"\bextends\s+\\?(?:\w+\\)*TestCase\b")
+DATA_PROVIDER_REFERENCE: Final = re.compile(
+    r"#\[\s*(?:\\?\w+\\)*DataProvider\s*\(\s*['\"](\w+)['\"]"
+    r"|@dataProvider\s+(\w+)"
+)
+
+MAX_ERRORS_REPORTED = 30
+
+
+# --- Types --------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One style violation at a source position."""
+
+    line: int
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {self.message}"
+
+
+@dataclass(frozen=True)
+class Source:
+    """PHP source with literals blanked out at their original positions."""
+
+    clean: str
+
+    @staticmethod
+    def blanked(literal: re.Match[str]) -> str:
+        """The matched literal as spaces, newlines preserved."""
+        return re.sub(r"[^\n]", " ", literal.group(0))
+
+    @classmethod
+    def from_php(cls, text: str) -> "Source":
+        """A source with every comment, string, and heredoc blanked out."""
+        return cls(clean=LITERALS.sub(cls.blanked, text))
+
+    def line_of(self, index: int) -> int:
+        """The 1-based line number of a character index."""
+        return self.clean.count("\n", 0, index) + 1
+
+
+@dataclass(frozen=True)
+class FileUnit:
+    """One file under analysis: its raw text and the blanked Source on demand."""
+
+    path: str
+    text: str
+
+    @cached_property
+    def source(self) -> Source:
+        """The PHP source with literals blanked, computed once per file."""
+        return Source.from_php(self.text)
+
+
+@dataclass(frozen=True)
+class Ordering:
+    """Sole owner of the parameter-ordering logic for one variant."""
+
+    group_member: dict[str, tuple[str, int, tuple[str, ...]]]
+
+    def sorted(self, names: list[str]) -> list[str]:
+        """The names in the required order."""
+        present = set(names)
+        return sorted(names, key=lambda name: self.key(name, present))
+
+    def key(self, name: str, present: set[str]) -> tuple[int, str, int]:
+        """Length, then alphabet, with every member of a present group at the lead key."""
+        entry = self.group_member.get(name)
+        if entry is not None:
+            lead, position, members = entry
+            if any(other in present for other in members if other != name):
+                return (len(lead), lead, position)
+        return (len(name), name, 0)
+
+
+PARAMETER_ORDERING: Final = Ordering(group_member=GROUP_MEMBER)
+MEMBER_ORDERING: Final = Ordering(group_member={})
+
+
+class MemberKind(Enum):
+    """Closed set of class-member groups in required declaration order.
+
+    Ranks 0 to 4 are the production families. A PHPUnit test class keeps the
+    const, case, constructor ranks then draws its methods from the test families
+    (5 to 7): lifecycle hooks, other methods, data providers. A class draws its
+    methods from one family set or the other, never both, so ranks stay monotonic.
+    """
+
+    CONSTANT = (0, "const")
+    CASE = (1, "case")
+    CONSTRUCTOR = (2, "constructor")
+    STATIC_METHOD = (3, "static method")
+    INSTANCE_METHOD = (4, "instance method")
+    LIFECYCLE = (5, "lifecycle hook")
+    METHOD = (6, "method")
+    DATA_PROVIDER = (7, "data provider")
+
+    @property
+    def rank(self) -> int:
+        return self.value[0]
+
+    @property
+    def label(self) -> str:
+        return self.value[1]
+
+    def precedes(self, other: "MemberKind") -> bool:
+        """Whether this group must appear before the other group."""
+        return self.rank < other.rank
+
+
+@dataclass(frozen=True)
+class Member:
+    """One classified class member at its declaration line."""
+
+    kind: MemberKind
+    line: int
+    name: str
+
+
+@dataclass(frozen=True)
+class TypeMembers:
+    """The members of one class-like declaration in source order."""
+
+    name: str
+    is_test: bool
+    members: list[Member]
+
+
+# Parameter ordering tiers: required first, then defaulted, then a variadic.
+REQUIRED_TIER: Final = 0
+DEFAULT_TIER: Final = 1
+VARIADIC_TIER: Final = 2
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """One declared parameter: its identifier and its ordering tier."""
+
+    name: str
+    tier: int
+
+
+@dataclass(frozen=True)
+class ParameterList:
+    """One declaration's parameters in source order."""
+
+    line: int
+    owner: str
+    params: list[Parameter]
+
+    @property
+    def names(self) -> list[str]:
+        return [parameter.name for parameter in self.params]
+
+    def in_tier(self, tier: int) -> list[str]:
+        return [parameter.name for parameter in self.params if parameter.tier == tier]
+
+    def required(self) -> list[str]:
+        ordered = PARAMETER_ORDERING.sorted(self.in_tier(REQUIRED_TIER))
+        ordered += PARAMETER_ORDERING.sorted(self.in_tier(DEFAULT_TIER))
+        return ordered + self.in_tier(VARIADIC_TIER)
+
+    def out_of_order(self) -> bool:
+        return len(self.params) >= 2 and self.names != self.required()
+
+
+# --- Structure ----------------------------------------------------------------
+
+
+def bracket_spans(text: str) -> dict[int, int]:
+    """Every opening bracket position mapped to its closing position."""
+    spans: dict[int, int] = {}
+    stack: list[int] = []
+
+    for position, character in enumerate(text):
+        if character in "([{":
+            stack.append(position)
+
+        if character in ")]}" and stack:
+            spans[stack.pop()] = position
+
+    return spans
+
+
+def top_level_pieces(text: str) -> list[str]:
+    """The comma-separated pieces of a list, ignoring nested separators."""
+    pieces, depth, current = [], 0, []
+    for character in text:
+        if character in "([{":
+            depth += 1
+
+        if character in ")]}":
+            depth -= 1
+
+        if character == "," and depth == 0:
+            pieces.append("".join(current))
+            current = []
+            continue
+        current.append(character)
+
+    tail = "".join(current).strip()
+
+    if tail:
+        pieces.append(tail)
+
+    return pieces
+
+
+# --- Extraction ---------------------------------------------------------------
+
+
+def declared_signatures(source: Source) -> list[ParameterList]:
+    """Every function or method declaration with its parameters."""
+    signatures = []
+    spans = bracket_spans(source.clean)
+
+    for match in FUNCTION_DECLARATION.finditer(source.clean):
+        open_paren = source.clean.index("(", match.end() - 1)
+        inner = source.clean[open_paren + 1: spans.get(open_paren, len(source.clean))]
+        params = [
+            parameter_of(piece)
+            for piece in top_level_pieces(inner)
+            if PARAMETER.search(piece)
+        ]
+
+        signatures.append(ParameterList(
+            line=source.line_of(match.start()),
+            owner=match.group(1),
+            params=params,
+        ))
+    return signatures
+
+
+def parameter_of(piece: str) -> Parameter:
+    """One parameter's identifier and ordering tier from its declaration piece."""
+    name = PARAMETER.findall(piece)[-1]
+
+    if VARIADIC.search(piece):
+        return Parameter(name=name, tier=VARIADIC_TIER)
+
+    if DEFAULT_ASSIGNMENT.search(piece):
+        return Parameter(name=name, tier=DEFAULT_TIER)
+    return Parameter(name=name, tier=REQUIRED_TIER)
+
+
+def class_members(unit: FileUnit) -> list[TypeMembers]:
+    """Every class-like declaration with its members in source order."""
+    declarations = []
+    clean = unit.source.clean
+    spans = bracket_spans(clean)
+
+    for type_match in TYPE_DECLARATION.finditer(clean):
+        body_open = clean.find("{", type_match.end())
+
+        if body_open == -1:
+            continue
+
+        body_close = spans.get(body_open, len(clean))
+        is_test = bool(EXTENDS_TESTCASE.search(clean[type_match.end(): body_open]))
+        providers = test_providers(unit.text[body_open + 1: body_close]) if is_test else set()
+        declarations.append(TypeMembers(
+            name=type_match.group(2),
+            is_test=is_test,
+            members=declared_members(
+                at_line=unit.source.line_of(body_open),
+                body=clean[body_open + 1: body_close],
+                is_test=is_test,
+                providers=providers,
+            ),
+        ))
+    return declarations
+
+
+def test_providers(raw_body: str) -> set[str]:
+    """Every method name a data-provider attribute or annotation references."""
+    names = set()
+    for match in DATA_PROVIDER_REFERENCE.finditer(raw_body):
+        names.add(match.group(1) or match.group(2))
+    return names
+
+
+def provider_consumer_lines(unit: FileUnit) -> set[int]:
+    """Declaration lines of the test methods a data provider feeds.
+
+    The consumer side of the data-provider relation: the method a
+    `#[DataProvider('name')]` attribute or `@dataProvider name` tag immediately
+    precedes. Its parameters are the columns of the data set, ordered by the data
+    rather than by name length, so the parameter check skips these lines. Detection
+    runs on the raw text, since the docblock form is blanked in the Source, then the
+    next declaration in the position-aligned Source fixes the line.
+    """
+    clean = unit.source.clean
+    lines = set()
+    for reference in DATA_PROVIDER_REFERENCE.finditer(unit.text):
+        method = FUNCTION_DECLARATION.search(clean, reference.end())
+        if not method:
+            continue
+        lines.add(unit.source.line_of(method.start()))
+    return lines
+
+
+def declared_members(at_line: int, body: str, is_test: bool, providers: set[str]) -> list[Member]:
+    """The members declared at the top level of one type body."""
+    members, depth = [], 0
+    for offset, line in enumerate(body.split("\n")):
+        member = classified(at=at_line + offset, line=line, is_test=is_test, providers=providers)
+        if depth == 0 and member:
+            members.append(member)
+        depth += line.count("{") - line.count("}")
+    return members
+
+
+def classified(at: int, line: str, is_test: bool, providers: set[str]) -> Member | None:
+    """The member a line declares, when it declares one."""
+    method = METHOD_LINE.match(line)
+    if method:
+        name = method.group(2)
+        if name == "__construct":
+            return Member(kind=MemberKind.CONSTRUCTOR, line=at, name=name)
+
+        if is_test:
+            return Member(kind=test_method_kind(name=name, providers=providers), line=at, name=name)
+
+        if "static" in method.group(1).split():
+            return Member(kind=MemberKind.STATIC_METHOD, line=at, name=name)
+        return Member(kind=MemberKind.INSTANCE_METHOD, line=at, name=name)
+
+    constant = CONST_LINE.match(line)
+
+    if constant:
+        return Member(kind=MemberKind.CONSTANT, line=at, name=constant.group(1))
+    case = CASE_LINE.match(line)
+
+    if case:
+        return Member(kind=MemberKind.CASE, line=at, name=case.group(1))
+    return None
+
+
+def test_method_kind(name: str, providers: set[str]) -> MemberKind:
+    """The method family a name takes inside a PHPUnit test class."""
+    if name in LIFECYCLE_HOOKS:
+        return MemberKind.LIFECYCLE
+
+    if name in providers:
+        return MemberKind.DATA_PROVIDER
+    return MemberKind.METHOD
+
+
+# --- Checks -------------------------------------------------------------------
+
+
+def parameter_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Parameter ordering on every declaration a data provider does not feed."""
+    exempt = provider_consumer_lines(unit)
+    return tuple(
+        Violation(
+            line=signature.line,
+            path=unit.path,
+            message=(
+                f"parameter order in `{signature.owner}()` is "
+                f"({', '.join(signature.names)}), "
+                f"required ({', '.join(signature.required())})"
+            ),
+        )
+
+        for signature in declared_signatures(unit.source)
+        if signature.line not in exempt and signature.out_of_order()
+    )
+
+
+def member_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Member ordering on group sequence and order within each group."""
+    violations: list[Violation] = []
+    for declared in class_members(unit):
+        violations.extend(group_sequence_violations(path=unit.path, declared=declared))
+        violations.extend(within_group_violations(path=unit.path, declared=declared))
+    return tuple(violations)
+
+
+def group_sequence_violations(path: str, declared: TypeMembers) -> tuple[Violation, ...]:
+    """Members declared after a group that must come later."""
+    violations = []
+    order = group_order_text(declared.is_test)
+    latest = MemberKind.CONSTANT
+    for member in declared.members:
+        if member.kind.precedes(latest):
+            violations.append(Violation(
+                line=member.line,
+                path=path,
+                message=(
+                    f"`{member.name}` ({member.kind.label}) declared after a later "
+                    f"group in `{declared.name}`, required group order {order}"
+                ),
+            ))
+
+        if latest.precedes(member.kind):
+            latest = member.kind
+    return tuple(violations)
+
+
+def group_order_text(is_test: bool) -> str:
+    """The required group-order clause for the production or the test layout."""
+    if is_test:
+        return "const, case, constructor, lifecycle hooks, methods, data providers"
+    return "const, case, constructor, static methods, instance methods"
+
+
+def within_group_violations(path: str, declared: TypeMembers) -> tuple[Violation, ...]:
+    """Groups whose members break their required intra-group order."""
+    violations = []
+    for kind in MemberKind:
+        if kind is MemberKind.CONSTRUCTOR:
+            continue
+        grouped = [member for member in declared.members if member.kind is kind]
+        names = [member.name for member in grouped]
+
+        if not names:
+            continue
+        required = required_within(kind=kind, names=names)
+
+        if names == required:
+            continue
+
+        violations.append(Violation(
+            line=grouped[0].line,
+            path=path,
+            message=(
+                f"{kind.label} order in `{declared.name}` is ({', '.join(names)}), "
+                f"required ({', '.join(required)})"
+            ),
+        ))
+    return tuple(violations)
+
+
+def required_within(kind: MemberKind, names: list[str]) -> list[str]:
+    """One group's required order, lifecycle hooks by execution order, else length then alphabet."""
+    if kind is MemberKind.LIFECYCLE:
+        return [hook for hook in LIFECYCLE_ORDER if hook in names]
+    return MEMBER_ORDERING.sorted(names)
+
+
+def ordering_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Every ordering violation in one PHP file: members, parameters."""
+    return (
+        *member_violations(unit),
+        *parameter_violations(unit),
+    )
+
+
+# --- Shell --------------------------------------------------------------------
+
+
+def requested_paths() -> list[Path]:
+    """The paths to verify, from argv or from the hook's stdin payload."""
+    if len(sys.argv) > 1:
+        return [Path(argument) for argument in sys.argv[1:]]
+    try:
+        payload = json.load(sys.stdin)
+    except ValueError:
+        return []
+
+    file_path = (payload.get("tool_input") or {}).get("file_path")
+
+    if isinstance(file_path, str):
+        return [Path(file_path)]
+    return []
+
+
+def in_scope(path: Path) -> bool:
+    """Whether the path is a PHP source under src/ or tests/."""
+    return bool(SCOPE_PATTERN.search(path.as_posix())) and path.is_file()
+
+
+def file_violations(path: Path) -> tuple[Violation, ...]:
+    """The ordering violations for one file."""
+    unit = FileUnit(
+        path=path.as_posix(),
+        text=path.read_text(errors="replace", encoding="utf-8"),
+    )
+    return ordering_violations(unit)
+
+
+def main() -> int:
+    violations = [
+        violation
+        for path in requested_paths()
+        if in_scope(path)
+        for violation in file_violations(path)
+    ]
+
+    if not violations:
+        return 0
+
+    for violation in violations[:MAX_ERRORS_REPORTED]:
+        print(violation, file=sys.stderr)
+    overflow = len(violations) - MAX_ERRORS_REPORTED
+
+    if overflow > 0:
+        print(f"... and {overflow} more violations", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.claude/hooks/php-prose-punctuation-conformance.py b/.claude/hooks/php-prose-punctuation-conformance.py
new file mode 100644
index 0000000..0ff0d35
--- /dev/null
+++ b/.claude/hooks/php-prose-punctuation-conformance.py
@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Prose punctuation conformance hook for tiny-blocks PHP libraries.
+
+Self-contained PostToolUse hook on Edit|Write|MultiEdit. Verifies prose punctuation:
+no em-dash, en-dash, or ` -- ` as a clause separator in Markdown prose or
+PHP comments, plus no `;` separator in Markdown. The checks read raw text only, so
+this script carries no PHP lexer. Markdown files route to the prose check, PHP
+sources to the comment check.
+
+Control flow uses guard clauses only and nesting never exceeds two levels. Reports
+violations to stderr and exits 2 to prompt Claude with feedback; exits 0 silently if
+no violations or the file is out of scope.
+"""
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+# --- Configuration ----------------------------------------------------------
+
+# In-scope files: PHP sources under src/ or tests/, plus any Markdown file.
+SCOPE_PATTERN: Final = re.compile(r"(^|/)(src|tests)/.+\.php$")
+MARKDOWN_PATTERN: Final = re.compile(r"\.md$")
+
+# Prohibited prose punctuation as clause separators. Em-dash U+2014, en-dash U+2013,
+# spaced double hyphen, and (Markdown only) the semicolon.
+PROSE_PUNCTUATION: Final = re.compile(r"[\u2014\u2013]| -- |;")
+PROSE_DASHES: Final = re.compile(r"[\u2014\u2013]| -- ")
+FENCE: Final = re.compile(r"^\s*```")
+PHP_COMMENT: Final = re.compile(r"/\*.*?\*/|//[^\n]*|#(?!\[)[^\n]*", re.DOTALL)
+INLINE_CODE: Final = re.compile(r"`[^`]*`")
+
+# String and heredoc bodies, blanked before the PHP comment scan so a `//` or ` -- `
+# inside a string literal is never mistaken for a comment.
+STRING_LITERAL: Final = re.compile(
+    r"""
+      <<<[ \t]*(?P<quote>['"]?)(?P<label>\w+)(?P=quote)[^\n]*\n
+      .*?\n[ \t]*(?P=label)\b
+    | '(?:\\.|[^'\\])*'
+    | "(?:\\.|[^"\\])*"
+    """,
+    re.DOTALL | re.VERBOSE,
+)
+
+# HTML entities (&amp;, &#39;) and URLs carry legitimate semicolons, so they are
+# stripped from a Markdown line before the prose-punctuation scan.
+HTML_ENTITY: Final = re.compile(r"&(?:\w+|#\d+);")
+URL: Final = re.compile(r"https?://\S+")
+# A line indented by four or more spaces is a Markdown indented code block.
+INDENTED_CODE: Final = re.compile(r"^ {4,}\S")
+
+MAX_ERRORS_REPORTED = 30
+
+
+# --- Types --------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One style violation at a source position."""
+
+    line: int
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}: {self.message}"
+
+
+@dataclass(frozen=True)
+class FileUnit:
+    """One file under analysis: its path and raw text. No lexing needed here."""
+
+    path: str
+    text: str
+
+
+# --- Checks -------------------------------------------------------------------
+
+
+def blanked(literal: re.Match[str]) -> str:
+    """The matched literal as spaces, newlines preserved."""
+    return re.sub(r"[^\n]", " ", literal.group(0))
+
+
+def is_markdown(path: str) -> bool:
+    """Whether the path is a Markdown file, routed to the Markdown prose check."""
+    return bool(MARKDOWN_PATTERN.search(path))
+
+
+def markdown_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """No `;`, em-dash, en-dash, or ` -- ` as a clause
+    separator in Markdown prose. Fenced code and table rows are exempt."""
+    violations = []
+    in_fence = False
+    for number, line in enumerate(unit.text.split("\n"), start=1):
+        if FENCE.match(line):
+            in_fence = not in_fence
+            continue
+
+        if in_fence or "|" in line or INDENTED_CODE.match(line):
+            continue
+
+        prose = URL.sub("", HTML_ENTITY.sub("", INLINE_CODE.sub("", line)))
+
+        if PROSE_PUNCTUATION.search(prose):
+            violations.append(Violation(
+                line=number,
+                path=unit.path,
+                message=(
+                    "prohibited prose punctuation (`;`, em-dash, en-dash, or ` -- `), "
+                    "split the sentence or use a comma, colon, or parentheses"
+                ),
+            ))
+    return tuple(violations)
+
+
+def comment_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """In PHPDoc and comments: no em-dash, en-dash,
+    or ` -- ` as a separator. The `;` is not checked in PHP comments (it terminates
+    statements in commented code)."""
+    violations = []
+    source = STRING_LITERAL.sub(blanked, unit.text)
+    for match in PHP_COMMENT.finditer(source):
+        if PROSE_DASHES.search(INLINE_CODE.sub("", match.group(0))):
+            violations.append(Violation(
+                line=source.count("\n", 0, match.start()) + 1,
+                path=unit.path,
+                message=(
+                    "prohibited prose punctuation (em-dash, en-dash, or ` -- `) in a "
+                    "comment"
+                ),
+            ))
+    return tuple(violations)
+
+
+def punctuation_violations(unit: FileUnit) -> tuple[Violation, ...]:
+    """Punctuation violations for one file: Markdown prose for `.md`, comments otherwise."""
+    if is_markdown(unit.path):
+        return markdown_violations(unit)
+    return comment_violations(unit)
+
+
+# --- Shell --------------------------------------------------------------------
+
+
+def requested_paths() -> list[Path]:
+    """The paths to verify, from argv or from the hook's stdin payload."""
+    if len(sys.argv) > 1:
+        return [Path(argument) for argument in sys.argv[1:]]
+    try:
+        payload = json.load(sys.stdin)
+    except ValueError:
+        return []
+
+    file_path = (payload.get("tool_input") or {}).get("file_path")
+
+    if isinstance(file_path, str):
+        return [Path(file_path)]
+    return []
+
+
+def in_scope(path: Path) -> bool:
+    """Whether the path is a PHP source or any Markdown this hook covers."""
+    posix = path.as_posix()
+    matched = SCOPE_PATTERN.search(posix) or MARKDOWN_PATTERN.search(posix)
+    return bool(matched) and path.is_file()
+
+
+def file_violations(path: Path) -> tuple[Violation, ...]:
+    """The punctuation violations for one file."""
+    unit = FileUnit(
+        path=path.as_posix(),
+        text=path.read_text(errors="replace", encoding="utf-8"),
+    )
+    return punctuation_violations(unit)
+
+
+def main() -> int:
+    violations = [
+        violation
+        for path in requested_paths()
+        if in_scope(path)
+        for violation in file_violations(path)
+    ]
+
+    if not violations:
+        return 0
+
+    for violation in violations[:MAX_ERRORS_REPORTED]:
+        print(violation, file=sys.stderr)
+    overflow = len(violations) - MAX_ERRORS_REPORTED
+
+    if overflow > 0:
+        print(f"... and {overflow} more violations", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.claude/rules/php-library-code-style.md b/.claude/rules/php-library-code-style.md
index c44dbc1..4468794 100644
--- a/.claude/rules/php-library-code-style.md
+++ b/.claude/rules/php-library-code-style.md
@@ -7,11 +7,13 @@ paths:
 
 # Code style
 
-Semantic rules for all PHP files in libraries. Formatting rules covered by `PSR-12` are enforced
-by `phpcs.xml`. Four formatting rules outside `PSR-12` (single-line signatures within 120
-characters, no vertical alignment in parameter lists, vertical alignment of `=>` in multi-line
-match arms and array literals, no trailing comma in multi-line lists) are documented at the end
-of this file under "Formatting overrides". Complexity rules live in `php-library-modeling.md`.
+Semantic rules for all PHP files in libraries. Formatting and structural rules are enforced by
+`phpcs.xml` (the `PSR12` ruleset plus curated Squiz, Generic, PSR2, and `SlevomatCodingStandard`
+sniffs). Three formatting rules the ruleset does not cover (single-line signatures within 120
+characters, vertical alignment of `=>` in multi-line match arms and array literals, no trailing
+comma in multi-line lists) are documented at the end of this file under "Formatting overrides".
+Single spacing between a type hint and its parameter is mechanically enforced by the
+`Squiz.Functions.FunctionDeclarationArgumentSpacing` sniff. Complexity rules live in `php-library-modeling.md`.
 Folder structure, public API boundary, and the semantics of `Internal/` live in
 `php-library-architecture.md`.
 
@@ -829,8 +831,7 @@ public function classify(int $score): Grade
 
 ## Formatting overrides
 
-Four formatting rules are not covered by the canonical `phpcs.xml` (which references `PSR-12`
-only). Apply them manually.
+Three formatting rules are not covered by the canonical `phpcs.xml`. Apply them manually.
 
 ### Single-line signatures within 120 characters
 
@@ -859,36 +860,9 @@ private function __construct(public ExternalReference $id, public Money $amount,
 ```
 
 When the one-line form would exceed 120 characters, break to one parameter per line and apply the
-no-vertical-alignment and no-trailing-comma rules below.
-
-### No vertical alignment in parameter lists
-
-Use a single space between the type and the variable name in parameter lists (constructors,
-function signatures, closures). Never pad with extra spaces to align columns. This rule applies
-only to parameter lists, not to other contexts that use `=>` alignment (see "Vertical alignment
-of `=>`" below).
-
-**Prohibited.** Vertical alignment of types:
-
-```php
-public function __construct(
-    public OrderId     $id,
-    public Money       $total,
-    public Customer    $customer,
-    public Precision   $precision
-) {}
-```
-
-**Correct.** Single space between type and variable:
-
-```php
-public function __construct(
-    public OrderId $id,
-    public Money $total,
-    public Customer $customer,
-    public Precision $precision
-) {}
-```
+no-trailing-comma rule below. Single spacing between a type hint and its parameter (never padded to
+align columns) is enforced mechanically by the `Squiz.Functions.FunctionDeclarationArgumentSpacing`
+sniff, so it is not a manual override.
 
 ### Vertical alignment of `=>` in match arms and array literals
 
diff --git a/.claude/rules/php-library-tooling.md b/.claude/rules/php-library-tooling.md
index 8cf50d2..6ece250 100644
--- a/.claude/rules/php-library-tooling.md
+++ b/.claude/rules/php-library-tooling.md
@@ -36,18 +36,26 @@ revise before outputting.
 2. `composer.json` exposes exactly five scripts: `configure`, `configure-and-update`, `review`,
    `test-file`, `tests`. No other public scripts.
 3. `composer.json` fixed fields use the canonical values from the skill asset (`license`, `type`,
-   `minimum-stability`, `prefer-stable`, `authors`, `config`, `require.php`). The five universal
+   `minimum-stability`, `prefer-stable`, `authors`, `config`, `require.php`). The six universal
    dev dependencies (`ergebnis/composer-normalize`, `infection/infection`, `phpstan/phpstan`,
-   `phpunit/phpunit`, `squizlabs/php_codesniffer`) are present. `require-dev` may add libraries
-   the tests need on top of those five. The asset's caret ranges are the canonical floor, and
-   the repo `composer.json` matches the asset. To bump, update the asset first, then the repo.
+   `phpunit/phpunit`, `slevomat/coding-standard`, `squizlabs/php_codesniffer`) are present, and
+   `config.allow-plugins` enables `dealerdirect/phpcodesniffer-composer-installer` so the Slevomat
+   sniffs register with phpcs. `require-dev` may add libraries the tests need on top of those six.
+   The asset's caret ranges are the canonical floor, and the repo `composer.json` matches the
+   asset. To bump, update the asset first, then the repo.
 4. `composer.json` `description` is a single short sentence. Multi-sentence prose belongs in the
    README Overview, not in Composer metadata.
 5. `composer.json` includes a `keywords` array that contains `"tiny-blocks"`. Its position in
    the array is not constrained. The remaining entries are topic tokens derived from the
    library's purpose (`psr-7`, `http-client`, `event-sourcing`, etc.).
-6. `phpcs.xml` references only the `PSR12` ruleset. No additional sniffs. Formatting rules outside
-   PSR-12 live in `php-library-code-style.md` under "Formatting overrides".
+6. `phpcs.xml` references the `PSR12` ruleset plus curated Squiz, Generic, PSR2, and
+   `SlevomatCodingStandard` sniffs that mechanically enforce the library's structural and
+   type-hint conventions (class member order, alphabetically sorted and used-only imports, strict
+   types, parameter, property, and return type hints, and complexity ceilings). The
+   `SlevomatCodingStandard.Classes.ClassStructure` groups collapse all methods into one group, so
+   the `php-ordering-conformance` hook owns the name-length ordering within them. The three
+   formatting rules the ruleset does not cover live in `php-library-code-style.md` under
+   "Formatting overrides".
 7. `phpunit.xml` sets all five `failOn*` flags to `true` (`failOnDeprecation`, `failOnNotice`,
    `failOnPhpunitDeprecation`, `failOnRisky`, `failOnWarning`).
 8. `phpunit.xml` sets `executionOrder="random"` and `beStrictAboutOutputDuringTests="true"`.
@@ -84,9 +92,10 @@ revise before outputting.
 The committed config files split into two naming conventions on purpose. The split is documented
 here so it reads as intentional, not accidental.
 
-- **Committed live, no `.dist`:** `phpcs.xml` and `phpunit.xml`. The ruleset (`PSR12` only) and
-  the test configuration are stable across the whole ecosystem and identical in every library.
-  There is no per-clone local-override story, so the live file is committed directly.
+- **Committed live, no `.dist`:** `phpcs.xml` and `phpunit.xml`. The ruleset (`PSR12` plus the
+  curated Squiz, Generic, PSR2, and `SlevomatCodingStandard` sniffs) and the test configuration
+  are stable across the whole ecosystem and identical in every library. There is no per-clone
+  local-override story, so the live file is committed directly.
 - **Committed as `.dist`:** `phpstan.neon.dist` and `infection.json.dist`. These are the two
   tools a contributor may legitimately want to tune locally (a temporary `ignoreErrors` entry, a
   narrower mutator set while iterating). The `.dist` baseline is committed. A contributor drops a
diff --git a/.claude/settings.json b/.claude/settings.json
index 512042f..f01749f 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -228,5 +228,22 @@
       "Bash(wget * | bash)",
       "Bash(wget * | sudo:*)"
     ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/php-ordering-conformance.py"
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/php-prose-punctuation-conformance.py"
+          }
+        ]
+      }
+    ]
   }
 }
diff --git a/.claude/skills/tiny-blocks-create/SKILL.md b/.claude/skills/tiny-blocks-create/SKILL.md
index efcc62b..5f743f7 100644
--- a/.claude/skills/tiny-blocks-create/SKILL.md
+++ b/.claude/skills/tiny-blocks-create/SKILL.md
@@ -8,8 +8,9 @@ description: Scaffold a new PHP library for the tiny-blocks ecosystem, or restor
 This skill is the single source of truth for the boilerplate every tiny-blocks PHP library
 shares: the config files, the CI workflow, and the repository templates. The canonical bodies
 live in `assets/` as drop-in files. Copy them and substitute the placeholders rather than
-regenerating them from memory. The assets already encode the ecosystem's decisions (PSR-12 only,
-`level: max`, MSI 100, Docker-wrapped Makefile, the `.dist` naming split, the export-ignore set).
+regenerating them from memory. The assets already encode the ecosystem's decisions (the `PSR12`
+plus `SlevomatCodingStandard` ruleset, `level: max`, MSI 100, Docker-wrapped Makefile, the
+`.dist` naming split, the export-ignore set).
 
 The semantic conventions (how to name classes, how to structure `src/`, how to write tests) are
 **not** in this skill. They live in `.claude/rules/`. This skill produces the skeleton. The rules
diff --git a/.claude/skills/tiny-blocks-create/assets/config/.gitattributes b/.claude/skills/tiny-blocks-create/assets/config/.gitattributes
index 2bd9baa..275cece 100644
--- a/.claude/skills/tiny-blocks-create/assets/config/.gitattributes
+++ b/.claude/skills/tiny-blocks-create/assets/config/.gitattributes
@@ -2,6 +2,9 @@
 
 *.php text diff=php
 
+# Keep Claude tooling scripts out of GitHub's language statistics
+/.claude/**/*.py linguist-vendored
+
 # Dev-only, excluded from the Packagist tarball
 /.github             export-ignore
 /tests               export-ignore
diff --git a/.claude/skills/tiny-blocks-create/assets/config/.gitignore b/.claude/skills/tiny-blocks-create/assets/config/.gitignore
index c8f4364..29546dd 100644
--- a/.claude/skills/tiny-blocks-create/assets/config/.gitignore
+++ b/.claude/skills/tiny-blocks-create/assets/config/.gitignore
@@ -9,6 +9,8 @@ composer.lock
 # Tooling cache
 .phpunit.cache/
 .phpunit.result.cache
+__pycache__/
+*.pyc
 
 # Coverage and reports
 build/
diff --git a/.claude/skills/tiny-blocks-create/assets/config/composer.json b/.claude/skills/tiny-blocks-create/assets/config/composer.json
index e10a520..85d30fc 100644
--- a/.claude/skills/tiny-blocks-create/assets/config/composer.json
+++ b/.claude/skills/tiny-blocks-create/assets/config/composer.json
@@ -27,6 +27,7 @@
         "infection/infection": "^0.33",
         "phpstan/phpstan": "^2.2",
         "phpunit/phpunit": "^13.1",
+        "slevomat/coding-standard": "^8.30",
         "squizlabs/php_codesniffer": "^4.0"
     },
     "minimum-stability": "stable",
@@ -43,6 +44,7 @@
     },
     "config": {
         "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true,
             "ergebnis/composer-normalize": true,
             "infection/extension-installer": true
         },
diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml b/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml
index a52372c..8f95184 100644
--- a/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml
+++ b/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml
@@ -1,7 +1,93 @@
 <?xml version="1.0"?>
 <ruleset name="tiny-blocks">
     <description>Code style for the tiny-blocks library.</description>
-    <rule ref="PSR12"/>
+
     <file>src</file>
     <file>tests</file>
+
+    <rule ref="PSR12"/>
+
+    <rule ref="Squiz.Arrays.ArrayBracketSpacing"/>
+    <rule ref="Squiz.ControlStructures.ControlSignature"/>
+    <rule ref="Squiz.ControlStructures.ElseIfDeclaration"/>
+    <rule ref="Squiz.Formatting.OperatorBracket"/>
+    <rule ref="Squiz.Functions.FunctionDeclarationArgumentSpacing">
+        <properties>
+            <property name="equalsSpacing" value="1"/>
+        </properties>
+    </rule>
+    <rule ref="Squiz.Scope.MethodScope"/>
+    <rule ref="Squiz.WhiteSpace.ControlStructureSpacing"/>
+    <rule ref="Squiz.WhiteSpace.FunctionSpacing">
+        <properties>
+            <property name="spacing" value="1"/>
+            <property name="spacingBeforeFirst" value="0"/>
+            <property name="spacingAfterLast" value="0"/>
+        </properties>
+    </rule>
+    <rule ref="Squiz.WhiteSpace.SuperfluousWhitespace"/>
+
+    <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
+    <rule ref="Generic.CodeAnalysis.EmptyStatement"/>
+    <rule ref="Generic.ControlStructures.InlineControlStructure"/>
+    <rule ref="Generic.Formatting.DisallowMultipleStatements"/>
+    <rule ref="Generic.Metrics.CyclomaticComplexity">
+        <properties>
+            <property name="complexity" value="10"/>
+            <property name="absoluteComplexity" value="20"/>
+        </properties>
+    </rule>
+    <rule ref="Generic.Metrics.NestingLevel"/>
+    <rule ref="Generic.NamingConventions.ConstructorName"/>
+    <rule ref="Generic.PHP.DeprecatedFunctions"/>
+    <rule ref="Generic.PHP.LowerCaseKeyword"/>
+    <rule ref="Generic.Strings.UnnecessaryStringConcat"/>
+
+    <rule ref="PSR2.Classes.PropertyDeclaration"/>
+    <rule ref="PSR2.Files.EndFileNewline"/>
+    <rule ref="PSR2.Methods.MethodDeclaration"/>
+
+    <rule ref="SlevomatCodingStandard.Classes.ClassStructure">
+        <properties>
+            <property name="groups" type="array">
+                <element value="uses"/>
+                <element value="public constants"/>
+                <element value="protected constants"/>
+                <element value="private constants"/>
+                <element value="enum cases"/>
+                <element value="public properties, public static properties"/>
+                <element value="protected properties, protected static properties"/>
+                <element value="private properties, private static properties"/>
+                <element value="constructor, destructor"/>
+                <element value="all public methods, all protected methods, all private methods, static constructors"/>
+                <element value="magic methods"/>
+            </property>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Classes.ModernClassNameReference"/>
+    <rule ref="SlevomatCodingStandard.Complexity.Cognitive"/>
+    <rule ref="SlevomatCodingStandard.ControlStructures.RequireNullCoalesceOperator"/>
+    <rule ref="SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses"/>
+    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly"/>
+    <rule ref="SlevomatCodingStandard.Namespaces.UnusedUses">
+        <properties>
+            <property name="searchAnnotations" value="true"/>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Namespaces.UseFromSameNamespace"/>
+    <rule ref="SlevomatCodingStandard.TypeHints.DeclareStrictTypes">
+        <properties>
+            <property name="spacesCountAroundEqualsSign" value="0"/>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification"/>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification"/>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification"/>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Variables.UnusedVariable"/>
 </ruleset>
diff --git a/.gitattributes b/.gitattributes
index 2bd9baa..275cece 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -2,6 +2,9 @@
 
 *.php text diff=php
 
+# Keep Claude tooling scripts out of GitHub's language statistics
+/.claude/**/*.py linguist-vendored
+
 # Dev-only, excluded from the Packagist tarball
 /.github             export-ignore
 /tests               export-ignore
diff --git a/.gitignore b/.gitignore
index c8f4364..29546dd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,8 @@ composer.lock
 # Tooling cache
 .phpunit.cache/
 .phpunit.result.cache
+__pycache__/
+*.pyc
 
 # Coverage and reports
 build/
diff --git a/README.md b/README.md
index c7841d8..cdf896c 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
         - [Creating from a database timestamp](#creating-from-a-database-timestamp)
         - [Creating from Unix seconds](#creating-from-unix-seconds)
         - [Adding and subtracting time](#adding-and-subtracting-time)
+        - [Adding and subtracting months and years](#adding-and-subtracting-months-and-years)
         - [Measuring distance between instants](#measuring-distance-between-instants)
         - [Comparing instants](#comparing-instants)
         - [Emitting with sub-second precision](#emitting-with-sub-second-precision)
@@ -53,6 +54,7 @@
         - [Projecting an Instant](#projecting-an-instant)
         - [Comparing dates](#comparing-dates)
         - [Day arithmetic](#day-arithmetic)
+        - [Month and year arithmetic](#month-and-year-arithmetic)
         - [Serializing with the mapper](#serializing-with-the-mapper-1)
     + [Timezone](#timezone)
         - [Creating from an identifier](#creating-from-an-identifier)
@@ -71,10 +73,10 @@
 
 ## Overview
 
-Models time as immutable value objects for PHP, including instants, durations, periods, timezones, time-of-day,
-local dates, and day-of-week. All instants are normalized to UTC with microsecond precision, with strict parsing,
-formatting, and arithmetic operations. Declared as `final readonly class` for language-level immutability, with
-structural equality provided by the tiny-blocks value-object contract.
+Models time as immutable value objects for PHP, including instants, durations, periods, timezones, time-of-day, local
+dates, and day-of-week. All instants are normalized to UTC with microsecond precision, with strict parsing, formatting,
+and arithmetic operations. Declared as `final readonly class` for language-level immutability, with structural equality
+provided by the tiny-blocks value-object contract.
 
 ## Installation
 
@@ -194,6 +196,46 @@ $instant->plus(duration: Duration::fromHours(hours: 2))->toIso8601();       # 20
 $instant->minus(duration: Duration::fromSeconds(seconds: 60))->toIso8601(); # 2026-02-17T09:59:00+00:00
 ```
 
+#### Adding and subtracting months and years
+
+Re-anchors the instant in a timezone (UTC when omitted), shifts the local calendar date by whole months or years with
+the same day clamping as `LocalDate`, and normalizes the result back to UTC. The local time of day, including
+microseconds, is preserved.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\Instant;
+
+$instant = Instant::fromString(value: '2026-01-31T10:00:00+00:00');
+
+$instant->plusMonths(months: 1)->toIso8601();   # 2026-02-28T10:00:00+00:00 (clamped)
+$instant->plusYears(years: 1)->toIso8601();     # 2027-01-31T10:00:00+00:00
+$instant->minusMonths(months: 1)->toIso8601();  # 2025-12-31T10:00:00+00:00
+$instant->minusYears(years: 1)->toIso8601();    # 2025-01-31T10:00:00+00:00
+```
+
+Passing a timezone re-anchors the shift in that zone. When the resulting local wall time does not exist because of a
+spring-forward gap, PHP shifts it forward by the gap.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\Instant;
+use TinyBlocks\Time\Timezone;
+
+$newYork = Timezone::from(identifier: 'America/New_York');
+$instant = Instant::fromString(value: '2026-02-08T07:30:00+00:00');
+
+# The local time 2026-02-08 02:30 plus one month targets the non-existent local 2026-03-08 02:30,
+# so PHP resolves it forward to 03:30 -04:00.
+$instant->plusMonths(months: 1, zone: $newYork)->toIso8601(); # 2026-03-08T07:30:00+00:00
+```
+
 #### Measuring distance between instants
 
 Returns the absolute `Duration` between two `Instant` objects.
@@ -245,8 +287,8 @@ $later->isAfterOrEqual(other: $earlier);   # true
 
 #### Emitting with sub-second precision
 
-By default `toIso8601()` emits seconds only. Pass a `Precision` value to include fractional
-seconds in the output. Existing callers that omit the argument are unaffected.
+By default `toIso8601()` emits seconds only. Pass a `Precision` value to include fractional seconds in the output.
+Existing callers that omit the argument are unaffected.
 
 ```php
 <?php
@@ -403,17 +445,16 @@ $duration->toDays();    # 0
 
 ### MonotonicClock
 
-A `MonotonicClock` exposes a high-resolution counter for measuring elapsed time, conceptually
-distinct from `Duration`: `Duration` is a wall-clock quantity measured in whole seconds, while
-a monotonic reading is an opaque nanosecond counter whose absolute value carries no calendar
-meaning and is only useful as the delta between two readings on the same clock. The default
+A `MonotonicClock` exposes a high-resolution counter for measuring elapsed time, conceptually distinct from `Duration`:
+`Duration` is a wall-clock quantity measured in whole seconds, while a monotonic reading is an opaque nanosecond counter
+whose absolute value carries no calendar meaning and is only useful as the delta between two readings on the same clock.
+The default
 `SystemMonotonicClock` implementation is backed by PHP's `hrtime(true)`.
 
 #### Reading the current nanoseconds
 
-Returns the current monotonic reading as an integer nanosecond count. The value has no calendar
-meaning. Treat it as an opaque counter and only compare it to another reading from the same
-clock.
+Returns the current monotonic reading as an integer nanosecond count. The value has no calendar meaning. Treat it as an
+opaque counter and only compare it to another reading from the same clock.
 
 ```php
 <?php
@@ -429,8 +470,8 @@ $clock->nanoseconds(); # 12345678901234 (an opaque counter, not a calendar value
 
 #### Measuring an elapsed window
 
-Subtract two successive readings on the same clock to obtain the elapsed interval in
-nanoseconds. Readings are guaranteed to be non-decreasing.
+Subtract two successive readings on the same clock to obtain the elapsed interval in nanoseconds. Readings are
+guaranteed to be non-decreasing.
 
 ```php
 <?php
@@ -451,20 +492,19 @@ $elapsedNanos = $clock->nanoseconds() - $start;
 
 ### Stopwatch
 
-A `Stopwatch` separates the act of measuring from the value being measured. It captures a
-starting reading from a `MonotonicClock` and exposes the accumulated interval as an `Elapsed`
-value object. The clock is injected explicitly so the time source stays under the caller's
-control, and reading the interval is idempotent: invoking `elapsed()` more than once returns
-successive measurements from the same starting reading.
+A `Stopwatch` separates the act of measuring from the value being measured. It captures a starting reading from a
+`MonotonicClock` and exposes the accumulated interval as an `Elapsed`
+value object. The clock is injected explicitly so the time source stays under the caller's control, and reading the
+interval is idempotent: invoking `elapsed()` more than once returns successive measurements from the same starting
+reading.
 
-`Elapsed` is a pure value object expressed in nanoseconds. It is distinct from `Duration`, which
-models wall-clock seconds, and nanosecond and second granularities are kept in separate types so
-the intent of each measurement stays explicit at the call site.
+`Elapsed` is a pure value object expressed in nanoseconds. It is distinct from `Duration`, which models wall-clock
+seconds, and nanosecond and second granularities are kept in separate types so the intent of each measurement stays
+explicit at the call site.
 
 #### Starting a stopwatch
 
-Captures the current reading of the provided monotonic clock and returns a stopwatch anchored to
-that moment.
+Captures the current reading of the provided monotonic clock and returns a stopwatch anchored to that moment.
 
 ```php
 <?php
@@ -479,9 +519,8 @@ $stopwatch = Stopwatch::start(clock: new SystemMonotonicClock());
 
 #### Reading the elapsed interval
 
-Returns an `Elapsed` measuring the interval between the starting reading and the current reading
-of the same clock. `toMilliseconds()` converts the nanosecond count to milliseconds rounded to
-two decimal places.
+Returns an `Elapsed` measuring the interval between the starting reading and the current reading of the same clock.
+`toMilliseconds()` converts the nanosecond count to milliseconds rounded to two decimal places.
 
 ```php
 <?php
@@ -502,8 +541,7 @@ $stopwatch->elapsed()->toMilliseconds(); # 1.5
 #### Reading the elapsed interval more than once
 
 The starting reading is captured once and never changes. Each call to `elapsed()` returns a new
-`Elapsed` measured from that same anchor, so successive calls report a non-decreasing series of
-intervals.
+`Elapsed` measured from that same anchor, so successive calls report a non-decreasing series of intervals.
 
 ```php
 <?php
@@ -840,8 +878,8 @@ $time->toString();                # 08:30
 
 ### LocalDate
 
-A `LocalDate` is a value object representing a calendar date (year, month, day) without time and without timezone.
-Dates are always in the proleptic Gregorian calendar and restricted to the range `0001–9999`.
+A `LocalDate` is a value object representing a calendar date (year, month, day) without time and without timezone. Dates
+are always in the proleptic Gregorian calendar and restricted to the range `0001–9999`.
 
 #### Creating from components
 
@@ -940,6 +978,33 @@ $date->plusDays(days: 10)->toIso8601();  # 2026-06-02
 $date->minusDays(days: 30)->toIso8601(); # 2026-04-23
 ```
 
+#### Month and year arithmetic
+
+Shifts the year and month, then clamps the day to the last valid day of the target month. A negative count shifts in the
+opposite direction.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use TinyBlocks\Time\LocalDate;
+
+$date = LocalDate::of(year: 2026, month: 1, day: 31);
+
+$date->plusMonths(months: 1)->toIso8601();  # 2026-02-28 (clamped, February has 28 days)
+$date->plusYears(years: 2)->toIso8601();    # 2028-01-31
+$date->minusMonths(months: 2)->toIso8601(); # 2025-11-30 (clamped, November has 30 days)
+$date->minusYears(years: 1)->toIso8601();   # 2025-01-31
+```
+
+Because the day is clamped, the shift is not associative. Adding a month and then subtracting it does not always restore
+the original day.
+
+```php
+$date->plusMonths(months: 1)->minusMonths(months: 1)->toIso8601(); # 2026-01-28
+```
+
 #### Serializing with the mapper
 
 `LocalDate` carries a `#[ScalarCodec]`, so `tiny-blocks/mapper` rebuilds it from a `YYYY-MM-DD` string and writes it
diff --git a/composer.json b/composer.json
index a81d2ac..ec5a219 100644
--- a/composer.json
+++ b/composer.json
@@ -31,7 +31,7 @@
     "require": {
         "php": "^8.5",
         "tiny-blocks/collection": "^2.5",
-        "tiny-blocks/mapper": "^3.1",
+        "tiny-blocks/mapper": "^3.2",
         "tiny-blocks/value-object": "^5.0"
     },
     "require-dev": {
@@ -39,6 +39,7 @@
         "infection/infection": "^0.33",
         "phpstan/phpstan": "^2.2",
         "phpunit/phpunit": "^13.1",
+        "slevomat/coding-standard": "^8.30",
         "squizlabs/php_codesniffer": "^4.0"
     },
     "minimum-stability": "stable",
@@ -55,6 +56,7 @@
     },
     "config": {
         "allow-plugins": {
+            "dealerdirect/phpcodesniffer-composer-installer": true,
             "ergebnis/composer-normalize": true,
             "infection/extension-installer": true
         },
diff --git a/phpcs.xml b/phpcs.xml
index a52372c..8f95184 100644
--- a/phpcs.xml
+++ b/phpcs.xml
@@ -1,7 +1,93 @@
 <?xml version="1.0"?>
 <ruleset name="tiny-blocks">
     <description>Code style for the tiny-blocks library.</description>
-    <rule ref="PSR12"/>
+
     <file>src</file>
     <file>tests</file>
+
+    <rule ref="PSR12"/>
+
+    <rule ref="Squiz.Arrays.ArrayBracketSpacing"/>
+    <rule ref="Squiz.ControlStructures.ControlSignature"/>
+    <rule ref="Squiz.ControlStructures.ElseIfDeclaration"/>
+    <rule ref="Squiz.Formatting.OperatorBracket"/>
+    <rule ref="Squiz.Functions.FunctionDeclarationArgumentSpacing">
+        <properties>
+            <property name="equalsSpacing" value="1"/>
+        </properties>
+    </rule>
+    <rule ref="Squiz.Scope.MethodScope"/>
+    <rule ref="Squiz.WhiteSpace.ControlStructureSpacing"/>
+    <rule ref="Squiz.WhiteSpace.FunctionSpacing">
+        <properties>
+            <property name="spacing" value="1"/>
+            <property name="spacingBeforeFirst" value="0"/>
+            <property name="spacingAfterLast" value="0"/>
+        </properties>
+    </rule>
+    <rule ref="Squiz.WhiteSpace.SuperfluousWhitespace"/>
+
+    <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
+    <rule ref="Generic.CodeAnalysis.EmptyStatement"/>
+    <rule ref="Generic.ControlStructures.InlineControlStructure"/>
+    <rule ref="Generic.Formatting.DisallowMultipleStatements"/>
+    <rule ref="Generic.Metrics.CyclomaticComplexity">
+        <properties>
+            <property name="complexity" value="10"/>
+            <property name="absoluteComplexity" value="20"/>
+        </properties>
+    </rule>
+    <rule ref="Generic.Metrics.NestingLevel"/>
+    <rule ref="Generic.NamingConventions.ConstructorName"/>
+    <rule ref="Generic.PHP.DeprecatedFunctions"/>
+    <rule ref="Generic.PHP.LowerCaseKeyword"/>
+    <rule ref="Generic.Strings.UnnecessaryStringConcat"/>
+
+    <rule ref="PSR2.Classes.PropertyDeclaration"/>
+    <rule ref="PSR2.Files.EndFileNewline"/>
+    <rule ref="PSR2.Methods.MethodDeclaration"/>
+
+    <rule ref="SlevomatCodingStandard.Classes.ClassStructure">
+        <properties>
+            <property name="groups" type="array">
+                <element value="uses"/>
+                <element value="public constants"/>
+                <element value="protected constants"/>
+                <element value="private constants"/>
+                <element value="enum cases"/>
+                <element value="public properties, public static properties"/>
+                <element value="protected properties, protected static properties"/>
+                <element value="private properties, private static properties"/>
+                <element value="constructor, destructor"/>
+                <element value="all public methods, all protected methods, all private methods, static constructors"/>
+                <element value="magic methods"/>
+            </property>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Classes.ModernClassNameReference"/>
+    <rule ref="SlevomatCodingStandard.Complexity.Cognitive"/>
+    <rule ref="SlevomatCodingStandard.ControlStructures.RequireNullCoalesceOperator"/>
+    <rule ref="SlevomatCodingStandard.Namespaces.AlphabeticallySortedUses"/>
+    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly"/>
+    <rule ref="SlevomatCodingStandard.Namespaces.UnusedUses">
+        <properties>
+            <property name="searchAnnotations" value="true"/>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Namespaces.UseFromSameNamespace"/>
+    <rule ref="SlevomatCodingStandard.TypeHints.DeclareStrictTypes">
+        <properties>
+            <property name="spacesCountAroundEqualsSign" value="0"/>
+        </properties>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification"/>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification"/>
+    </rule>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint">
+        <exclude name="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification"/>
+    </rule>
+    <rule ref="SlevomatCodingStandard.Variables.UnusedVariable"/>
 </ruleset>
diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index d9f0651..0632585 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -8,6 +8,10 @@ parameters:
         - identifier: method.nonObject
           path: src/Instant.php
 
+        # DateTimeImmutable::createFromFormat returns DateTimeImmutable|false; the recomposed wall-clock string is always well-formed, so the false branch is unreachable.
+        - identifier: method.nonObject
+          path: src/Internal/ZonedShift.php
+
         # Collectible is a @template TValue interface; the promoted constructor property $timezones cannot
         # carry a Collectible<Timezone> type parameter because PHPDoc on constructors is prohibited.
         - identifier: missingType.generics
diff --git a/src/DayOfWeek.php b/src/DayOfWeek.php
index a9dff87..898e626 100644
--- a/src/DayOfWeek.php
+++ b/src/DayOfWeek.php
@@ -9,6 +9,8 @@
  */
 enum DayOfWeek: int
 {
+    private const int DAYS_IN_WEEK = 7;
+
     case Monday = 1;
     case Tuesday = 2;
     case Wednesday = 3;
@@ -17,8 +19,6 @@ enum DayOfWeek: int
     case Saturday = 6;
     case Sunday = 7;
 
-    private const int DAYS_IN_WEEK = 7;
-
     /**
      * Derives the day of the week from an Instant.
      *
@@ -66,6 +66,6 @@ public function isWeekend(): bool
      */
     public function distanceTo(DayOfWeek $other): int
     {
-        return ($other->value - $this->value + self::DAYS_IN_WEEK) % self::DAYS_IN_WEEK;
+        return (($other->value - $this->value + self::DAYS_IN_WEEK) % self::DAYS_IN_WEEK);
     }
 }
diff --git a/src/Duration.php b/src/Duration.php
index 8dea67c..4eb62ae 100644
--- a/src/Duration.php
+++ b/src/Duration.php
@@ -44,7 +44,7 @@ public static function zero(): Duration
      */
     public static function fromDays(int $days): Duration
     {
-        return new Duration(seconds: Seconds::from(value: $days * self::SECONDS_PER_DAY));
+        return new Duration(seconds: Seconds::from(value: ($days * self::SECONDS_PER_DAY)));
     }
 
     /**
@@ -56,7 +56,7 @@ public static function fromDays(int $days): Duration
      */
     public static function fromHours(int $hours): Duration
     {
-        return new Duration(seconds: Seconds::from(value: $hours * self::SECONDS_PER_HOUR));
+        return new Duration(seconds: Seconds::from(value: ($hours * self::SECONDS_PER_HOUR)));
     }
 
     /**
@@ -68,7 +68,7 @@ public static function fromHours(int $hours): Duration
      */
     public static function fromMinutes(int $minutes): Duration
     {
-        return new Duration(seconds: Seconds::from(value: $minutes * self::SECONDS_PER_MINUTE));
+        return new Duration(seconds: Seconds::from(value: ($minutes * self::SECONDS_PER_MINUTE)));
     }
 
     /**
diff --git a/src/Elapsed.php b/src/Elapsed.php
index 8e13bb6..39b108e 100644
--- a/src/Elapsed.php
+++ b/src/Elapsed.php
@@ -43,6 +43,6 @@ public static function fromNanoseconds(int $nanoseconds): Elapsed
      */
     public function toMilliseconds(): float
     {
-        return round($this->nanoseconds / self::NANOSECONDS_PER_MILLISECOND, 2);
+        return round(($this->nanoseconds / self::NANOSECONDS_PER_MILLISECOND), 2);
     }
 }
diff --git a/src/Exceptions/InvalidLocalDate.php b/src/Exceptions/InvalidLocalDate.php
index 57d9fb6..6783de4 100644
--- a/src/Exceptions/InvalidLocalDate.php
+++ b/src/Exceptions/InvalidLocalDate.php
@@ -18,6 +18,11 @@ public static function becauseValueIsInvalid(string $value): InvalidLocalDate
         return new InvalidLocalDate(message: sprintf($template, $value));
     }
 
+    public static function becauseShiftIsOutOfRange(): InvalidLocalDate
+    {
+        return new InvalidLocalDate(message: 'The shifted date falls outside the supported range 0001 to 9999.');
+    }
+
     public static function becauseComponentsAreInvalid(int $year, int $month, int $day): InvalidLocalDate
     {
         $template = 'Year <%d>, month <%d>, and day <%d> do not form a valid calendar date.';
diff --git a/src/Instant.php b/src/Instant.php
index 5447219..298e6d4 100644
--- a/src/Instant.php
+++ b/src/Instant.php
@@ -7,7 +7,9 @@
 use DateTimeImmutable;
 use TinyBlocks\Mapper\ScalarCodec;
 use TinyBlocks\Time\Exceptions\InvalidInstant;
+use TinyBlocks\Time\Exceptions\InvalidLocalDate;
 use TinyBlocks\Time\Internal\TextDecoder;
+use TinyBlocks\Time\Internal\ZonedShift;
 use TinyBlocks\Vo\ValueObject;
 use TinyBlocks\Vo\ValueObjectBehavior;
 
@@ -38,7 +40,8 @@ private function __construct(private DateTimeImmutable $datetime)
     public static function now(): Instant
     {
         $utc = Timezone::utc()->toDateTimeZone();
-        return new Instant(datetime: new DateTimeImmutable(datetime: 'now', timezone: $utc));
+
+        return new Instant(datetime: new DateTimeImmutable(timezone: $utc));
     }
 
     /**
@@ -120,20 +123,43 @@ public function isBefore(Instant $other): bool
         return $this->datetime < $other->datetime;
     }
 
+    /**
+     * Returns a new Instant with the given number of years added, re-anchored in a timezone.
+     *
+     * <p>A negative count shifts backward. The instant is projected into <code>$zone</code> (UTC
+     * when omitted), the year shift runs on the local date through {@see LocalDate::plusYears()}
+     * with the same February 29 clamping, and the result is normalized back to UTC.</p>
+     *
+     * @param int $years The number of years to add (may be negative).
+     * @param Timezone|null $zone The timezone used to re-anchor the shift. Defaults to UTC.
+     * @return Instant A new Instant re-anchored after the year shift, normalized to UTC.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function plusYears(int $years, ?Timezone $zone = null): Instant
+    {
+        $timezone = ($zone ?? Timezone::utc());
+        $shiftedDate = $this->toLocalDate(zone: $timezone)->plusYears(years: $years);
+        $recomposed = ZonedShift::recompose(zone: $timezone, original: $this->datetime, shiftedDate: $shiftedDate);
+
+        return new Instant(datetime: $recomposed);
+    }
+
     /**
      * Returns the Instant as an ISO 8601 string in UTC at the chosen sub-second precision.
      *
-     * The output always carries the +00:00 offset and is composed of a date, a time, and an
-     * optional fractional-seconds component determined by the precision argument:
+     * <p>The output always carries the +00:00 offset and is composed of a date, a time, and an
+     * optional fractional-seconds component determined by the precision argument:</p>
      *
-     *  - Precision::Seconds (default): no fractional component, e.g. 2026-02-17T10:30:00+00:00.
-     *  - Precision::Milliseconds: three fractional digits, e.g. 2026-02-17T08:27:21.106+00:00.
-     *  - Precision::Microseconds: six fractional digits, e.g. 2026-02-17T08:27:21.106011+00:00.
+     * <ul>
+     * <li>Precision::Seconds (default): no fractional component, e.g. 2026-02-17T10:30:00+00:00.</li>
+     * <li>Precision::Milliseconds: three fractional digits, e.g. 2026-02-17T08:27:21.106+00:00.</li>
+     * <li>Precision::Microseconds: six fractional digits, e.g. 2026-02-17T08:27:21.106011+00:00.</li>
+     * </ul>
      *
-     * Use Microseconds when interoperating with stores that hold sub-second precision (e.g. a
-     * TIMESTAMP(6) column). Use Seconds for human-facing logs or APIs that do not carry
-     * sub-second timing. Use Milliseconds when consumers expect millisecond resolution but
-     * not microseconds (some web APIs, JavaScript Date).
+     * <p>Use Microseconds when interoperating with stores that hold sub-second precision (e.g. a
+     * TIMESTAMP(6) column). Use Seconds for human-facing logs or APIs that do not carry sub-second
+     * timing. Use Milliseconds when consumers expect millisecond resolution but not microseconds
+     * (some web APIs, JavaScript Date).</p>
      *
      * @param Precision $precision The sub-second granularity to include in the output.
      *                             Defaults to Precision::Seconds.
@@ -155,17 +181,79 @@ public function toIso8601(Precision $precision = Precision::Seconds): string
         };
     }
 
+    /**
+     * Returns a new Instant with the given number of years subtracted, re-anchored in a timezone.
+     *
+     * <p>A negative count shifts forward. Delegates to {@see Instant::plusYears()} with the sign
+     * inverted, so February 29 shifted onto a common year is clamped to February 28 and the same
+     * re-anchoring applies.</p>
+     *
+     * @param int $years The number of years to subtract (may be negative).
+     * @param Timezone|null $zone The timezone used to re-anchor the shift. Defaults to UTC.
+     * @return Instant A new Instant re-anchored after the year shift, normalized to UTC.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function minusYears(int $years, ?Timezone $zone = null): Instant
+    {
+        return $this->plusYears(years: -$years, zone: $zone);
+    }
+
+    /**
+     * Returns a new Instant with the given number of months added, re-anchored in a timezone.
+     *
+     * <p>A negative count shifts backward. The instant is projected into <code>$zone</code> (UTC
+     * when omitted). The calendar shift runs on the local date through {@see LocalDate::plusMonths()},
+     * which clamps the day to the last valid day of the target month. The original local time of
+     * day, including microseconds, is preserved, and the result is normalized back to UTC.</p>
+     *
+     * <p>When the resulting local wall time does not exist in the zone because of a spring-forward
+     * gap, PHP's own resolution is adopted, shifting the time forward by the gap. For example, an
+     * instant whose local time is 2026-02-08 02:30 in America/New_York, plus 1 month, targets the
+     * non-existent local 2026-03-08 02:30 and resolves to 2026-03-08 03:30 -04:00, which is the
+     * instant 2026-03-08T07:30:00+00:00.</p>
+     *
+     * @param int $months The number of months to add (may be negative).
+     * @param Timezone|null $zone The timezone used to re-anchor the shift. Defaults to UTC.
+     * @return Instant A new Instant re-anchored after the month shift, normalized to UTC.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function plusMonths(int $months, ?Timezone $zone = null): Instant
+    {
+        $timezone = ($zone ?? Timezone::utc());
+        $shiftedDate = $this->toLocalDate(zone: $timezone)->plusMonths(months: $months);
+        $recomposed = ZonedShift::recompose(zone: $timezone, original: $this->datetime, shiftedDate: $shiftedDate);
+
+        return new Instant(datetime: $recomposed);
+    }
+
+    /**
+     * Returns a new Instant with the given number of months subtracted, re-anchored in a timezone.
+     *
+     * <p>A negative count shifts forward. Delegates to {@see Instant::plusMonths()} with the sign
+     * inverted, so the same re-anchoring, day clamping, and spring-forward gap resolution apply.</p>
+     *
+     * @param int $months The number of months to subtract (may be negative).
+     * @param Timezone|null $zone The timezone used to re-anchor the shift. Defaults to UTC.
+     * @return Instant A new Instant re-anchored after the month shift, normalized to UTC.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function minusMonths(int $months, ?Timezone $zone = null): Instant
+    {
+        return $this->plusMonths(months: -$months, zone: $zone);
+    }
+
     /**
      * Projects this instant into a calendar date under the given timezone.
      *
      * @param Timezone $zone The timezone used to determine the civil date.
      * @return LocalDate The local date in the given timezone at this instant.
+     * @throws InvalidLocalDate If the projected date falls outside the range 0001 to 9999.
      */
     public function toLocalDate(Timezone $zone): LocalDate
     {
-        $dateTime = $this->datetime->setTimezone($zone->toDateTimeZone());
+        $datetime = $this->datetime->setTimezone($zone->toDateTimeZone());
 
-        return LocalDate::fromString(value: $dateTime->format('Y-m-d'));
+        return LocalDate::fromString(value: $datetime->format('Y-m-d'));
     }
 
     /**
diff --git a/src/Internal/CalendarDay.php b/src/Internal/CalendarDay.php
new file mode 100644
index 0000000..b4dd198
--- /dev/null
+++ b/src/Internal/CalendarDay.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Time\Internal;
+
+final class CalendarDay
+{
+    private function __construct()
+    {
+    }
+
+    public static function clamp(int $year, int $month, int $day): int
+    {
+        $isLeapYear = ($year % 4 === 0 && $year % 100 !== 0) || ($year % 400) === 0;
+
+        return match ($month) {
+            2           => min($day, $isLeapYear ? 29 : 28),
+            4, 6, 9, 11 => min($day, 30),
+            default     => $day
+        };
+    }
+}
diff --git a/src/Internal/Seconds.php b/src/Internal/Seconds.php
index 9ed4636..f0e4dbf 100644
--- a/src/Internal/Seconds.php
+++ b/src/Internal/Seconds.php
@@ -30,12 +30,12 @@ public static function zero(): Seconds
 
     public function plus(Seconds $other): Seconds
     {
-        return new Seconds(value: $this->value + $other->value);
+        return new Seconds(value: ($this->value + $other->value));
     }
 
     public function minus(Seconds $other): Seconds
     {
-        $result = $this->value - $other->value;
+        $result = ($this->value - $other->value);
 
         if ($result < self::ZERO) {
             throw InvalidSeconds::becauseResultIsNegative(current: $this->value, subtracted: $other->value);
diff --git a/src/Internal/ZonedShift.php b/src/Internal/ZonedShift.php
new file mode 100644
index 0000000..003a4bf
--- /dev/null
+++ b/src/Internal/ZonedShift.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Time\Internal;
+
+use DateTimeImmutable;
+use TinyBlocks\Time\LocalDate;
+use TinyBlocks\Time\Timezone;
+
+final class ZonedShift
+{
+    private function __construct()
+    {
+    }
+
+    public static function recompose(
+        Timezone $zone,
+        DateTimeImmutable $original,
+        LocalDate $shiftedDate
+    ): DateTimeImmutable {
+        $dateTimeZone = $zone->toDateTimeZone();
+        $timeOfDay = $original->setTimezone($dateTimeZone)->format('H:i:s.u');
+        $template = '%s %s';
+        $wallClock = sprintf($template, $shiftedDate->toIso8601(), $timeOfDay);
+        $recomposed = DateTimeImmutable::createFromFormat('Y-m-d H:i:s.u', $wallClock, $dateTimeZone);
+
+        return $recomposed->setTimezone(Timezone::utc()->toDateTimeZone());
+    }
+}
diff --git a/src/LocalDate.php b/src/LocalDate.php
index a9c5409..5009727 100644
--- a/src/LocalDate.php
+++ b/src/LocalDate.php
@@ -7,12 +7,14 @@
 use DateTimeImmutable;
 use TinyBlocks\Mapper\ScalarCodec;
 use TinyBlocks\Time\Exceptions\InvalidLocalDate;
+use TinyBlocks\Time\Internal\CalendarDay;
 use TinyBlocks\Vo\ValueObject;
 use TinyBlocks\Vo\ValueObjectBehavior;
 
 /**
  * Represents a calendar date (year, month, day) without time and without timezone.
- * Two instances of this type for the same date are always equal by value.
+ *
+ * <p>Two instances of this type for the same date are always equal by value.</p>
  */
 #[ScalarCodec(decode: 'fromString', encode: 'toIso8601')]
 final readonly class LocalDate implements ValueObject
@@ -31,9 +33,9 @@ private function __construct(private DateTimeImmutable $date)
     /**
      * Creates a LocalDate from explicit year, month, and day components.
      *
-     * @param int $year The calendar year (1–9999).
-     * @param int $month The month of the year (1–12).
-     * @param int $day The day of the month (1–31, validated per month and leap year).
+     * @param int $year The calendar year (1-9999).
+     * @param int $month The month of the year (1-12).
+     * @param int $day The day of the month (1-31, validated per month and leap year).
      * @return LocalDate The created local date.
      * @throws InvalidLocalDate If the combination does not form a valid calendar date.
      */
@@ -56,7 +58,7 @@ public static function of(int $year, int $month, int $day): LocalDate
      */
     public static function today(Timezone $zone): LocalDate
     {
-        $dateTime = new DateTimeImmutable(datetime: 'now', timezone: $zone->toDateTimeZone());
+        $dateTime = new DateTimeImmutable(timezone: $zone->toDateTimeZone());
 
         return LocalDate::fromString(value: $dateTime->format(self::DATE_FORMAT));
     }
@@ -97,7 +99,7 @@ public function year(): int
     /**
      * Returns the month of the year.
      *
-     * @return int The month (1–12).
+     * @return int The month (1-12).
      */
     public function month(): int
     {
@@ -128,7 +130,8 @@ public function isBefore(LocalDate $other): bool
 
     /**
      * Returns a copy of this date shifted forward by the given number of days.
-     * A negative count shifts backward.
+     *
+     * <p>A negative count shifts backward.</p>
      *
      * @param int $days The number of days to add (may be negative).
      * @return LocalDate A new LocalDate shifted forward by the given count.
@@ -153,7 +156,8 @@ public function dayOfWeek(): DayOfWeek
 
     /**
      * Returns a copy of this date shifted backward by the given number of days.
-     * A negative count shifts forward.
+     *
+     * <p>A negative count shifts forward.</p>
      *
      * @param int $days The number of days to subtract (may be negative).
      * @return LocalDate A new LocalDate shifted backward by the given count.
@@ -166,6 +170,31 @@ public function minusDays(int $days): LocalDate
         return new LocalDate(date: $modified);
     }
 
+    /**
+     * Returns a copy of this date shifted forward by the given number of years.
+     *
+     * <p>A negative count shifts backward. February 29 shifted onto a common year is clamped to
+     * February 28, exactly as the month shift clamps in {@see LocalDate::plusMonths()}.</p>
+     *
+     * @param int $years The number of years to add (may be negative).
+     * @return LocalDate A new LocalDate with the year shifted and the day clamped.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function plusYears(int $years): LocalDate
+    {
+        $lowestShift = (self::MIN_YEAR - $this->year());
+        $highestShift = (self::MAX_YEAR - $this->year());
+
+        if ($years < $lowestShift || $years > $highestShift) {
+            throw InvalidLocalDate::becauseShiftIsOutOfRange();
+        }
+
+        $targetYear = ($this->year() + $years);
+        $clampedDay = CalendarDay::clamp(year: $targetYear, month: $this->month(), day: $this->dayOfMonth());
+
+        return LocalDate::of(year: $targetYear, month: $this->month(), day: $clampedDay);
+    }
+
     /**
      * Returns the LocalDate as an ISO 8601 date string (YYYY-MM-DD).
      *
@@ -179,13 +208,82 @@ public function toIso8601(): string
     /**
      * Returns the day of the month.
      *
-     * @return int The day (1–31).
+     * @return int The day (1-31).
      */
     public function dayOfMonth(): int
     {
         return (int)$this->date->format('j');
     }
 
+    /**
+     * Returns a copy of this date shifted backward by the given number of years.
+     *
+     * <p>A negative count shifts forward. February 29 shifted onto a common year is clamped to
+     * February 28, exactly as the month shift clamps in {@see LocalDate::plusMonths()}.</p>
+     *
+     * @param int $years The number of years to subtract (may be negative).
+     * @return LocalDate A new LocalDate with the year shifted and the day clamped.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function minusYears(int $years): LocalDate
+    {
+        return $this->plusYears(years: -$years);
+    }
+
+    /**
+     * Returns a copy of this date shifted forward by the given number of months.
+     *
+     * <p>A negative count shifts backward. The shift moves the year and month first, then clamps
+     * the day to the last valid day of the target month. When the original day does not exist in a
+     * shorter target month, the result lands on that month's final day.</p>
+     *
+     * <ul>
+     * <li>2026-01-31 plus 1 month becomes 2026-02-28.</li>
+     * <li>2028-01-31 plus 1 month becomes 2028-02-29.</li>
+     * <li>2026-03-31 minus 1 month becomes 2026-02-28.</li>
+     * </ul>
+     *
+     * <p>Because the day is clamped, the operation is not associative. Shifting 2026-01-31
+     * forward by 1 month and then back by 1 month yields 2026-01-28, not the original day.</p>
+     *
+     * @param int $months The number of months to add (may be negative).
+     * @return LocalDate A new LocalDate with the year and month shifted and the day clamped.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function plusMonths(int $months): LocalDate
+    {
+        $baseMonths = (($this->year() * 12) + ($this->month() - 1));
+        $lowestShift = ((self::MIN_YEAR * 12) - $baseMonths);
+        $highestShift = ((self::MAX_YEAR * 12) + 11 - $baseMonths);
+
+        if ($months < $lowestShift || $months > $highestShift) {
+            throw InvalidLocalDate::becauseShiftIsOutOfRange();
+        }
+
+        $totalMonths = ($baseMonths + $months);
+        $targetYear = intdiv($totalMonths, 12);
+        $targetMonth = (($totalMonths % 12) + 1);
+        $clampedDay = CalendarDay::clamp(year: $targetYear, month: $targetMonth, day: $this->dayOfMonth());
+
+        return LocalDate::of(year: $targetYear, month: $targetMonth, day: $clampedDay);
+    }
+
+    /**
+     * Returns a copy of this date shifted backward by the given number of months.
+     *
+     * <p>A negative count shifts forward. The day is clamped to the last valid day of the target
+     * month, exactly as in {@see LocalDate::plusMonths()}. Because of the clamp, the operation is
+     * not associative.</p>
+     *
+     * @param int $months The number of months to subtract (may be negative).
+     * @return LocalDate A new LocalDate with the year and month shifted and the day clamped.
+     * @throws InvalidLocalDate If the resulting date falls outside the range 0001 to 9999.
+     */
+    public function minusMonths(int $months): LocalDate
+    {
+        return $this->plusMonths(months: -$months);
+    }
+
     /**
      * Tells whether this date is after or equal to another.
      *
diff --git a/src/Stopwatch.php b/src/Stopwatch.php
index 4a7cdfd..2761c37 100644
--- a/src/Stopwatch.php
+++ b/src/Stopwatch.php
@@ -37,6 +37,6 @@ public static function start(MonotonicClock $clock): Stopwatch
      */
     public function elapsed(): Elapsed
     {
-        return Elapsed::fromNanoseconds(nanoseconds: $this->clock->nanoseconds() - $this->startedAt);
+        return Elapsed::fromNanoseconds(nanoseconds: ($this->clock->nanoseconds() - $this->startedAt));
     }
 }
diff --git a/src/TimeOfDay.php b/src/TimeOfDay.php
index 4c1b30e..59394ff 100644
--- a/src/TimeOfDay.php
+++ b/src/TimeOfDay.php
@@ -154,7 +154,7 @@ public function toDuration(): Duration
      */
     public function durationUntil(TimeOfDay $other): Duration
     {
-        $difference = $other->toMinutesSinceMidnight() - $this->toMinutesSinceMidnight();
+        $difference = ($other->toMinutesSinceMidnight() - $this->toMinutesSinceMidnight());
 
         if ($difference <= 0) {
             throw InvalidTimeOfDay::becauseEndIsNotAfterStart(from: $this, to: $other);
@@ -192,6 +192,6 @@ public function isBeforeOrEqual(TimeOfDay $other): bool
      */
     public function toMinutesSinceMidnight(): int
     {
-        return ($this->hour * self::MINUTES_PER_HOUR) + $this->minute;
+        return (($this->hour * self::MINUTES_PER_HOUR) + $this->minute);
     }
 }
diff --git a/src/Timezones.php b/src/Timezones.php
index 532385d..49a6a95 100644
--- a/src/Timezones.php
+++ b/src/Timezones.php
@@ -107,6 +107,6 @@ public function findByIdentifier(string $iana): ?Timezone
      */
     public function findByIdentifierOrUtc(string $iana): Timezone
     {
-        return $this->findByIdentifier(iana: $iana) ?? Timezone::utc();
+        return ($this->findByIdentifier(iana: $iana) ?? Timezone::utc());
     }
 }
diff --git a/tests/Unit/CalendarDayTest.php b/tests/Unit/CalendarDayTest.php
new file mode 100644
index 0000000..a9f2213
--- /dev/null
+++ b/tests/Unit/CalendarDayTest.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\Time\Unit;
+
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use ReflectionMethod;
+use TinyBlocks\Time\Internal\CalendarDay;
+
+final class CalendarDayTest extends TestCase
+{
+    public function testConstructorWhenInvokedViaReflectionThenInstanceIsCreated(): void
+    {
+        /** @Given an instance allocated without invoking the private constructor */
+        $instance = new ReflectionClass(CalendarDay::class)->newInstanceWithoutConstructor();
+
+        /** @When the private constructor of the static-only collaborator is invoked through reflection */
+        new ReflectionMethod(CalendarDay::class, '__construct')->invoke($instance);
+
+        /** @Then the collaborator is instantiated */
+        self::assertInstanceOf(CalendarDay::class, $instance);
+    }
+}
diff --git a/tests/Unit/DayOfWeekTest.php b/tests/Unit/DayOfWeekTest.php
index 793233c..8ff2ee5 100644
--- a/tests/Unit/DayOfWeekTest.php
+++ b/tests/Unit/DayOfWeekTest.php
@@ -287,7 +287,7 @@ public function testDistanceToWhenComputedInBothDirectionsThenIsNotSymmetric(
         self::assertSame($expectedBackward, $backward);
 
         /** @And together they should complete a full week */
-        self::assertSame(7, $expectedForward + $expectedBackward);
+        self::assertSame(7, ($expectedForward + $expectedBackward));
     }
 
     public static function forwardDistanceDataProvider(): array
diff --git a/tests/Unit/DurationTest.php b/tests/Unit/DurationTest.php
index f5eccc0..8d8614b 100644
--- a/tests/Unit/DurationTest.php
+++ b/tests/Unit/DurationTest.php
@@ -445,7 +445,7 @@ public function testFromMinutesWhenReconstructedFromSlotCountThenMatchesOriginal
         $slotCount = $appointmentDuration->divide(other: $slotSize);
 
         /** @When reconstructing a Duration from the slot count and slot size */
-        $reconstructed = Duration::fromMinutes(minutes: $slotCount * $slotSize->toMinutes());
+        $reconstructed = Duration::fromMinutes(minutes: ($slotCount * $slotSize->toMinutes()));
 
         /** @Then it should match the original appointment duration */
         self::assertSame($appointmentDuration->toSeconds(), $reconstructed->toSeconds());
diff --git a/tests/Unit/InstantSerializationTest.php b/tests/Unit/InstantSerializationTest.php
index 973de29..fc59f84 100644
--- a/tests/Unit/InstantSerializationTest.php
+++ b/tests/Unit/InstantSerializationTest.php
@@ -7,8 +7,8 @@
 use PHPUnit\Framework\TestCase;
 use Test\TinyBlocks\Time\Models\Event;
 use TinyBlocks\Mapper\Mapper;
-use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\Exceptions\InvalidInstant;
+use TinyBlocks\Time\Instant;
 
 final class InstantSerializationTest extends TestCase
 {
diff --git a/tests/Unit/InstantTest.php b/tests/Unit/InstantTest.php
index 2da162a..c469447 100644
--- a/tests/Unit/InstantTest.php
+++ b/tests/Unit/InstantTest.php
@@ -7,9 +7,11 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 use TinyBlocks\Time\Duration;
+use TinyBlocks\Time\Exceptions\InvalidInstant;
+use TinyBlocks\Time\Exceptions\InvalidLocalDate;
 use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\Precision;
-use TinyBlocks\Time\Exceptions\InvalidInstant;
+use TinyBlocks\Time\Timezone;
 
 final class InstantTest extends TestCase
 {
@@ -141,6 +143,18 @@ public function testNowThenIso8601HasNoFractionalSeconds(): void
         self::assertMatchesRegularExpression('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$/', $iso);
     }
 
+    public function testPlusYearsWhenCommonDateThenShiftsYear(): void
+    {
+        /** @Given an Instant on a common day */
+        $instant = Instant::fromString(value: '2026-05-15T10:00:00+00:00');
+
+        /** @When adding two years */
+        $shifted = $instant->plusYears(years: 2);
+
+        /** @Then the year is shifted forward and the time of day is preserved */
+        self::assertSame('2028-05-15T10:00:00+00:00', $shifted->toIso8601());
+    }
+
     public function testIsAfterOrEqualWhenEqualThenReturnsTrue(): void
     {
         /** @Given an Instant at a known moment */
@@ -171,6 +185,30 @@ public function testIsAfterOrEqualWhenLaterThenReturnsTrue(): void
         self::assertTrue($isAfterOrEqual);
     }
 
+    public function testMinusYearsWhenCommonDateThenShiftsYear(): void
+    {
+        /** @Given an Instant on a common day */
+        $instant = Instant::fromString(value: '2026-05-15T10:00:00+00:00');
+
+        /** @When subtracting two years */
+        $shifted = $instant->minusYears(years: 2);
+
+        /** @Then the year is shifted backward and the time of day is preserved */
+        self::assertSame('2024-05-15T10:00:00+00:00', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenNoZoneThenReanchorsInUtc(): void
+    {
+        /** @Given an Instant on the last day of a 31-day month */
+        $instant = Instant::fromString(value: '2026-01-31T10:00:00+00:00');
+
+        /** @When adding one month without a zone, defaulting to UTC */
+        $shifted = $instant->plusMonths(months: 1);
+
+        /** @Then the date is shifted and clamped while the time of day is preserved */
+        self::assertSame('2026-02-28T10:00:00+00:00', $shifted->toIso8601());
+    }
+
     public function testIsBeforeOrEqualWhenEqualThenReturnsTrue(): void
     {
         /** @Given an Instant at a known moment */
@@ -192,10 +230,22 @@ public function testPlusWhenZeroDurationThenReturnsSameTime(): void
         $instant = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
 
         /** @When adding zero Duration */
-        $result = $instant->plus(duration: Duration::zero());
+        $shifted = $instant->plus(duration: Duration::zero());
 
         /** @Then the result should be the same time */
-        self::assertSame('2026-02-17T10:00:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-17T10:00:00+00:00', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenLeapDayThenClampsToLastDay(): void
+    {
+        /** @Given an Instant on the leap day of a leap year */
+        $instant = Instant::fromString(value: '2024-02-29T10:00:00+00:00');
+
+        /** @When adding one year to a common year */
+        $shifted = $instant->plusYears(years: 1);
+
+        /** @Then the day is clamped to the last day of February and the time is preserved */
+        self::assertSame('2025-02-28T10:00:00+00:00', $shifted->toIso8601());
     }
 
     public function testIsBeforeOrEqualWhenLaterThenReturnsFalse(): void
@@ -213,16 +263,40 @@ public function testIsBeforeOrEqualWhenLaterThenReturnsFalse(): void
         self::assertFalse($isBeforeOrEqual);
     }
 
+    public function testMinusMonthsWhenNegativeThenShiftsForward(): void
+    {
+        /** @Given an Instant on the last day of a 31-day month */
+        $instant = Instant::fromString(value: '2026-01-31T10:00:00+00:00');
+
+        /** @When subtracting -1 month (equivalent to adding 1) */
+        $shifted = $instant->minusMonths(months: -1);
+
+        /** @Then the date is shifted forward and clamped while the time is preserved */
+        self::assertSame('2026-02-28T10:00:00+00:00', $shifted->toIso8601());
+    }
+
     public function testMinusWhenZeroDurationThenReturnsSameTime(): void
     {
         /** @Given an Instant at a known time */
         $instant = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
 
         /** @When subtracting zero Duration */
-        $result = $instant->minus(duration: Duration::zero());
+        $shifted = $instant->minus(duration: Duration::zero());
 
         /** @Then the result should be the same time */
-        self::assertSame('2026-02-17T10:00:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-17T10:00:00+00:00', $shifted->toIso8601());
+    }
+
+    public function testMinusYearsWhenLeapDayThenClampsToLastDay(): void
+    {
+        /** @Given an Instant on the leap day of a leap year */
+        $instant = Instant::fromString(value: '2024-02-29T10:00:00+00:00');
+
+        /** @When subtracting one year to a common year */
+        $shifted = $instant->minusYears(years: 1);
+
+        /** @Then the day is clamped to the last day of February and the time is preserved */
+        self::assertSame('2023-02-28T10:00:00+00:00', $shifted->toIso8601());
     }
 
     public function testIsAfterOrEqualWhenEarlierThenReturnsFalse(): void
@@ -264,10 +338,10 @@ public function testPlusWhenDurationProvidedThenShiftsForward(): void
         $duration = Duration::fromMinutes(minutes: 30);
 
         /** @When adding the Duration */
-        $result = $instant->plus(duration: $duration);
+        $shifted = $instant->plus(duration: $duration);
 
         /** @Then the result should be 30 minutes later */
-        self::assertSame('2026-02-17T10:30:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-17T10:30:00+00:00', $shifted->toIso8601());
     }
 
     public function testNowThenMicrosecondComponentIsRepresentable(): void
@@ -317,10 +391,10 @@ public function testMinusWhenDurationProvidedThenShiftsBackward(): void
         $duration = Duration::fromMinutes(minutes: 30);
 
         /** @When subtracting the Duration */
-        $result = $instant->minus(duration: $duration);
+        $shifted = $instant->minus(duration: $duration);
 
         /** @Then the result should be 30 minutes earlier */
-        self::assertSame('2026-02-17T10:00:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-17T10:00:00+00:00', $shifted->toIso8601());
     }
 
     public function testDurationUntilWhenSwappedThenReturnsSameValue(): void
@@ -338,16 +412,28 @@ public function testDurationUntilWhenSwappedThenReturnsSameValue(): void
         self::assertSame($duration->toSeconds(), $later->durationUntil(other: $earlier)->toSeconds());
     }
 
+    public function testMinusMonthsWhenDefaultZoneThenShiftsBackward(): void
+    {
+        /** @Given an Instant on the last day of a 31-day month */
+        $instant = Instant::fromString(value: '2026-03-31T10:00:00+00:00');
+
+        /** @When subtracting one month without a zone, defaulting to UTC */
+        $shifted = $instant->minusMonths(months: 1);
+
+        /** @Then the date is shifted backward and clamped while the time is preserved */
+        self::assertSame('2026-02-28T10:00:00+00:00', $shifted->toIso8601());
+    }
+
     public function testPlusWhenCrossesDayBoundaryThenReturnsNextDay(): void
     {
         /** @Given an Instant near the end of the day */
         $instant = Instant::fromString(value: '2026-02-17T23:30:00+00:00');
 
         /** @When adding 1 hour */
-        $result = $instant->plus(duration: Duration::fromHours(hours: 1));
+        $shifted = $instant->plus(duration: Duration::fromHours(hours: 1));
 
         /** @Then the result should cross into the next day */
-        self::assertSame('2026-02-18T00:30:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-18T00:30:00+00:00', $shifted->toIso8601());
     }
 
     public function testFromStringWhenDatabaseFormatThenTimezoneIsUtc(): void
@@ -386,6 +472,18 @@ public function testToIso8601WhenNoPrecisionThenDefaultsToSeconds(): void
         self::assertSame('2026-02-17T08:27:21+00:00', $iso);
     }
 
+    public function testPlusMonthsWhenZeroThenReturnsEquivalentInstant(): void
+    {
+        /** @Given an Instant at a known moment */
+        $instant = Instant::fromString(value: '2026-05-23T10:00:00+00:00');
+
+        /** @When adding zero months */
+        $shifted = $instant->plusMonths(months: 0);
+
+        /** @Then the result is an equivalent instant */
+        self::assertSame('2026-05-23T10:00:00+00:00', $shifted->toIso8601());
+    }
+
     public function testFromStringWhenNegativeOffsetThenNormalizesToUtc(): void
     {
         /** @When creating an Instant from a string with a negative offset */
@@ -413,10 +511,10 @@ public function testPlusWhenLargeDurationThenShiftsForwardCorrectly(): void
         $instant = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
 
         /** @When adding 1 day */
-        $result = $instant->plus(duration: Duration::fromDays(days: 1));
+        $shifted = $instant->plus(duration: Duration::fromDays(days: 1));
 
         /** @Then the result should be exactly one day later */
-        self::assertSame('2026-02-18T10:00:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-18T10:00:00+00:00', $shifted->toIso8601());
     }
 
     public function testPlusWhenDurationProvidedThenPreservesUtcTimezone(): void
@@ -425,10 +523,25 @@ public function testPlusWhenDurationProvidedThenPreservesUtcTimezone(): void
         $instant = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
 
         /** @When adding a Duration */
-        $result = $instant->plus(duration: Duration::fromMinutes(minutes: 90));
+        $shifted = $instant->plus(duration: Duration::fromMinutes(minutes: 90));
 
         /** @Then the result should remain in UTC */
-        self::assertSame('UTC', $result->toDateTimeImmutable()->getTimezone()->getName());
+        self::assertSame('UTC', $shifted->toDateTimeImmutable()->getTimezone()->getName());
+    }
+
+    public function testPlusYearsWhenZoneProvidedThenReanchorsInThatZone(): void
+    {
+        /** @Given an Instant whose Tokyo local date is the leap day but whose UTC date is not */
+        $instant = Instant::fromString(value: '2024-02-28T20:00:00+00:00');
+
+        /** @And the Tokyo timezone */
+        $zone = Timezone::from(identifier: 'Asia/Tokyo');
+
+        /** @When adding one year re-anchored in Tokyo */
+        $shifted = $instant->plusYears(years: 1, zone: $zone);
+
+        /** @Then the shift follows the Tokyo local date, clamped, and normalizes back to UTC */
+        self::assertSame('2025-02-27T20:00:00+00:00', $shifted->toIso8601());
     }
 
     public function testFromUnixSecondsWhenEpochThenReturnsUnixEpochInUtc(): void
@@ -449,10 +562,10 @@ public function testMinusWhenCrossesDayBoundaryThenReturnsPreviousDay(): void
         $instant = Instant::fromString(value: '2026-02-17T00:30:00+00:00');
 
         /** @When subtracting 1 hour */
-        $result = $instant->minus(duration: Duration::fromHours(hours: 1));
+        $shifted = $instant->minus(duration: Duration::fromHours(hours: 1));
 
         /** @Then the result should cross into the previous day */
-        self::assertSame('2026-02-16T23:30:00+00:00', $result->toIso8601());
+        self::assertSame('2026-02-16T23:30:00+00:00', $shifted->toIso8601());
     }
 
     public function testMinusWhenDurationProvidedThenPreservesUtcTimezone(): void
@@ -461,10 +574,25 @@ public function testMinusWhenDurationProvidedThenPreservesUtcTimezone(): void
         $instant = Instant::fromString(value: '2026-02-17T10:00:00+00:00');
 
         /** @When subtracting a Duration */
-        $result = $instant->minus(duration: Duration::fromMinutes(minutes: 90));
+        $shifted = $instant->minus(duration: Duration::fromMinutes(minutes: 90));
 
         /** @Then the result should remain in UTC */
-        self::assertSame('UTC', $result->toDateTimeImmutable()->getTimezone()->getName());
+        self::assertSame('UTC', $shifted->toDateTimeImmutable()->getTimezone()->getName());
+    }
+
+    public function testPlusMonthsWhenZoneProvidedThenReanchorsInThatZone(): void
+    {
+        /** @Given an Instant whose local date in Tokyo differs from its UTC date */
+        $instant = Instant::fromString(value: '2026-01-30T20:00:00+00:00');
+
+        /** @And the Tokyo timezone */
+        $zone = Timezone::from(identifier: 'Asia/Tokyo');
+
+        /** @When adding one month re-anchored in Tokyo */
+        $shifted = $instant->plusMonths(months: 1, zone: $zone);
+
+        /** @Then the shift follows the Tokyo local date, clamped, and normalizes back to UTC */
+        self::assertSame('2026-02-27T20:00:00+00:00', $shifted->toIso8601());
     }
 
     public function testPlusWhenPositiveDurationThenResultIsAfterOriginal(): void
@@ -513,6 +641,18 @@ public function testFromStringWhenMaxPositiveOffsetThenNormalizesToUtc(): void
         self::assertSame('2026-02-17T00:00:00+00:00', $instant->toIso8601());
     }
 
+    public function testPlusMonthsWhenMicrosecondsPresentThenPreservesThem(): void
+    {
+        /** @Given an Instant carrying microsecond precision */
+        $instant = Instant::fromString(value: '2026-01-31T12:34:56.789012+00:00');
+
+        /** @When adding one month */
+        $shifted = $instant->plusMonths(months: 1);
+
+        /** @Then the microseconds are preserved after the shift and clamp */
+        self::assertSame('2026-02-28T12:34:56.789012+00:00', $shifted->toIso8601(precision: Precision::Microseconds));
+    }
+
     public function testMinusWhenPositiveDurationThenResultIsBeforeOriginal(): void
     {
         /** @Given an Instant at a known time */
@@ -538,6 +678,19 @@ public function testFromUnixSecondsWhenNegativeThenReturnsDateBeforeEpoch(): voi
         self::assertSame(-86400, $instant->toUnixSeconds());
     }
 
+    public function testPlusYearsWhenArgumentIsIntegerMaxThenInvalidLocalDate(): void
+    {
+        /** @Given an Instant at a known moment */
+        $instant = Instant::fromString(value: '2026-05-15T10:00:00+00:00');
+
+        /** @Then an out-of-range shift is raised instead of an arithmetic overflow */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When adding the maximum integer number of years re-anchored in UTC */
+        $instant->plusYears(years: PHP_INT_MAX);
+    }
+
     public function testToIso8601WhenFromValidStringThenHasNoFractionalSeconds(): void
     {
         /** @Given an Instant created from any valid input */
@@ -603,11 +756,11 @@ public function testPlusWhenFollowedByMinusOfSameDurationThenReturnsOriginal():
         $duration = Duration::fromMinutes(minutes: 45);
 
         /** @When adding and then subtracting the same Duration */
-        $result = $instant->plus(duration: $duration)->minus(duration: $duration);
+        $shifted = $instant->plus(duration: $duration)->minus(duration: $duration);
 
         /** @Then the result should be the original time */
-        self::assertSame($instant->toIso8601(), $result->toIso8601());
-        self::assertSame($instant->toUnixSeconds(), $result->toUnixSeconds());
+        self::assertSame($instant->toIso8601(), $shifted->toIso8601());
+        self::assertSame($instant->toUnixSeconds(), $shifted->toUnixSeconds());
     }
 
     public function testComparisonsWhenSameMomentFromDifferentOriginsThenAllAgree(): void
@@ -644,6 +797,19 @@ public function testDurationUntilWhenInstantsDifferThenReturnsAbsoluteDistance()
         self::assertSame(1800, $later->durationUntil(other: $earlier)->toSeconds());
     }
 
+    public function testPlusMonthsWhenResultExceedsMaximumYearThenInvalidLocalDate(): void
+    {
+        /** @Given an Instant in the last month of the maximum supported year */
+        $instant = Instant::fromString(value: '9999-12-01T10:00:00+00:00');
+
+        /** @Then an exception indicating an out-of-range shift should be thrown */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When adding one month crosses above the maximum year */
+        $instant->plusMonths(months: 1);
+    }
+
     public function testDurationUntilWhenAcrossDayBoundaryThenReturnsCorrectSeconds(): void
     {
         /** @Given an Instant before midnight */
@@ -732,6 +898,21 @@ public function testDurationUntilWhenSameMomentFromDifferentOriginsThenReturnsZe
         self::assertTrue($duration->isZero());
     }
 
+    public function testPlusMonthsWhenTargetLocalTimeFallsInDstGapThenPhpShiftsForward(): void
+    {
+        /** @Given an Instant whose local time in New York is 2026-02-08 02:30 */
+        $instant = Instant::fromString(value: '2026-02-08T07:30:00+00:00');
+
+        /** @And the America/New_York timezone */
+        $zone = Timezone::from(identifier: 'America/New_York');
+
+        /** @When adding one month lands on the non-existent local 2026-03-08 02:30 spring-forward gap */
+        $shifted = $instant->plusMonths(months: 1, zone: $zone);
+
+        /** @Then PHP shifts the local time forward to 03:30 -04:00, which is 07:30 UTC */
+        self::assertSame('2026-03-08T07:30:00+00:00', $shifted->toIso8601());
+    }
+
     public function testDurationUntilWhenInstantShiftedByDurationThenEqualsThatDuration(): void
     {
         /** @Given an Instant at a known time */
diff --git a/tests/Unit/LocalDateTest.php b/tests/Unit/LocalDateTest.php
index 464cdd7..a81d9e1 100644
--- a/tests/Unit/LocalDateTest.php
+++ b/tests/Unit/LocalDateTest.php
@@ -9,10 +9,10 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 use TinyBlocks\Time\DayOfWeek;
+use TinyBlocks\Time\Exceptions\InvalidLocalDate;
 use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\LocalDate;
 use TinyBlocks\Time\Timezone;
-use TinyBlocks\Time\Exceptions\InvalidLocalDate;
 
 final class LocalDateTest extends TestCase
 {
@@ -232,10 +232,10 @@ public function testPlusDaysWhenZeroThenReturnsSameDate(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When adding zero days */
-        $result = $date->plusDays(days: 0);
+        $shifted = $date->plusDays(days: 0);
 
         /** @Then the result is the same date */
-        self::assertSame('2026-05-23', $result->toIso8601());
+        self::assertSame('2026-05-23', $shifted->toIso8601());
     }
 
     public function testDayOfWeekWhenMondayThenReturnsMonday(): void
@@ -256,10 +256,10 @@ public function testMinusDaysWhenZeroThenReturnsSameDate(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When subtracting zero days */
-        $result = $date->minusDays(days: 0);
+        $shifted = $date->minusDays(days: 0);
 
         /** @Then the result is the same date */
-        self::assertSame('2026-05-23', $result->toIso8601());
+        self::assertSame('2026-05-23', $shifted->toIso8601());
     }
 
     public function testOfWhenDayAboveMaxThenInvalidLocalDate(): void
@@ -278,10 +278,22 @@ public function testPlusDaysWhenPositiveThenShiftsForward(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When adding 7 days */
-        $result = $date->plusDays(days: 7);
+        $shifted = $date->plusDays(days: 7);
 
         /** @Then the result is 7 days later */
-        self::assertSame('2026-05-30', $result->toIso8601());
+        self::assertSame('2026-05-30', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenCommonDateThenShiftsYear(): void
+    {
+        /** @Given a LocalDate on a common day */
+        $date = LocalDate::of(year: 2026, month: 5, day: 15);
+
+        /** @When adding two years */
+        $shifted = $date->plusYears(years: 2);
+
+        /** @Then the year is shifted forward and the month and day are preserved */
+        self::assertSame('2028-05-15', $shifted->toIso8601());
     }
 
     public function testFromStringThenRoundTripsThroughIso8601(): void
@@ -302,10 +314,22 @@ public function testMinusDaysWhenNegativeThenShiftsForward(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When subtracting -3 days (equivalent to adding 3) */
-        $result = $date->minusDays(days: -3);
+        $shifted = $date->minusDays(days: -3);
 
         /** @Then the result is 3 days later */
-        self::assertSame('2026-05-26', $result->toIso8601());
+        self::assertSame('2026-05-26', $shifted->toIso8601());
+    }
+
+    public function testMinusYearsWhenCommonDateThenShiftsYear(): void
+    {
+        /** @Given a LocalDate on a common day */
+        $date = LocalDate::of(year: 2026, month: 5, day: 15);
+
+        /** @When subtracting two years */
+        $shifted = $date->minusYears(years: 2);
+
+        /** @Then the year is shifted backward and the month and day are preserved */
+        self::assertSame('2024-05-15', $shifted->toIso8601());
     }
 
     public function testOfWhenValidComponentsThenDateIsCreated(): void
@@ -326,10 +350,10 @@ public function testPlusDaysWhenNegativeThenShiftsBackward(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When adding -3 days (equivalent to subtracting 3) */
-        $result = $date->plusDays(days: -3);
+        $shifted = $date->plusDays(days: -3);
 
         /** @Then the result is 3 days earlier */
-        self::assertSame('2026-05-20', $result->toIso8601());
+        self::assertSame('2026-05-20', $shifted->toIso8601());
     }
 
     public function testTodayWhenUtcThenDateIsWithinCurrentDay(): void
@@ -354,10 +378,10 @@ public function testMinusDaysWhenPositiveThenShiftsBackward(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When subtracting 7 days */
-        $result = $date->minusDays(days: 7);
+        $shifted = $date->minusDays(days: 7);
 
         /** @Then the result is 7 days earlier */
-        self::assertSame('2026-05-16', $result->toIso8601());
+        self::assertSame('2026-05-16', $shifted->toIso8601());
     }
 
     public function testDayOfWeekWhenSaturdayThenReturnsSaturday(): void
@@ -372,6 +396,18 @@ public function testDayOfWeekWhenSaturdayThenReturnsSaturday(): void
         self::assertSame(DayOfWeek::Saturday, $dayOfWeek);
     }
 
+    public function testMinusMonthsWhenNegativeThenShiftsForward(): void
+    {
+        /** @Given a LocalDate */
+        $date = LocalDate::of(year: 2026, month: 1, day: 15);
+
+        /** @When subtracting -1 month (equivalent to adding 1) */
+        $shifted = $date->minusMonths(months: -1);
+
+        /** @Then the result is one month later */
+        self::assertSame('2026-02-15', $shifted->toIso8601());
+    }
+
     public function testOfWhenLeapDayOnLeapYearThenDateIsCreated(): void
     {
         /** @When creating a LocalDate for February 29 on a leap year */
@@ -391,6 +427,18 @@ public function testOfWhenYearAboveLimitThenInvalidLocalDate(): void
         LocalDate::of(year: 10000, month: 1, day: 1);
     }
 
+    public function testPlusMonthsWhenNegativeThenShiftsBackward(): void
+    {
+        /** @Given a LocalDate */
+        $date = LocalDate::of(year: 2026, month: 3, day: 15);
+
+        /** @When adding -1 month (equivalent to subtracting 1) */
+        $shifted = $date->plusMonths(months: -1);
+
+        /** @Then the result is one month earlier */
+        self::assertSame('2026-02-15', $shifted->toIso8601());
+    }
+
     public function testOfWhenMonthAboveRangeThenInvalidLocalDate(): void
     {
         /** @Then an exception indicating invalid components should be thrown */
@@ -413,6 +461,66 @@ public function testFromStringWhenValidIso8601ThenDateIsCreated(): void
         self::assertSame('2026-05-23', $date->toIso8601());
     }
 
+    public function testPlusMonthsWhenZeroThenReturnsEquivalentDate(): void
+    {
+        /** @Given a LocalDate */
+        $date = LocalDate::of(year: 2026, month: 5, day: 23);
+
+        /** @When adding zero months */
+        $shifted = $date->plusMonths(months: 0);
+
+        /** @Then the result is an equivalent date */
+        self::assertSame('2026-05-23', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenLandsOnMaximumYearThenSucceeds(): void
+    {
+        /** @Given a date one year below the maximum supported year */
+        $date = LocalDate::of(year: 9998, month: 5, day: 15);
+
+        /** @When adding one year to reach the maximum year */
+        $shifted = $date->plusYears(years: 1);
+
+        /** @Then the result lands on the maximum supported year */
+        self::assertSame('9999-05-15', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenLandsOnMinimumYearThenSucceeds(): void
+    {
+        /** @Given a date one year above the minimum supported year */
+        $date = LocalDate::of(year: 2, month: 5, day: 15);
+
+        /** @When subtracting one year to reach the minimum year */
+        $shifted = $date->plusYears(years: -1);
+
+        /** @Then the result lands on the minimum supported year */
+        self::assertSame('0001-05-15', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenLeapDayThenClampsToTwentyEight(): void
+    {
+        /** @Given the leap day of a leap year */
+        $date = LocalDate::of(year: 2024, month: 2, day: 29);
+
+        /** @When adding one year to a common year */
+        $shifted = $date->plusYears(years: 1);
+
+        /** @Then the day is clamped to the last day of February */
+        self::assertSame('2025-02-28', $shifted->toIso8601());
+    }
+
+    public function testMinusYearsWhenLeapDayThenClampsToTwentyEight(): void
+    {
+        /** @Given the leap day of a leap year */
+        $date = LocalDate::of(year: 2024, month: 2, day: 29);
+
+        /** @When subtracting one year to a common year */
+        $shifted = $date->minusYears(years: 1);
+
+        /** @Then the day is clamped to the last day of February */
+        self::assertSame('2023-02-28', $shifted->toIso8601());
+    }
+
     public function testOfWhenInvalidDayForMonthThenInvalidLocalDate(): void
     {
         /** @Then an exception indicating invalid components should be thrown */
@@ -441,6 +549,18 @@ public function testOfWhenYearAtMinimumBoundaryThenDateIsCreated(): void
         self::assertSame('0001-01-01', $date->toIso8601());
     }
 
+    public function testPlusMonthsWhenTargetIsJuneThenClampsToThirty(): void
+    {
+        /** @Given the last day of May */
+        $date = LocalDate::of(year: 2026, month: 5, day: 31);
+
+        /** @When adding one month to reach June */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the last day of June */
+        self::assertSame('2026-06-30', $shifted->toIso8601());
+    }
+
     public function testInstantToLocalDateWhenUtcMidnightThenSameDate(): void
     {
         /** @Given an Instant at midnight UTC on a known date */
@@ -459,10 +579,10 @@ public function testPlusDaysWhenCrossesLeapDayThenIncludesLeapDay(): void
         $date = LocalDate::of(year: 2024, month: 2, day: 28);
 
         /** @When adding 1 day */
-        $result = $date->plusDays(days: 1);
+        $shifted = $date->plusDays(days: 1);
 
         /** @Then the result is the leap day */
-        self::assertSame('2024-02-29', $result->toIso8601());
+        self::assertSame('2024-02-29', $shifted->toIso8601());
     }
 
     public function testPlusDaysWhenCrossesYearBoundaryThenShiftsYear(): void
@@ -471,10 +591,34 @@ public function testPlusDaysWhenCrossesYearBoundaryThenShiftsYear(): void
         $date = LocalDate::of(year: 2026, month: 12, day: 31);
 
         /** @When adding 1 day */
-        $result = $date->plusDays(days: 1);
+        $shifted = $date->plusDays(days: 1);
 
         /** @Then the result is the first day of the following year */
-        self::assertSame('2027-01-01', $result->toIso8601());
+        self::assertSame('2027-01-01', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenLandsOnMaximumMonthThenSucceeds(): void
+    {
+        /** @Given a date one month below the last month of the maximum year */
+        $date = LocalDate::of(year: 9999, month: 11, day: 15);
+
+        /** @When adding one month to reach the last supported month */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the result lands on the last month of the maximum year */
+        self::assertSame('9999-12-15', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenLandsOnMinimumMonthThenSucceeds(): void
+    {
+        /** @Given a date one month above the first month of the minimum year */
+        $date = LocalDate::of(year: 1, month: 2, day: 15);
+
+        /** @When subtracting one month to reach the first supported month */
+        $shifted = $date->plusMonths(months: -1);
+
+        /** @Then the result lands on the first month of the minimum year */
+        self::assertSame('0001-01-15', $shifted->toIso8601());
     }
 
     #[DataProvider('invalidStringsDataProvider')]
@@ -495,10 +639,10 @@ public function testMinusDaysWhenCrossesYearBoundaryThenShiftsYear(): void
         $date = LocalDate::of(year: 2027, month: 1, day: 1);
 
         /** @When subtracting 1 day */
-        $result = $date->minusDays(days: 1);
+        $shifted = $date->minusDays(days: 1);
 
         /** @Then the result is the last day of the previous year */
-        self::assertSame('2026-12-31', $result->toIso8601());
+        self::assertSame('2026-12-31', $shifted->toIso8601());
     }
 
     public function testOfWhenLeapDayOnNonLeapYearThenInvalidLocalDate(): void
@@ -529,10 +673,22 @@ public function testPlusDaysWhenCrossesMonthBoundaryThenShiftsMonth(): void
         $date = LocalDate::of(year: 2026, month: 5, day: 29);
 
         /** @When adding 3 days */
-        $result = $date->plusDays(days: 3);
+        $shifted = $date->plusDays(days: 3);
 
         /** @Then the result crosses into June */
-        self::assertSame('2026-06-01', $result->toIso8601());
+        self::assertSame('2026-06-01', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenCrossesYearBoundaryThenShiftsYear(): void
+    {
+        /** @Given a date late in the year */
+        $date = LocalDate::of(year: 2026, month: 11, day: 15);
+
+        /** @When adding three months */
+        $shifted = $date->plusMonths(months: 3);
+
+        /** @Then the result crosses into the following year */
+        self::assertSame('2027-02-15', $shifted->toIso8601());
     }
 
     public function testMinusDaysWhenCrossesMonthBoundaryThenShiftsMonth(): void
@@ -541,10 +697,10 @@ public function testMinusDaysWhenCrossesMonthBoundaryThenShiftsMonth(): void
         $date = LocalDate::of(year: 2026, month: 6, day: 1);
 
         /** @When subtracting 3 days */
-        $result = $date->minusDays(days: 3);
+        $shifted = $date->minusDays(days: 3);
 
         /** @Then the result crosses back into May */
-        self::assertSame('2026-05-29', $result->toIso8601());
+        self::assertSame('2026-05-29', $shifted->toIso8601());
     }
 
     public function testMinusDaysWhenNegativeThenMatchesPlusDaysPositive(): void
@@ -577,6 +733,30 @@ public function testPlusDaysWhenNegativeThenMatchesMinusDaysPositive(): void
         self::assertSame($viaMinus->toIso8601(), $viaPlus->toIso8601());
     }
 
+    public function testPlusMonthsWhenDayFitsTargetMonthThenPreservesDay(): void
+    {
+        /** @Given a LocalDate whose day exists in the target month */
+        $date = LocalDate::of(year: 2026, month: 1, day: 15);
+
+        /** @When adding one month */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is preserved without clamping */
+        self::assertSame('2026-02-15', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenTargetIsNovemberThenClampsToThirty(): void
+    {
+        /** @Given the last day of October */
+        $date = LocalDate::of(year: 2026, month: 10, day: 31);
+
+        /** @When adding one month to reach November */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the last day of November */
+        self::assertSame('2026-11-30', $shifted->toIso8601());
+    }
+
     public function testToIso8601WhenValidDateThenReturnsFormattedString(): void
     {
         /** @Given a LocalDate for a known date */
@@ -601,6 +781,44 @@ public function testInstantToLocalDateWhenEastZoneIsAheadThenNextDate(): void
         self::assertSame('2026-02-18', $localDate->toIso8601());
     }
 
+    public function testPlusMonthsWhenTargetIsSeptemberThenClampsToThirty(): void
+    {
+        /** @Given the last day of August */
+        $date = LocalDate::of(year: 2026, month: 8, day: 31);
+
+        /** @When adding one month to reach September */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the last day of September */
+        self::assertSame('2026-09-30', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenBelowMinimumYearThenInvalidLocalDate(): void
+    {
+        /** @Given a date on the minimum supported year */
+        $date = LocalDate::of(year: 1, month: 5, day: 15);
+
+        /** @Then an exception indicating an out-of-range shift should be thrown */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When subtracting one year crosses below the minimum year */
+        $date->plusYears(years: -1);
+    }
+
+    public function testPlusYearsWhenExceedsMaximumYearThenInvalidLocalDate(): void
+    {
+        /** @Given a date on the maximum supported year */
+        $date = LocalDate::of(year: 9999, month: 5, day: 15);
+
+        /** @Then an exception indicating an out-of-range shift should be thrown */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When adding one year crosses above the maximum year */
+        $date->plusYears(years: 1);
+    }
+
     public function testToIso8601WhenYearBoundaryThenReturnsFormattedString(): void
     {
         /** @Given a LocalDate for the first day of a new year */
@@ -613,16 +831,78 @@ public function testToIso8601WhenYearBoundaryThenReturnsFormattedString(): void
         self::assertSame('2027-01-01', $iso);
     }
 
+    public function testPlusMonthsWhenTargetIsLeapFebruaryThenClampsToLeapDay(): void
+    {
+        /** @Given the last day of January in a leap year */
+        $date = LocalDate::of(year: 2028, month: 1, day: 31);
+
+        /** @When adding one month to reach February of the leap year */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the leap day */
+        self::assertSame('2028-02-29', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenTargetMonthIsShorterThenClampsToLastDay(): void
+    {
+        /** @Given the last day of a 31-day month */
+        $date = LocalDate::of(year: 2026, month: 1, day: 31);
+
+        /** @When adding one month to reach a 28-day month */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the last day of the target month */
+        self::assertSame('2026-02-28', $shifted->toIso8601());
+    }
+
+    public function testPlusYearsWhenArgumentIsIntegerMaxThenInvalidLocalDate(): void
+    {
+        /** @Given a date at a known moment */
+        $date = LocalDate::of(year: 2026, month: 5, day: 15);
+
+        /** @Then an out-of-range shift is raised instead of an arithmetic overflow */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When adding the maximum integer number of years */
+        $date->plusYears(years: PHP_INT_MAX);
+    }
+
+    public function testMinusMonthsWhenTargetMonthIsShorterThenClampsToLastDay(): void
+    {
+        /** @Given the last day of a 31-day month */
+        $date = LocalDate::of(year: 2026, month: 3, day: 31);
+
+        /** @When subtracting one month to reach a 28-day month */
+        $shifted = $date->minusMonths(months: 1);
+
+        /** @Then the day is clamped to the last day of the target month */
+        self::assertSame('2026-02-28', $shifted->toIso8601());
+    }
+
     public function testPlusDaysWhenFollowedByMinusDaysThenReturnsOriginalDate(): void
     {
         /** @Given a LocalDate */
         $date = LocalDate::of(year: 2026, month: 5, day: 23);
 
         /** @When adding 10 days and then subtracting 10 days */
-        $result = $date->plusDays(days: 10)->minusDays(days: 10);
+        $shifted = $date->plusDays(days: 10)->minusDays(days: 10);
 
         /** @Then the result is the original date */
-        self::assertSame($date->toIso8601(), $result->toIso8601());
+        self::assertSame($date->toIso8601(), $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenArgumentIsIntegerMaxThenInvalidLocalDate(): void
+    {
+        /** @Given a date at a known moment */
+        $date = LocalDate::of(year: 2026, month: 5, day: 15);
+
+        /** @Then an out-of-range shift is raised instead of an arithmetic overflow */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When adding the maximum integer number of months */
+        $date->plusMonths(months: PHP_INT_MAX);
     }
 
     public function testInstantToLocalDateWhenInUtcThenRoundTripsThroughIso8601(): void
@@ -637,6 +917,80 @@ public function testInstantToLocalDateWhenInUtcThenRoundTripsThroughIso8601(): v
         self::assertSame($localDate->toIso8601(), LocalDate::fromString(value: $localDate->toIso8601())->toIso8601());
     }
 
+    public function testPlusMonthsWhenFollowedByMinusMonthsThenIsNotAssociative(): void
+    {
+        /** @Given the last day of a 31-day month */
+        $date = LocalDate::of(year: 2026, month: 1, day: 31);
+
+        /** @When adding one month and then subtracting one month */
+        $shifted = $date->plusMonths(months: 1)->minusMonths(months: 1);
+
+        /** @Then the clamped day is not restored, so the operation is not associative */
+        self::assertSame('2026-01-28', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenTargetMonthHasThirtyDaysThenClampsToThirty(): void
+    {
+        /** @Given the last day of a 31-day month */
+        $date = LocalDate::of(year: 2026, month: 1, day: 31);
+
+        /** @When adding three months to reach a 30-day month */
+        $shifted = $date->plusMonths(months: 3);
+
+        /** @Then the day is clamped to the last day of the target month */
+        self::assertSame('2026-04-30', $shifted->toIso8601());
+    }
+
+    public function testMinusMonthsWhenResultBelowMinimumYearThenInvalidLocalDate(): void
+    {
+        /** @Given the first day of the minimum supported year */
+        $date = LocalDate::of(year: 1, month: 1, day: 1);
+
+        /** @Then an exception indicating an out-of-range shift should be thrown */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When subtracting one month crosses below the minimum year */
+        $date->minusMonths(months: 1);
+    }
+
+    public function testPlusMonthsWhenResultExceedsMaximumYearThenInvalidLocalDate(): void
+    {
+        /** @Given the last month of the maximum supported year */
+        $date = LocalDate::of(year: 9999, month: 12, day: 1);
+
+        /** @Then an exception indicating an out-of-range shift should be thrown */
+        $this->expectException(InvalidLocalDate::class);
+        $this->expectExceptionMessage('The shifted date falls outside the supported range 0001 to 9999.');
+
+        /** @When adding one month crosses above the maximum year */
+        $date->plusMonths(months: 1);
+    }
+
+    public function testPlusMonthsWhenTargetIsCommonCenturyThenClampsToTwentyEight(): void
+    {
+        /** @Given the last day of January in a common century year */
+        $date = LocalDate::of(year: 1900, month: 1, day: 31);
+
+        /** @When adding one month to reach February of the non-leap century year */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the last day of February */
+        self::assertSame('1900-02-28', $shifted->toIso8601());
+    }
+
+    public function testPlusMonthsWhenTargetIsFourHundredYearLeapThenClampsToLeapDay(): void
+    {
+        /** @Given the last day of January in a year divisible by four hundred */
+        $date = LocalDate::of(year: 2000, month: 1, day: 31);
+
+        /** @When adding one month to reach February of the leap century year */
+        $shifted = $date->plusMonths(months: 1);
+
+        /** @Then the day is clamped to the leap day */
+        self::assertSame('2000-02-29', $shifted->toIso8601());
+    }
+
     public function testInstantToLocalDateWhenJustPastMidnightUtcInWestZoneThenPreviousDate(): void
     {
         /** @Given an Instant at 00:30 UTC on 2026-02-18 */
diff --git a/tests/Unit/PeriodTest.php b/tests/Unit/PeriodTest.php
index 05c84c6..51145a9 100644
--- a/tests/Unit/PeriodTest.php
+++ b/tests/Unit/PeriodTest.php
@@ -6,8 +6,8 @@
 
 use PHPUnit\Framework\TestCase;
 use TinyBlocks\Time\Duration;
-use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\Exceptions\InvalidPeriod;
+use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\Period;
 
 final class PeriodTest extends TestCase
diff --git a/tests/Unit/SystemMonotonicClockTest.php b/tests/Unit/SystemMonotonicClockTest.php
index 70a44a5..28d0acb 100644
--- a/tests/Unit/SystemMonotonicClockTest.php
+++ b/tests/Unit/SystemMonotonicClockTest.php
@@ -51,6 +51,6 @@ public function testNanosecondsWhenMeasuringAcrossSleepThenElapsedIsAtLeastSleep
         $endReading = $clock->nanoseconds();
 
         /** @Then the elapsed delta covers the sleep interval with generous slack */
-        self::assertGreaterThanOrEqual(100_000, $endReading - $startReading);
+        self::assertGreaterThanOrEqual(100_000, ($endReading - $startReading));
     }
 }
diff --git a/tests/Unit/TimeOfDayTest.php b/tests/Unit/TimeOfDayTest.php
index 16a3633..6e5a077 100644
--- a/tests/Unit/TimeOfDayTest.php
+++ b/tests/Unit/TimeOfDayTest.php
@@ -5,8 +5,8 @@
 namespace Test\TinyBlocks\Time\Unit;
 
 use PHPUnit\Framework\TestCase;
-use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\Exceptions\InvalidTimeOfDay;
+use TinyBlocks\Time\Instant;
 use TinyBlocks\Time\TimeOfDay;
 
 final class TimeOfDayTest extends TestCase
diff --git a/tests/Unit/ZonedShiftTest.php b/tests/Unit/ZonedShiftTest.php
new file mode 100644
index 0000000..d9f2eb6
--- /dev/null
+++ b/tests/Unit/ZonedShiftTest.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Test\TinyBlocks\Time\Unit;
+
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use ReflectionMethod;
+use TinyBlocks\Time\Internal\ZonedShift;
+
+final class ZonedShiftTest extends TestCase
+{
+    public function testConstructorWhenInvokedViaReflectionThenInstanceIsCreated(): void
+    {
+        /** @Given an instance allocated without invoking the private constructor */
+        $instance = new ReflectionClass(ZonedShift::class)->newInstanceWithoutConstructor();
+
+        /** @When the private constructor of the static-only collaborator is invoked through reflection */
+        new ReflectionMethod(ZonedShift::class, '__construct')->invoke($instance);
+
+        /** @Then the collaborator is instantiated */
+        self::assertInstanceOf(ZonedShift::class, $instance);
+    }
+}