Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Scope: this file tracks the repository and shared assets — tooling, AI skills, build scripts, and Pragmatica Core version bumps. Each book now versions independently with its own reader-facing changelog: book/CHANGELOG.md (JBCT) and book-pfd/CHANGELOG.md (PFD). See BOOK-VERSIONING.md. Pre-existing entries below that describe book content are kept as history.

[Unreleased]

Added

• The JBCT worksheet has a web edition (website/build.js) — book/appendix-d-worksheet.md renders at /java/jbct/worksheet/ and is linked from the JBCT course footer, mirroring the PFD and Architecture Synthesis worksheet routes. The slug is registered as a non-lesson so it does not enter the course spine. Site goes from 85 to 86 pages.
• The articles are published on the site, and the canonical URLs finally resolve (website/build.js, website/content/articles.md, articles/) — twelve cross-posted articles now render at /articles/<slug>/ behind an index at /articles/, taking the site from 72 to 85 pages. This closes a defect that had been live for months and was invisible to every check: ten published articles carried a canonical_url pointing at a page that did not exist, and one canonicalised to the site’s homepage — returning 200, so nothing ever flagged it, while telling search engines that article was the front page. PUBLISHING_SCHEDULE.md tracks twelve articles; dev.to has thirty published, which is why eight of the broken ones were invisible. Page text is the retrieved published version rather than the local draft, since the two had drifted; a 301 carries article #1’s prefix-less legacy canonical to its new home.
• Two more book-owned sync blocks (ai-tools/sync-book-blocks.py) — predicate-naming and recovery-triple, joining zone-verbs. Both were written into the book first and pulled into the skill by the sync, rather than hand-copied, because every drift incident this repo has had traced to a hand copy.
• The recovery triple reaches the tooling (ai-tools/skills/jbct/SKILL.md, agents/jbct-coder.md, agents/jbct-reviewer.md) — the book has carried ## The Recovery Triple: BER, FER, Design-Out with the instruction “name the triple for each step that changes state”, and ai-tools/ contained zero occurrences of it: not BER, FER, design-out, or compensate. .recover( appeared only as an API example. An agent writing JBCT code had no prompt to state a guarantee for a dropped failure, and the reviewer had no rule to catch its absence. The reviewer gains ### Recovery Checks (return-kind violation, absorption without justification, untested absorbed path); the coder gains a self-validation item shaped like the inverse-pair rule — a stated justification is a complete answer; silence is not — with a guard against inventing retries or outboxes to avoid writing the sentence.
• A fifth corpus sheet: the Shopify pod-era derivation (website/next-step/corpus/shopify.toml) — transcribed from the pre-registered blind run whose every prediction graded HIT. It turns sharded from a unit-tested rule into a reproduced derivation: BLIND-DERIVATION-SO.md:73 names Shopify as “the sharded value the other runs never touched”, and this is now the corpus entry for it. The sheet reproduces the recorded vector on every axis and carries three refusals no other sheet can exercise — 1000+ developers pressing nothing on topology (F21 at the top of its range, against Discord’s four engineers at the bottom), 11 TB/s of read volume stopping at the replicas rung because the read model has not diverged, and a contention row at a scope that also carries a partition key, which must not shard because more sharding cannot help a conflict inside one tenant. Building it surfaced a book-level scope error, below.
• The sheet’s normal form is enforced, and divergence is computed (website/next-step/) — Card 5’s one-row-per-unit rule was specified in the book and honoured by convention only. diverges and diverges_on are now rejected by the entry gate as UNNORMALIZED: a sheet that asserts a divergence has done the deriving itself, and the engine was reading a conclusion and calling it a demand. Divergence is computed instead — q7 by comparing each unit’s cadence against the system-scoped baseline, q9 by comparing typed attributes against it, with two storage shapes on one unit pressing polyglot and a unit differing on two or more attributes pressing per-component. All four corpus sheets reproduce their recorded derivations with the assertions deleted, which is the evidence the divergence was always computable from what they already stated. Comparing typed fields also retires the exact-match vocabulary that could not distinguish Companies House’s “shape” from profile 3’s “data shape” — a distinction that had already caused one misclassification. New: silence is no longer reported as absence, so a sheet where no unit states a cadence reports divergence as unknowable.
• Press rules for sharded and streaming, each two-condition and each with its refusals tested: sharded needs write volume past one node and a natural partition key (volume without a key is a capacity problem, not an axis move; a partition key never rescues a contention row, which “buys hardware and keeps the melt”); streaming needs the volume that earns a partitioned log and a replay-from-position need, at data-class scope. Coverage moves from 7 of 11 pressable ledger values to 9 of 11.
• verify — the exit gate, Card 6’s five arithmetic rules (website/next-step/verify.js) — latency decomposition down the critical path (sequential adds, parallel costs its max), tail composition in series and under fan-out, envelope composition by correlation, availability multiplication with an earned-independence check, and the mechanism bill against Q8’s operator count. 25 tests. The refusals are the load-bearing part and are pinned: a floor the sheet did not supply is UNVERIFIED, never a default; parallel availability arithmetic is refused outright when deploys, certs, regions or config are shared, and no number is produced; a sheet carrying no verification inputs reports not attempted rather than reading as passing. Wired as step 5 of derive.
• next_step entry gate and the mechanical half of the derivation, as a browser playground (website/next-step/, served at /method/architecture-synthesis/next-step/) — the book’s mechanizability claim shipped as software. Dependency-free ES modules parse the answer-sheet TOML subset and run: the entry gate’s five disciplines (priced · scoped · decomposed · triaged · surfaced), the null vector, pruning by explicit mandate strike, pressing each axis against the ledger’s provides / via / costs entries, resolving the pressed vector at the scope the pressure was recorded at, and recovery per effectful operation derived from domain-shape facts (design-out checked first, then inverse, then decay). 83 tests, including tests that pin the refusals — a recovery tie is emitted as a judgment point and never decided, no axis moves without a ledger entry justifying it, and prune never infers a strike from prose. Runs entirely client-side.
• Counterexample issue templates for PFD and JBCT (.github/ISSUE_TEMPLATE/) — the counterexamples page invited reports against all three methods while only Architecture Synthesis had a channel. A PFD report argues about a decomposition and its change drivers; a JBCT report about a rule that makes code worse. Neither has a registered-prediction corpus, so the page says reports there are read and answered rather than graded.
• ai-tools/sync-book-blocks.py — makes the books the source for enumerable rules the tooling duplicates (import ordering, member ordering, zone verb vocabulary, test naming). Each block names a book section by heading; the script extracts it into the destination between <!-- book:<id> --> markers, so those regions are build output rather than hand-copies. --check fails CI when a destination is stale (exit 1) or when a book heading was renamed or markers went missing (exit 2) — a renamed heading fails loudly instead of quietly leaving a stale copy.
• ai-tools/check-drift.sh — drift guard for the AI tooling, wired into CI as .github/workflows/checks.yml. Skills are installed away from this repo (~/.claude/skills), so a stale reference here becomes an invisible wrong answer there. Checks: references to retired documents, links that do not resolve, links that escape their skill directory (these cannot survive installation — book citations must be pragmatica.dev URLs), Pragmatica Core pins that disagree with the declared canonical version, book version headers that disagree with the book’s own CHANGELOG.md, and divergence between this repo and an installed copy. The install-drift check skips automatically where no ~/.claude exists, so CI runs the rest.
• Orphan detection in the site build — verifyLinks() checked that links resolve, not that pages are reachable, so a page nothing linked to passed silently. It now fails the build, with an explicit allowlist for legacy root pages kept only so previously-published URLs do not 404.

Changed

• The lint-rule counts are removed rather than corrected (ai-tools/skills/jbct/SKILL.md, ai-tools/skills/aether-coder/SKILL.md, ai-tools/agents/jbct-reviewer.md) — the jbct skill claimed 37 rules, aether-coder claimed 41, and the CLI ships 69 rule classes. A count in a derived artifact tracking another repository’s source rots by construction, so the number is gone from all three rather than updated to a value that would be wrong again at the next release. The jbct skill now names the rule-ID families instead (JBCT-RET-*, JBCT-VO-*, JBCT-EX-*, JBCT-NAM-*, JBCT-LAM-*, JBCT-STY-*, JBCT-LOG-*, JBCT-MIX-*), which are stable and are what every finding is reported under. The CLI has no rule-listing subcommand to point readers at.
• Q5 attaches at two scopes (rules.js) — load was accepted per path only, while sharded reads write volume past one node’s ceiling and streaming reads the one data class whose volume earns a partitioned log, both per data class. A sheet built to the stated rule could not express the fact those values turn on, which is how the Shopify sheet found it. data-class is now an accepted Q5 scope, and the book was corrected to match (AS 1.1.2).
• separated follows the rule the derivations actually apply — read-model divergence plus volume, with staleness as a cost rather than a third condition. The book, the working ledger and the two graded blind runs carried three incompatible statements of this rule while the engine implemented a fourth (divergence alone). LEDGER.md, axes-and-ledger.md:45, Card 2b and ledger.js now agree, and the engine gained the volume condition it lacked plus a cost check that refuses the move where the path is contracted strict.
• The two values no derivation has ever forced are labelled as such. unified runtime and serverless move from “needs a rule” to UNFORCED: no corpus run, worked example or blind derivation has produced their forcing pressure, so a rule would not implement the method but invent a demand and then obey it. That is a different gap from a missing rule, and the coverage test now records which kind it is.
• read_shape renamed to read_model across the engine, the four corpus sheets and the spec — Architecture Synthesis 1.1.0 named the fact read-model divergence and began eliciting it in Card 1’s second row, so the field now spells what the book asks for. The old name predated the book having a word for it, and collided with Card 3’s demand shapes — the collision the book fix removed. Reverting a single field name breaks four golden assertions, so the wiring is load-bearing rather than decorative.
• press.js’s header no longer claims read-model divergence is unelicited — Card 1 asks for it as of AS 1.1.0. This is the third stale “does not exist yet” comment found this cycle, after the ledger claim in these notes and derive.js’s blocked-press header; each outlived the thing it said was missing. The header now records what the engine genuinely still does not do: diverges is an assertion the sheet makes, not a comparison computed across per-unit rows, so Card 5’s one-row-per-unit normal form is specified in the book and unenforced in software.

Known gaps

• Press coverage is 7 of the ledger’s 11 pressable values (website/next-step/coverage.test.js). Unreached: unified runtime, serverless, streaming, sharded — each needs a press rule and a sheet field to carry the fact the rule would read (coupling and topology uncertainty, duty cycle, per-data-class volume, a natural partition key). The test fails if a ledger value gains a pressedBy and nobody decides whether a rule reaches it, so the gap cannot widen silently.
• separated is under-implemented. book-arch-meta/LEDGER.md:121 requires three conditions together — a read path with its own tight SLO and its own scale shape and tolerable staleness. The rule reads shape divergence alone; it reproduced two corpus runs on the strength of those sheets rather than of the rule.
• Card 2 does not print the ledger. axes-and-ledger.md:39 forward-references the per-value provides / mechanism / costs entries to the reference cards, and Card 2 carries only axes and values. The content exists — book-arch-meta/LEDGER.md v0.2, which ledger.js is transcribed from — so this is a publishing gap, not authorial work.
• Member ordering and import ordering (skills/jbct/project-structure/organization.md) — JBCT-ORD-01 and the import-order rule were in the book (book/project-structure.md) but had never reached the skill. Now generated from it.
• Zone verb vocabulary (skills/jbct/SKILL.md) — the skill pointed at the book for the full tables and carried a divergent verb list of its own; the tables are now generated from book/basic-patterns.md.

Fixed

• The book contradicted itself on test naming — book/basic-patterns.md still taught the retired three-segment methodName_outcome_condition while systematic-application.md and chapter-summaries.md taught the 4.3.1 method_[scenario_]expectation. The 4.3.1 change had missed this section, which is where the skill’s copy of the old rule came from.
• Bidirectional tooling drift — the installed copies of jbct-coder, jbct-reviewer and code-reviewer had accumulated content that was never backported (the *State naming rule, the @NullReturn intent annotation, the Verify.Is/built-in-VO catalog rules, the mirrored-API sibling-diff review pass, and code-reviewer’s rescoping to non-JBCT code), while the repo copies were ahead on the pattern-origin framing. Both directions reconciled against the book.
• BPMN framing — jbct-coder and jbct-reviewer claimed the six patterns “map to” BPMN constructs. The book is explicit that the correspondence is “corroboration, not foundation — the catalog is derived from the process, not from the notation” (book/basic-patterns.md:18). Patterns now lead from the process side, with BPMN retained as a dictionary.
• Test-naming rule — skill still carried the pre-4.3.1 three-segment form; relaxed to method_[scenario_]expectation (two or more segments) per JBCT-NAM-05.
• Dead book references — CODING_GUIDE.md (retired 2026-06-22) and the non-existent book/ch09-thread-safety.md / book/ch07-basic-patterns.md paths replaced with published web-edition URLs.
• Stale book version headers — book/introduction.md and book/from-process-to-patterns.md announced JBCT v4.3.0 against a 4.3.1 changelog.

[3.1.0] - 2026-06-13

Added

• Chapter 9b: Knowledge-Gathering Pipelines — new chapter developing the knowledge-gathering view (Ch. 2) to implementation depth. Realizes the methodology’s growing context: stage records carry the previous stage as a type parameter, so the composed type is a compiler-checked proof of pipeline progress; the Pragmatica Core 1.0.0-rc1 mapWith / flatMapWith / ensureWith combinator family collapses each stage to one lambda-free line. Includes the gating-vs-evidence rule: ensureWith is where parse-don’t-validate runs out (transient outcomes only), while a load-bearing check must return evidence and accrete it. Wired into both build scripts and the TOC.
• Instrumentation completeness (Ch. 9) — new subsection in Pattern: Aspects (Decorators): because effects live only at leaves, wrapping every leaf (and every injected dependency) instruments the whole request path by construction, with the business body naming none of it. Reframes the existing logging-at-leaves rule as a completeness guarantee, adds the structural error-telemetry and cross-module-seam points, and a matching key-takeaway.

Changed

• Chapter 2 reshaped into a design→code bridge — Design Methodology slimmed to From Process to Patterns: keeps the knowledge-gathering view and the data-dependency-graph → pattern → Pragmatica-code mapping (which the pattern chapters and Ch. 9b depend on, and which the implementation-agnostic Process-First Design book does not carry), and defers the full design treatment (process-first design, worked design example, data-follows-process, design by elimination, composition at scale, BPMN, ubiquitous language) to the companion Process-First Design book. Wired the chapter into both build scripts for the first time — it had been authored at 3.0.0 but omitted from the build.
• Factory-naming rationale (Ch. 5) — made explicit that type-named factories (lowercase-first, e.g. email, money) allow static imports without collision, which is the reason shared names like of/create/valueOf are rejected.

Fixed

• Emoji rendering in comparison tables — the ✅/❌/⚠ marks in the Ch. 3 (return-types) and Ch. 6 (error-handling) comparison tables are emoji codepoints absent from DejaVu, so xelatex rendered them as blank boxes. Added a monochrome Noto Emoji fallback (mapped via active-character definitions in metadata.yaml, stray variation-selectors stripped) so they render; the font dependency is checked in build-pdf.sh.
• Chapter numbering reconciled with the table of contents — the 3.0.0 design-methodology insertion (as Chapter 2) had renumbered only the front chapters’ titles, leaving everything from Pragmatica Core Essentials onward one number behind the TOC (two chapters were both titled “Chapter 3”, and the built book skipped from Chapter 1 to Chapter 3 because ch02-design-methodology was missing from both build scripts). Added that chapter to the build, and reconciled every body title and cross-reference to the canonical TOC numbering (1–20, with 9b and 15a/15b as lettered sub-chapters). Removed the unused, stale book/manuscript/ mirror.
• Factory-naming consistency in examples — appendix-b TransferFunds exercises now use the canonical factories Money.money(...) and TransferFunds.transferFunds(...) (were Money.of / TransferFunds.create); ch11 timeout test uses UseCase.useCase(...) (was UseCase.create).

[3.0.0] - 2026-04-12

Added

• Design Methodology section in CODING_GUIDE.md — process-first design, use case identification, data follows process, design by elimination, composition at scale, BPMN as shared language, ubiquitous language, references to emerging direction
• Series Part 0: Design Methodology — tutorial with worked e-commerce checkout example
• Book Chapter 2: Design Methodology — full treatment with context-specific entities, worked examples, further reading
• Promise.await() forbidden in business logic — zero-tolerance rule; @TerminalOperation for legitimate cases
• Abandoned Result/Promise values — zero-tolerance rule; expression-based code enforcement
• @Contract and @TerminalOperation annotations — replace @SuppressWarnings for exemptions

Changed

• Major version bump to 3.0.0 for new design methodology
• Book renumbered: new Chapter 2 shifts all subsequent chapters by one (20 chapters + 3 appendices)
• ndx section added to CLAUDE.md

[2.3.1] - 2026-04-11

Added

• Promise.await() forbidden in business logic — new zero-tolerance rule; use @TerminalOperation for legitimate cases (CLI, fire-and-forget)
• Abandoned Result/Promise values — new zero-tolerance rule; every value must be returned or handled
• @Contract and @TerminalOperation annotations — dedicated annotations replace @SuppressWarnings for void return and await exemptions
• ndx section in CLAUDE.md for recall palace quick reference

Changed

[2.3.0] - 2026-04-06

Added

• Aether Coder skill — full slice development skill covering patterns, resources, deployment, and testing
• Promise.allOrCancel() documentation — static and instance variants (1-15 params), cancels remaining on first failure
• Promise.allOfOrCancel() documentation — collection variant with cancellation
• Promise.any() documentation — first success wins

Changed

• Updated Pragmatica Core version from 0.25.0 to 1.0.0-rc1 across all documentation, AI tools, examples, and training
• Updated JBCT version from 2.2.0 to 2.3.0 in book metadata
• Corrected Promise.all() arity documentation from 1-9 to 1-15
• Documented instance all()/allOrCancel() for-comprehension style variants
• Fixed instance all() description to reflect parallel execution (was sequential, now fixed in core)

[2.2.0] - 2026-03-27

Changed

• Renamed “Pragmatica Lite” to “Pragmatica Core” across all documentation, book, series, articles, and tools
• Updated Pragmatica Core version from 0.11.2 to 0.25.0
• Updated GitHub URLs from siy/pragmatica-lite to pragmaticalabs/pragmatica
• Stripped CLAUDE.md to essentials — Java formatting and API reference delegated to jbct skill/agent
• Synced project-local AI tools (jbct-coder, jbct-reviewer, jbct skill) from authoritative system versions
• Added proactive SKILL.md loading to jbct-coder and jbct-reviewer agents
• Added spec/plan backreference verification step to jbct-coder self-validation
• Replaced abstract version numbers with last-modified timestamps in AI tool headers

[2.1.6] - 2026-03-25

Added

• Documented when void return type is the right choice: API conformance and fire-and-forget side effects
• Added library value objects section to book chapters (ch03, ch04) and series (part-03)
• Added Verify.Is::present to API reference listings (combined not-null + not-blank for CharSequence)

Changed

• Redesigned front page quick-start with ecommerce CreateUserRequest example showing Result.all() composition
• Migrated string validation from Verify.Is::notNull to Verify.Is::present across all docs, examples, and AI tools
• Clarified Void type parameter (forbidden) vs void return type (fire-and-forget) across guide, series, book, and AI tools
• Fixed JBCT method chain dot alignment in all code examples
• Mentioned Pragmatica Core library value objects (Email, Url, Uuid, NonBlankString, IsoDateTime)
• Updated website styles

[2.1.5] - 2026-02-07

Changed

• Version bump for next development cycle

[2.1.4] - 2026-02-01

Changed

• Version bump for next development cycle

[2.1.3] - 2026-01-19

Added

• RFC-0008: Aspect Framework - Compile-time aspect framework for cross-cutting concerns
  • Core interfaces: AspectConfig, AspectFactory, Cache<K,V>
  • Annotations: @Aspect(CACHE, LOG, METRICS, RETRY, TIMEOUT), @Key
  • Hierarchical TOML config: [slice.method.section] → [slice.section] → [default.section]
  • Aspects.with*() composition utilities
  • Key extraction from request records

Changed

• Pragmatica Core updated from 0.9.10 to 0.25.0
  • Updated all documentation, examples, and dependency references
• RFC-0002: Dependency Protocol - Improved proxy design
  • Replaced direct invoker.invoke() with pre-built MethodHandle pattern
  • Added MethodHandle<R, T> interface with invoke(), fireAndForget()
  • methodHandle() returns Result - parsing failures caught at factory time
  • Updated all proxy examples to use handle-based design

[2.1.2] - 2026-01-13

Added

• jbct-designer Agent - new AI agent for JBCT-based architecture design
  • Use before implementation to validate architecture and select patterns
  • 8-step design methodology with gap detection
  • Discovery questions by pattern
  • Output format for implementation-ready designs
  • Workflow: jbct-designer → jbct-coder → jbct-reviewer
• Common Language: Developer-Business Vocabulary - patterns as shared language
  • CODING_GUIDE.md: New section in Foundational Concepts
  • series/part-01-foundations.md: Added paragraph with translation examples
  • book/ch01-introduction.md: Added paragraph
  • Key insight: “First we verify, then we process, then we notify” = Sequencer
• Gap Detection Through Patterns - systematic requirement discovery
  • CODING_GUIDE.md: New section in Patterns Reference
  • series/part-05-basic-patterns.md: New section with discovery questions
  • series/part-06-advanced-patterns.md: Discovery questions for advanced patterns
  • book/ch07-basic-patterns.md: New section
  • book/ch08-advanced-patterns.md: New section
  • jbct-reviewer.md: Step 7 added to Review Methodology
• Discovery Questions by Pattern - questions each pattern generates
  • Per-pattern tables: Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects
  • Gap signal → Question to raise mapping
  • Added to CODING_GUIDE.md, series, book, and jbct-reviewer
• The Six Patterns That Cover Everything - follow-up article
  • Articles: articles/six-patterns-that-cover-everything.md
  • Common language concept, gap detection, right questions
  • Before/after example showing precision gain
• Request Processing as Data Transformation - foundational concept
  • Articles: articles/underlying-process.md (full article)
  • Articles: articles/linkedin-data-transformation.md (LinkedIn post)
  • CODING_GUIDE.md: New section in Foundational Concepts
  • Book: ch01-introduction.md expanded with new section
  • Key insight: sync/async and parallel/sequential are execution details, not structural concerns
  • JBCT patterns as universal primitives for data flow

Changed

• jbct-coder.md - Added Related Agents section with workflow context
• jbct-reviewer.md - Added Related Agents section, gap detection step, output format section

[2.1.1] - 2026-01-08

Added

• Parallel JBCT Review System
  • /jbct-review skill for thorough parallel code review
  • 10 focused review areas for comprehensive coverage
  • Severity-based consolidation of findings
  • Support for path and focus arguments
• fold() Alternatives guidance across documentation
  • jbct-coder.md: Decision guide and patterns
  • jbct-reviewer.md: Detection of fold() abuse in Quick Reference
  • skills/jbct/patterns/fold-alternatives.md: Full reference with examples
• Comprehensive Tooling Documentation
  • AI-TOOLING.md: Claude Code skills, agents, and commands
  • CLI-TOOLING.md: jbct CLI with all 37 lint rules
  • MAVEN-PLUGIN.md: Build integration and CI setup
  • Website navigation updated with Tools section

Changed

• jbct-reviewer.md enhanced with parallel review support
  • Focus parameter for narrow, thorough reviews
  • 10 focus areas with specific violation patterns
  • Improved Quick Reference with fold(), Void detection
• Pragmatica Core updated from 0.9.9 to 0.9.10
• jbct-cli referenced version updated to 0.4.6

[2.1.0] - 2026-01-06

Added

• Logging Philosophy section across documentation
  • CODING_GUIDE.md: Full section in Patterns Reference (Aspects)
  • book/ch08-advanced-patterns.md: Subsection with rationale and examples
  • skills/jbct/patterns/aspects.md: Condensed reference with anti-patterns
  • Principle: logging only at leaves and external boundaries
  • Implementation via aspects wrapping leaf implementations
  • Practical considerations: sensitive data sanitization, correlation propagation, high-volume operations
  • “Value highway” testing approach for composition verification

[2.0.11] - 2026-01-02

Changed

• Pragmatica Core updated from 0.9.3 to 0.9.4
  • TCP Server optimizations (TCP_NODELAY, PooledByteBufAllocator)
  • Consensus Netty network layer
  • Core API unchanged - version bump only

[2.0.10] - 2026-01-01

Changed

• Pragmatica Core updated from 0.9.0 to 0.9.3
  • 0.9.1: Dependency updates, deprecation warning fixes
  • 0.9.2: KSUID (replaces ULID), JOOQ integration module
  • 0.9.3: Consensus module (CFT protocol)
  • Core API unchanged - version bump only
• Fixed deprecated Verify.ensure() syntax across documentation
  • Old: Verify.ensure(CAUSE, value, predicate) (deprecated, forRemoval)
  • New: Verify.ensure(value, predicate, CAUSE) (cause-at-end)
  • Updated: articles/value-objects-cookbook.md, articles/parse-dont-validate.md, CODING_GUIDE.md, README.md
• jbct-cli 0.4.3 improvements (parser and formatter fixes)
  • Farthest failure tracking for better error positions
  • Multiple formatter alignment fixes
  • JBCT-SEAL-01 and JBCT-PAT-02 false positive fixes

[2.0.9] - 2025-12-27

Changed

• JBCT CLI lint rules count updated from 33 to 36

[2.0.8] - 2025-12-26

Changed

• Pragmatica Core updated from 0.8.6 to 0.9.0
  • New: Verify.ensureOption() for elegant Result<Option<T>> validation pattern
  • New: TOML Parser (not documented in JBCT guides)
• Documentation updates for Verify.ensureOption() pattern
  • CLAUDE.md API reference section
  • CODING_GUIDE.md ReferralCode example
  • jbct-coder.md and jbct-reviewer.md agent configurations
  • Series files: parts 2, 3, 4, 9 with ensureOption examples
  • Book chapters: ch02, ch04, ch05, ch12 with ensureOption pattern
• Series part count updated from 9 to 10 across all series files

[2.0.7] - 2025-12-24

Changed

• Pragmatica Core updated from 0.8.5 to 0.8.6
  • New: Result.sequence() for collecting results from iterables
  • New: .getOrThrow() for Result and Option
  • New: Instance all() for Option and Promise (was Result-only)
• CLI lint rules count updated from 23 to 33

[2.0.6] - 2025-12-22

Added

• Monetization links - Book and GitHub Sponsors links in site navigation and footer
• Services page - Consulting offerings with pricing (CONTACT.md → “Work With Us”)
• File structure guidelines - Standardized internal structure for JBCT source files
  • Import ordering convention (java → javax → pragmatica → third-party → project → static)
  • Member ordering by file type (use case, value object, error interface, step implementation, utility interface)
  • Utility interface pattern with sealed + unused record
  • Added to CODING_GUIDE.md, series/part-09, book/ch15, jbct-coder.md, jbct-reviewer.md
• Article series for JBCT promotion - 5-part series for Medium/Dev.to publication

Changed

• CLI lint rules count updated from 23 to 33
• Repository cleanup and build artifact management
• Medium compatibility - Replaced tables with lists in article series for better rendering
• Pragmatica Core updated from 0.8.4 to 0.8.5 in all documentation and examples
  • Breaking: Verify.ensureFn() removed - use .filter(cause, predicate) instead
  • New: RateLimiter with Token Bucket algorithm
  • New: Result.tryOf() aliases, Result.onOk()/onErr()/run() aliases
  • New: Instance all() methods for for-comprehension style
  • Migrated 108 ensureFn occurrences across 35 files to filter pattern

[2.0.5] - 2025-12-18

Added

• Broader movement acknowledgment - Added note in Chapter 1 that JBCT is part of a wider industry trend toward compile-time guarantees and type-driven design

Removed

• Appendix D (Quick Reference Cards) - Removed from book due to EPUB rendering issues

[2.0.4] - 2025-12-14

Added

• Tools section in README.md - Reorganized documentation structure
  • “AI Tools” subsection for Claude Code skill and subagents
  • “CLI Tools” subsection for jbct-cli and Maven plugin
• JBCT CLI integration - AI tools now aware of jbct-cli
  • jbct-coder.md: Suggests running jbct check after code generation
  • jbct-reviewer.md: Recommends jbct check before manual review
  • skills/jbct/SKILL.md: References CLI tool for automated checking
  • All tools suggest installation when CLI not found
• Tooling section in CODING_GUIDE.md - Brief overview pointing to README
• jbct-reviewer.md added to website build
• “Why Result” philosophy section - Error handling mechanism comparison
  • Added to CODING_GUIDE.md, series/part-02-four-return-types.md, book/ch02 and ch05
  • Comparison table: checked/unchecked exceptions, Go-style, functional Result
  • Explains transparency, ergonomics, reliability trade-offs
• “Promise as Async Result” note - Clarifies Promise/Result relationship
  • Added to CODING_GUIDE.md, series/part-02, book/ch02
  • Emphasizes symmetry and conversion patterns

[2.0.3] - 2025-12-14

Added

• Static imports section - Encouraged use of static imports for factory methods and Pragmatica Core APIs
  • Added to jbct-coder.md, jbct-reviewer.md, CODING_GUIDE.md, skills/jbct/SKILL.md
  • Reduces code verbosity while maintaining readability
• Fluent failure creation - Explicit preference for cause.result() over Result.failure(cause)
  • Added anti-pattern documentation with examples
  • Updated all code examples to use fluent style
• Book content - Complete JBCT book with 19 chapters and 4 appendices
• CI workflow - GitHub Actions workflow to build book PDF
• Book feedback fixes - Comprehensive improvements based on Java 25 reviewer feedback
  • JBCT abbreviation decoded on first use (“Java Backend Coding Technology”)
  • Prerequisites updated: Mid-/senior Java developers, Java 21+, FP basics
  • “Pragmatic, Not Pure” section clarifying JBCT’s non-academic FP approach
  • Return Type Matrix with allowed/discouraged/forbidden nesting rules
  • Validation placement guidelines (value object vs ValidRequest vs use case)
  • Programming errors vs business errors clarification
  • Null policy consolidation statement
  • Fork-Join infrastructure-level dependency warnings (DB locks, rate limits)
  • Aspects operational semantics (timeout, retry, composition order)
  • Test speed classification (fast/slow integration tests)
  • Async Promise testing patterns with timeouts
  • Interoperability section: Optional→Option, CompletableFuture→Promise, exceptions→Cause

Changed

• Pragmatica Core updated from 0.8.3 to 0.8.4 in all documentation and examples
  • New in 0.8.4: Extended all()/Fn/Tuple support from 9 to 15 parameters
  • New integration modules: HTTP Client, JDBC, R2DBC, JOOQ R2DBC
• jbct-coder.md and jbct-reviewer.md synchronized with system agent definitions
• ch01-introduction.md: Prerequisites, JBCT decode, “Pragmatic Not Pure” section
• ch02-four-return-types.md: Return Type Matrix (allowed/discouraged/forbidden)
• ch04-parse-dont-validate.md: Validation placement guidelines
• ch05-error-handling.md: Programming vs business errors clarification
• ch06-null-policy-recovery.md: Consolidated null policy statement
• ch08-advanced-patterns.md: Fork-Join infra warnings, Aspects operational semantics
• ch11-testing-practice.md: Test speed classification, async testing patterns
• ch17-migration-strategies.md: Interoperability section (Optional, CF, exceptions)

[2.0.2] - 2025-12-06

Added

• Part 10: Systematic Application Guide - New series part with checkpoints for coding and review
  • 8 checkpoints covering lambdas, return types, factories, class design, chains, logging, review, and implementation patterns
  • Quick reference violation → fix tables
  • Application order for new code and reviews
  • Nested record vs lambda pattern decision tree
  • Conditional Option composition patterns
  • Validation ownership rules

Changed

• Series expanded from 9 to 10 parts with systematic application guide
• jbct-coder.md v2.0.2
  • Added Thread Safety and Immutability section with Fork-Join safety rules
  • Added grouped error enum pattern (enum General for fixed-message errors)
  • Added exception mapping with constructor references pattern
  • Updated Causes.forValue() to Causes.forOneValue() (deprecated name fix)
  • Updated .match() to .fold() in controller example (correct API)
  • Added Part 10 to references
• jbct-reviewer.md v2.0.2
  • Added Thread Safety and Immutability section with Fork-Join checks
  • Added Zone-Based Abstraction Check section with Derrick Brandt attribution
  • Added direct constructor invocation check (bypassing factory methods)
  • Added Verify.Is/parse utilities usage checks
  • Updated Causes.forValue() to Causes.forOneValue() (deprecated name fix)
  • Enhanced review methodology with zone-based abstraction verification
• Updated series INDEX.md to reflect 10-part structure
• Synced subagents with hivemq-assignment project updates
• Copied updated subagents to system location (~/.claude/agents/)

[2.0.1] - 2025-11-17

Fixed

• Causes API consistency: Replaced deprecated Causes.forValue() with Causes.forOneValue() across all documentation
• Template syntax: Changed {} placeholders to %s (String.format syntax) in all Causes factory examples
• CLAUDE.md API Reference: Added comprehensive Causes utilities documentation with correct template syntax
• ValidOrder examples: Extracted calculateTotal() method to follow Single Level of Abstraction principle
• Error type references: Renamed UserLoginError to LoginError to match actual interface definitions
• UserError interface: Added EmailExists enum constant with consistent naming (EMAIL_EXISTS)

[2.0.0] - 2025-11-13

Major release: Thread Safety, Concurrency, and Series v2.0.0 (100% Parity)

Added

• Foundational Concepts: Immutability and Thread Confinement

  • Comprehensive section explaining thread safety model
  • Clear distinction between what MUST be immutable vs what CAN be mutable
  • Thread confinement as key safety mechanism
  • Safe local mutable state example with detailed explanation

• Promise Resolution and Thread Safety

  • Documents exactly-once resolution guarantee
  • Explains synchronization point semantics
  • Shows thread-safe resolution with multiple racing threads
  • Details transformation execution order and side effect independence

• Fork-Join: Independence and Thread Safety unified section

  • Rewrote to show independence and thread safety as two views of same requirement
  • Added thread safety violation examples (shared mutable state, data races)
  • Enhanced anti-patterns with mutation examples
  • Pattern-specific safety rules inline

• Thread Safety Quick Reference table (before Testing Strategy)

  • Comprehensive table for all patterns (Leaf, Sequencer, Fork-Join, Iteration, Condition)
  • Columns: Thread Safety Model, Local Mutable State, Input Data, Result Data
  • Key principles and common mistakes sections
  • Quick lookup for developers

• Thread Safety notes for each pattern

  • Leaf: Thread-safe through confinement
  • Sequencer: Safe through sequential execution
  • Iteration: Sequential safe with accumulators, parallel needs immutability
  • Each pattern section now includes thread safety subsection

• Testing: Mutable test state is acceptable

  • Explains why mutable test state is safe (single-threaded execution)
  • Example with call log accumulator
  • Clarifies this doesn’t violate production immutability rules

• Series v2.0.0: 100% Parity with CODING_GUIDE.md v2.0.0 (+1,439 lines across all parts)

  • Part 1: Quick Reference (+193 lines)
    • Pattern decision tree for selecting correct return type
    • Four Return Kinds reference table
    • Type transformations cheat sheet (Option→Result→Promise)
    • Naming conventions summary (factory methods, validated inputs, zone-based verbs)
    • Positioned after “Setting Up” for immediate use
  • Part 2: Null Policy (+237 lines)
    • When null IS acceptable (adapter boundaries only)
    • When null is NOT acceptable (business logic, parameters, returns)
    • Option.option(nullable) wrapping pattern
    • Complete examples with repositories and DTOs
  • Part 2: Error Recovery Patterns (+172 lines)
    • .or(), .orElse(), .recover() for fallback values
    • Graceful degradation strategies
    • Default values and safe mode examples
    • Multi-level fallback chains
  • Part 2: Expanded Monadic Composition Rules (+75 lines)
    • Lambda composition guidelines (what belongs inside/outside)
    • Forbidden patterns (direct field access, nested lambdas)
    • Single pattern per function enforcement
    • Common violations with corrections
  • Part 2: Pragmatica Core API Reference (+214 lines)
    • Complete type conversions table
    • Factories (creating instances)
    • Exception handling (lift methods)
    • Validation utilities (Verify.Is predicates)
    • Parse subpackage (JDK wrappers)
    • Aggregation (all/any/allOf)
    • Common methods reference
  • Part 3: Zone-Based Abstraction Framework (+62 lines within Single Level of Abstraction)
    • Three zones: Use Case, Orchestration, Implementation
    • Zone-specific verb vocabulary
    • Attribution to Derrick Brandt with link
    • Clear abstraction level boundaries
  • Part 3: Naming Conventions (+168 lines)
    • Factory method naming rules
    • Validated input naming (Valid prefix)
    • Zone-based verb selection
    • Acronym naming (treat as words: HttpClient not HTTPClient)
    • Test naming patterns
    • Complete examples for each convention
  • Part 4: Thread Safety Quick Reference (+183 lines)
    • Pattern-by-pattern thread safety guarantees
    • Leaf, Sequencer, Fork-Join, Iteration, Condition safety models
    • Common mistakes checklist
    • Independence validation for Fork-Join
    • Mutable state guidelines
  • Part 6: Module Organization (+187 lines)
    • Multi-module project structure
    • When to use modules vs single module
    • Gradle and Maven examples
    • Module dependency management
    • Build configuration best practices

Changed

• Series restructured from 6 to 9 parts for better learning progression
  • Part 2 split into 2A (Four Return Types), 2B (Parse Don’t Validate), 2C (Error Handling)
  • Part 5 split into 5A (Testing Philosophy), 5B (Testing Practice)
  • Each section now focused and digestible (~450-700 lines vs 2000+)
  • Improved navigation with clear prerequisites and next steps
  • All cross-references updated throughout series
• Series INDEX.md: Updated version to 2.0.0 with complete changelog
  • Added all new topics to each part’s topic list
  • Updated version history with comprehensive v2.0.0 details
  • Progressive terminology transition documented
  • Thread safety and 100% parity milestones captured
• All pattern sections enhanced with thread safety information
• Zone-based naming integrated throughout series with Derrick Brandt attribution
• Moved basic testing from Part 5 to Part 2 for earlier verification capability

Fixed

[1.8.2] - 2025-11-09

Enhanced documentation for easier adoption

Added

• README: 30-Second Pitch with before/after code comparison

  • Shows validation hell → parse-don’t-validate transformation
  • Concrete example highlighting immediate benefits
  • Positioned at top of README for maximum impact

• README: Quick Wins section for incremental adoption

  • Three small changes developers can make today (10 minutes each)
  • Win 1: Convert one value object to parse-don’t-validate
  • Win 2: Convert one service method to return Result
  • Win 3: Convert one test to functional assertions
  • Emphasis: “You don’t have to rewrite everything”

• Part 2: Spring to JBCT Translation table

  • Maps familiar Spring patterns to JBCT equivalents
  • Clear guidance on @Service → use case, @Repository → adapter, etc.
  • Example showing traditional vs JBCT Spring controller
  • Reduces barrier for Spring Boot developers

• Part 2: “Why Not Java Standard Library?” comparison

  • Table comparing null, Optional, exceptions, CompletableFuture to JBCT types
  • Shows concrete problems with traditional Java approaches
  • Explains why four types are necessary

• Part 2: Migration strategy for existing codebases

  • Three-phase incremental adoption path
  • Keep existing @Valid annotations, add parsing layer
  • Gradual migration from services to value objects
  • Real-world Spring controller example

• Part 2: Real-world validation examples

  • Cross-field validation (DateRange with end > start)
  • Dependent validation (password must not contain username)
  • Business rule validation (order total matches line items)
  • Error accumulation with Result.all()

• Part 2: “When Exceptions Are Still OK” section

  • Programming errors vs business failures distinction
  • Legitimate exception uses (IllegalArgumentException, framework boundaries)
  • Clear table showing when to use Result vs exceptions

• Part 2: Basic testing moved forward from Part 5

  • Functional assertion pattern (onSuccess/onFailure)
  • Examples for Result, Promise, and Option
  • Test naming convention (methodName_outcome_condition)
  • Allows developers to verify code immediately after learning concepts

• Part 2: Pragmatica Core Quick Reference

  • Common imports and method cheat sheet
  • Frequently used patterns with descriptions
  • Positioned after validation utilities section

• Part 3: “Why This Rule Exists” section for Single Pattern Per Function

  • Shows concrete pain points of mixing patterns
  • Testing brittleness, debugging confusion, code review issues
  • Demonstrates benefits of separation

• Part 1: Evaluation Framework worked example

  • Complete analysis of @Transactional vs explicit transactions
  • Applies all 5 criteria with scoring
  • Shows how every JBCT decision is made objectively

Changed

• Progressive “Smart Wrapper” → “monad” terminology across series

  • Part 1: 90% “Smart Wrapper”, 10% “monad” (gentle introduction)
  • Part 2: 70% “Smart Wrapper”, 30% “monad” (building familiarity)
  • Part 3: 50/50 mix with transition statements
  • Part 4: 70% “monad” (primary term established)
  • Parts 5-6: 80-100% “monad” (correct FP terminology)
  • Eliminates FP phobia while teaching correct terminology

• Part 3: Simplified async iteration example

  • Replaced complex reduce with simple for-loop version
  • Shows reduce as “alternative” with note: “clarity matters more than cleverness”
  • Makes async iteration immediately understandable

• Part 1: Added “Try It Now” exercises

  • After Smart Wrappers introduction
  • Encourages code exploration before moving to Part 2
  • Observation-focused (don’t change yet, just notice patterns)

• Terminology clarifications

  • Part 2: Added note that “Cause” ≠ exception cause (means “FailureReason”)
  • Part 3: Clarified “Leaf” as “(atomic operation with no substeps)”
  • Part 2: First code example shows full imports for API context

• CODING_GUIDE.md: Major comprehensive improvements (+1074 lines)

  • Added complete Foundational Concepts section (~250 lines)
    • Side effects and purity explanation
    • Composition fundamentals
    • Smart Wrappers (Monads) with “Do, If/When Available” mental model
    • Functional vs imperative comparison
    • Pipes and values mental model
  • Added Evaluation Framework worked example
    • Complete @Transactional analysis with 5-criteria scoring
    • Shows objective decision-making process
  • Added Spring to JBCT Translation table
    • Maps @Service, @Repository, @Valid, etc. to JBCT equivalents
    • Before/after Spring controller example
    • Reduces adoption friction for Spring Boot teams
  • Added comprehensive Testing Strategy section (~580 lines)
    • Problem with traditional component-focused testing
    • Integration-first philosophy with criteria justification
    • Three testing layers (value objects, leaves, use cases)
    • Evolutionary testing process (Phase 1-N)
    • Complex input handling (3 solutions: builders, vectors, factories)
    • Managing large test counts (3 strategies: nested classes, parameterized, file organization)
    • When to write unit tests (clear guidelines)
    • Migration guide from traditional unit testing
  • Added Real-World Validation Scenarios (~95 lines)
    • Cross-field validation (DateRange)
    • Dependent validation (password/username)
    • Business rule validation (order totals)
    • Error accumulation with Result.all()
  • Added Incremental Adoption Strategy (~95 lines)
    • 4-phase migration path for existing codebases
    • Keep existing validation while adding JBCT
    • Gradual shift from service layer to value objects
    • Timeline guidance (3-6 months)
  • Added Pragmatica Core Quick Reference (~45 lines)
    • Common imports cheat sheet
    • Frequently used patterns with descriptions
    • Positioned early for immediate reference
  • All examples updated with commented-out private constructors
    • // private Email {} // Not yet supported in Java
    • Team discipline note about package-private limitation
  • Terminology note added to Smart Wrappers section
    • Explains Smart Wrapper ↔ monad equivalence
    • Connects to broader FP ecosystem

Impact: CODING_GUIDE.md evolved from 3076 lines to 4150 lines of comprehensive, reference-quality documentation that bridges theoretical concepts with practical implementation guidance.

[1.8.1] - 2025-11-08

Added

• Syntax highlighting for code blocks on pragmatica.dev website
  • Integrated highlight.js with GitHub light/dark themes
  • Dynamic theme switching synced with site theme toggle
  • Fixes Firefox rendering issue where Java code blocks appeared as unreadable gray boxes
• Cross-references between JBCT skill and subagents
  • Added “When to Use Specialized Subagents” section to skills/jbct/SKILL.md
  • Clear guidance on when to use jbct-coder vs jbct-reviewer vs skill
  • Invocation instructions with Task tool for both subagents
  • Inline tips in workflow and mistakes sections
  • Enhanced External Resources section highlighting subagent capabilities

Changed

• All version references updated from 1.8.0 to 1.8.1
• Pragmatica Core API corrections in CLAUDE.md and jbct-coder.md
  • Added missing factory methods: Option.from(Optional), Result.unitResult(), Promise.unitPromise()
  • Corrected lift methods: removed non-existent Promise.async(Runnable), use Promise.lift(ThrowingRunnable) instead
  • Added missing aggregation: Promise.failAll(), Promise.cancelAll()
  • Added missing callback methods: .apply(), .fold(), .withSuccess(), .withFailure(), .withResult()
  • Added Promise-specific operations: .resolve(), .succeed(), .fail(), .cancel(), .isResolved(), .timeout(), .mapResult(), .replaceResult(), .trace()
  • Added query and unsafe operations: .isPresent(), .isEmpty(), .isSuccess(), .isFailure(), .unwrap(), .expect(), .stream(), .toOptional()
• JBCT Learning Series consistency fixes (30 improvements across 6 parts)
  • Fixed navigation metadata: Updated parts 1-3 from “of 5” to “of 6”, added “Part: 5 of 6” header
  • Fixed API violation: Changed Verify.Is::minLength to Verify.Is::lenBetween in Part 6
  • Consolidated testing content: Removed duplication from Part 4, standardized to functional assertion style in Part 5
  • Fixed naming convention: Changed all ValidatedUser occurrences to ValidUser in Part 6
  • Added forward references: Fork-Join (Part 2), package organization (Part 2), exception handling (Parts 2-3-6)
  • Added definitions: Unit type (Part 3), test vectors (Part 5), monad practical usage (Part 1)
  • Added Promise.allOf() to composition cheat sheet (Part 2)

[1.8.0] - 2025-10-21

Added

• Comprehensive Null Policy across all JBCT documentation
  • Added dedicated “Null Policy” section to CODING_GUIDE.md
  • Added null policy to skills/jbct/fundamentals/four-return-kinds.md with examples and summary table
  • Added null policy to jbct-coder.md with clear rules and patterns
  • Added null policy to jbct-reviewer.md with review checklist
  • Core principle: “Null exists only at system boundaries, business logic uses Option.none()”
  • Defined when null IS acceptable: adapter boundaries (wrapping external APIs, database nullable columns, test inputs)
  • Defined when null is NOT acceptable: business logic returns, component parameters, null checks
  • Pattern guidance: Option.option(nullable) at adapter entry, .orElse(null) at adapter exit (DB writes only)
• Structured JBCT Skill for Claude Code
  • Reorganized skills/jbct/ with progressive detalization structure
  • fundamentals/: four-return-kinds.md, parse-dont-validate.md, no-business-exceptions.md (3 files)
  • patterns/: leaf.md, sequencer.md, fork-join.md, condition.md, iteration.md, aspects.md (6 files)
  • use-cases/: structure.md, complete-example.md (RegisterUser walkthrough) (2 files)
  • testing/: patterns.md (functional assertions, test organization) (1 file)
  • project-structure/: organization.md (vertical slicing) (1 file)
  • Total: 13 detailed markdown files for granular topic access
  • Updated SKILL.md with references to detailed resources
  • Updated README.md with complete structure overview
  • Self-contained package ready for distribution

Changed

• All version references updated from 1.7.0 to 1.8.0

[1.7.0] - 2025-10-20

Added

• proposals/private-record-constructors.md - JEP proposal for enabling private canonical constructors in records
  • Complete JEP following OpenJDK JEP 2.0 format
  • Motivation: Enable parse-don’t-validate pattern with records
  • Examples comparing current workarounds vs proposed feature
  • Integration with value object patterns
• Factory method anti-pattern guidance across all documentation
  • Explicit prohibition of nested record implementations in use case factories
  • Clear examples showing wrong (nested record) vs correct (lambda) patterns
  • Added to jbct-coder.md, CODING_GUIDE.md, jbct-reviewer.md
  • Rule: “Records are for data, lambdas are for behavior”

Changed

• Use case factory examples - All examples now use lambda returns instead of nested records
  • jbct-coder.md RegisterUser example fixed
  • CODING_GUIDE.md RegisterUser and GetUserProfile examples fixed
  • series/part-06-production-systems.md RegisterUser and GetUserProfile examples fixed
  • Reduces verbosity from 10+ lines to 5 lines per factory
• jbct-coder.md Maven preference - Added explicit instruction to prefer Maven over Gradle
  • Maven marked as “(preferred)”
  • Gradle marked as “(only if explicitly requested)”
• jbct-reviewer.md build configuration checks
  • Added Pragmatica Core dependency verification
  • Check for correct groupId, artifactId, version
  • Build configuration added as Critical priority
  • New review section for dependency issues
• Pragmatica Core dependency specification - Added Gradle coordinates alongside Maven in all docs
  • README.md, CODING_GUIDE.md, CLAUDE.md
  • Full artifact coordinates: org.pragmatica-lite:core:0.8.3
  • Both Maven and Gradle examples provided

Fixed

• Terminology consistency - “Validated Request” → “Valid Request” in CODING_GUIDE.md
• Grammar improvements - “the factory method which builds” → “factory method that builds”
• All version references updated from 1.6.2 to 1.7.0

[1.6.2] - 2025-10-19

Added

• jbct-reviewer.md - Claude Code subagent for JBCT-specialized code review
  • Reviews code for JBCT compliance (Four Return Kinds, Parse Don’t Validate, No Business Exceptions)
  • Checks structural patterns (Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects)
  • Validates project structure and naming conventions
  • Enforces testing requirements
  • Provides actionable feedback with severity levels and examples
• Unit type guidance in CODING_GUIDE.md, jbct-coder.md, and Critical Rules Checklist
  • Explicit prohibition of Void type usage
  • Mandatory use of Result<Unit> or Promise<Unit> for operations without meaningful return values
  • Use Result.unitResult() for successful Result<Unit> creation
• Project Structure & Package Organization section in jbct-coder.md
  • Vertical slicing architecture guidelines
  • Package naming conventions and placement rules
  • Layer responsibilities (domain, usecase, adapter)
  • Value object, cause, and step placement rules
• Testing Requirements section in jbct-coder.md
  • Mandatory tests (value objects, use cases with end-to-end stubs)
  • Recommended tests (complex leaves, adapters)
  • Functional assertion patterns with onSuccess/onFailure
  • Test organization guidelines
• Website dark mode feature
  • Manual theme toggle button with localStorage persistence
  • System preference detection via prefers-color-scheme
  • No-flash initialization script
  • Dark mode CSS variables and styles

Changed

• README.md AI collaboration section replaced with Claude Code Subagents section
  • Added download links for jbct-coder.md and jbct-reviewer.md
  • Installation instructions for subagents (~/.claude/agents/)
  • Usage guidance for invoking subagents
• All version references updated from 1.6.1 to 1.6.2

[1.6.1] - 2025-01-17

Added

• INVISIBLE_MIDDLE_LAYER.md - New article explaining architectural philosophy behind the Coding Technology
  • Explains how coordination mechanics disappear into the type system
  • Three-layer architecture model (Business Domain, Coordination, Language/Runtime)
  • Concrete examples comparing traditional, intermediate, and Coding Technology implementations
  • Pattern demonstrations showing how each pattern eliminates middle layer code
  • Business logic visibility analysis with line count comparisons
  • Compiler as coordination engine concept
  • Composability, type-driven coordination, and pattern-combinator mapping explanations
• usecase-internal-service example demonstrating internal service patterns

Changed

• Naming convention standardization: Replaced Validated prefix with Valid prefix throughout all documentation
  • ValidatedUser → ValidUser
  • ValidatedCredentials → ValidCredentials
  • ValidatedRequest → ValidRequest (where applicable)
  • Rationale: Valid is concise and conveys the same meaning; Validated adds no semantic value
• Documentation of Valid prefix naming convention added to:
  • CODING_GUIDE.md (new “Validated Input Naming” section)
  • jbct-coder.md (added to factory naming section)
  • series/part-02-core-principles.md (expanded naming conventions)
  • series/part-04-advanced-patterns.md (added to naming conventions)
• All version references updated from 1.6.0 to 1.6.1
• Pragmatica Core version updated from 0.8.0 to 0.8.3 in all examples
• CLAUDE.md API Reference updated from Pragmatica Core 0.8.0 to 0.8.3
  • Added new convenience methods: flatMap2(), mapToUnit()
  • Added Run variants: onPresentRun(), onEmptyRun(), onSuccessRun(), onFailureRun(), onResultRun()
  • Added async variants for Promise: onSuccessAsync(), onSuccessRunAsync(), etc.
  • Added async predicate filtering for Promise: filter(Cause, Promise<Boolean>)
  • Added lift method variants with custom exception mappers
  • Added delayed Promise factory methods: promise(TimeSpan delay, ...)
• jbct-coder.md updated to v1.6.1
  • Refined lambda constructor rules: prefer ::new, inline only with captured parameters
  • Added Condition pattern critical rule: routing only, no transformation
  • Clarified Single Level of Abstraction with constructor reference guidelines
  • Updated version references (v1.5.0 → v1.6.1, 0.8.0 → 0.8.3)

[1.6.0] - 2025-01-10

Added

• Conversation style guidelines in both CLAUDE.md files
  • Extreme brevity principle (no conversational fluff)
  • Action-first execution pattern
  • Question asking guidelines with clear thresholds
  • Read → Act → Verify execution pattern
  • Proactive todo tracking rules
  • Structured response formats with examples
• Website favicon generated from pragmatica.png
  • 32x32, 16x16 PNG favicons
  • 180x180 Apple touch icon
  • Integrated into HTML template
• EXECUTIVE_SUMMARY_SHORT.md - Condensed 865-word version for publication
  • Maintains structure of full executive summary
  • Includes diagnostic checklist, code example, metrics
  • Suitable for magazine/journal submission (InformationWeek)

Changed

• Updated website build script to copy image directory to dist
• Updated conversation style from “ask first” to “execute when clear, ask when necessary”

[1.5.0] - 2025-01-07

Added

• EXECUTIVE_SUMMARY.md - Executive brief for CTOs/VPs (2-3 pages)
  • Diagnostic checklist with 5 friction signals
  • Visual proof with side-by-side code comparisons and cognitive load analysis
  • Observable outcomes with 3 proxy metrics (review efficiency, onboarding speed, structural consistency)
  • Academic foundations (Brooks’s Law, Dijkstra’s Structured Programming, Miller’s Law, Google’s consistency findings)
  • Inevitability narrative (AI code generation, distributed teams, rising team sizes)
  • Evidence-based adoption path with micro-evidence collection framework

Changed

• Factory pattern clarifications in CODING_GUIDE.md and TECHNOLOGY.md
  • Value objects (records): serializable data structures
  • Use cases and steps (lambdas): behavioral components created at assembly time
• All EXECUTIVE_SUMMARY links point to pragmatica.dev
• README updated with executive summary reference
• Website build includes EXECUTIVE_SUMMARY.md

[1.4.0] - 2025-01-07

Added

• Static website for pragmatica.dev
  • Build script to convert markdown to HTML
  • Professional, responsive CSS design
  • HTML templates with navigation
  • Sitemap generation for SEO
  • GitHub Actions CI/CD for automatic deployment
  • Netlify configuration for hosting
  • Complete deployment documentation
  • Local development server support

Infrastructure

• GitHub Actions workflow for automated deployment to Netlify
• Netlify configuration with security headers and caching
• Cloudflare DNS setup instructions for custom domain

[1.3.0] - 2025-01-07

Added

• New Part 5: Testing Strategy & Evolutionary Approach in learning series (~3000 lines)
  • Comprehensive evolutionary testing strategy
  • Integration-first philosophy (test composition, not components)
  • Test organization patterns (nested classes, builders, canonical vectors, parameterized tests)
  • Handling complex input objects with test data builders
  • Managing large test counts without drowning in complexity
  • What to Test Where guidelines (value objects, leaves, use cases, adapters)
  • Test utilities and helpers (ResultAssertions, StubBuilders, PromiseTestUtils)
  • Complete worked example (RegisterUser evolutionary testing)
  • Comparison to traditional unit testing
  • Migration guide from traditional to evolutionary testing
• Former Part 5 “Production Systems” is now Part 6
• Cross-references between Part 4, 5, and 6 for testing content

Changed

• Series expanded from 5 to 6 parts
• Updated INDEX.md with Part 5 description and 6-part structure
• Updated README.md Quick Start with Part 5 link
• Updated all series parts to reflect “X of 6” instead of “X of 5”
• Part 6 testing section now references detailed Part 5 content
• Part 4 “What’s Next” now points to Part 5 (Testing Strategy)

Documentation

• Series version bumped to 1.1.0
• INDEX.md version history updated

[1.2.0] - 2025-01-06

Added

• Comprehensive “Naming Conventions” section consolidating all naming guidelines
• Acronym naming convention: treat acronyms as normal words using camelCase (e.g., HttpClient not HTTPClient)
• Factory method naming guidelines consolidated in dedicated section
• Test naming pattern consolidated in dedicated section
• Cross-references between sections for better navigation
• Attribution to Daniel Moka’s LinkedIn post for acronym naming convention

Changed

• Replaced inline changelog in CODING_GUIDE.md with reference to CHANGELOG.md file
• Improved document structure by consolidating scattered naming conventions

[1.1.0] - 2025-01-06

Added

• Evaluation framework section explaining five objective criteria for code decisions
• Criteria justifications for all core concepts (Four Return Kinds, Parse Don’t Validate, No Business Exceptions, Single Pattern Per Function, Single Level of Abstraction)
• Rationale subsections for all patterns (Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects) based on evaluation criteria
• Criteria justification for vertical slicing philosophy in package organization
• Evaluation framework section integrated into all series parts (Part 1-5)

Changed

• Enhanced CODING_GUIDE.md with objective evaluation framework
• Enhanced all series/*.md files with criteria-based justifications
• Improved documentation clarity by replacing subjective “best practices” with measurable standards

[1.0.1] - 2025-01-05

Added

• Adapter leaves framework independence guidance

[1.0.0] - 2025-01-05

Added

• Initial release of Java Backend Coding Technology
• Complete coding guide with patterns and principles
• Five-part learning series
• Management perspective document
• Project structure and package organization guide