lot tracking, hledger 2.x, AI policy

.version

@@ -1 +1 @@
-1.52.99
+1.99

README.md

@@ -1,4 +1,34 @@
 # hledger
+
+## About this branch
+
+This is the `hledger2` branch, a development branch for the hledger 2.x releases.
+This branch is mutable (it can be force-pushed).
+
+For the hledger 1.x series, see `hledger1`.
+`master` is currently the same as `hledger1`.
+It will absorb `hledger2`, and possibly be renamed to `main`, when hledger 2.0 is released.
+
+Some goals for the 2.x series:
+
+- continue and improve 1.x's reliability
+- provide excellent lot tracking and capital gains calculation
+- explore ethical use of AI as a dev tool
+- more cleanup and simplification of code, docs, process, finance
+- more speed
+- more interoperability
+- more use of jj for version management
+- easier contribution
+
+and for 1.x:
+
+- continued stability, installability
+- bugfix releases to fix newly discovered regressions, if any
+- preserve the non-AI-assisted codebase, and try to keep it that way
+
+Related discussion: [Thoughts on hledger 2 #2547](https://github.com/simonmichael/hledger/issues/2547)
+
+
 ## Robust, intuitive plain text accounting
 [![license](https://img.shields.io/badge/license-GPLv3+-brightgreen.svg)](https://www.gnu.org/licenses/gpl.html)
 [![on hackage](https://img.shields.io/hackage/v/hledger.svg?label=hackage&colorB=green)](https://hackage.haskell.org/package/hledger)

Shake.hs

@@ -1,6 +1,7 @@
 #!/usr/bin/env stack
 {- stack script --resolver nightly-2025-09-30 --compile
    --extra-include-dirs /Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/usr/include/ffi
+   --extra-dep shake-0.19.9
    --package base-prelude
    --package directory
    --package extra

doc/AI.md

@@ -0,0 +1,55 @@
+# AI policy
+
+The productivity benefits from AI-assisted software development are becoming obvious.
+The many potential costs and risks will keep becoming clearer.
+
+Here are some current policies for AI use in the hledger project:
+
+- hledger does not use AI at runtime.
+
+- hledger 1.x (2007..2025) has been developed without AI assistance.
+
+- hledger 2.x (2026..) is developed with careful AI assistance.
+
+- This bears repeating: careful AI assistance is not "vibe coding".
+  We aim to increase quality and maintainability, not decrease them.
+
+- The codebase remains human maintainable. We can always stop using AI and keep moving forward.
+
+- We aim to use only the more principled/trustworthy/sustainable tools and providers.
+  For now that means we prefer Anthropic, Ecosia, local LLMs, and such.
+
+- We monitor and try to limit and optimise our AI resource usage (represented by tokens, cost, etc.)
+
+- We monitor the impact of AI tools on the project, ourselves, and the planet and make adjustments as needed.
+
+Justification for AI use in this project:
+
+- I needed it to fully design and implement robust tax lot tracking in hledger.
+  This is a feature that I have been wanting for years, but it was just too big/intricate to tackle.
+  Use of AI tools made it possible. I think it's unlikely hledger would have ever got this feature without them.
+
+- Although similar features exist in other free software (Beancount/Ledger/rustledger/BittyTax/rotki/RP2/..),
+  I believe this new implementation provides flexibility currently not available elsewhere -
+  private, plain text, and capable of modelling real world lot operations and US pre- and post-2025 booking methods.
+  This (I hope) will provide value to many.
+
+- I imagine it is overall more efficient in resources and human energy,
+  for developers to use AI to develop efficient deterministic software,
+  than to have everyone using AI individually to try and do the same tasks less efficiently and less reliably.
+  Ie, let's move the AI use upstream as far as possible - use it briefly at design/implementation time,
+  not repeatedly at usage time.
+
+- The "bitter lesson" says that general computation always eventually wins over special-purpose systems -
+  suggesting that the lifetime and value of specialised tools like hledger will decrease.
+  However, there is at least a time lag, and for some time yet there will be a gap in efficiency, cost, reliability,
+  and so on, making this work worthwhile.
+
+- We are making mindful limited use of unsustainable technologies for a short time, 
+  in preparation for more sustainable versions (local LLMs, ASIC LLMs) coming soon.
+
+- It is a learning experiment that can be discontinued or even rolled back at any time.
+
+If you are a hledger user who objects to any use of AI, for one reason or another: I can understand.
+AI is a tool, probably too dangerous for us, but it's here and we're going to have to try to survive it.
+The AI-free hledger 1.x still exists, will continue to receive at least regression fixes, and can be revived or forked at any time if needed.

doc/IMPACT.md

@@ -0,0 +1,18 @@
+# Impact
+
+In the 21st century we are living in a time of collapse and disruption of many natural and human systems.
+
+As hledger users, contributors and especially developers,
+we all are responsible and accountable for this project's impact on the world.
+
+On this page we try to understand and describe impacts
+this project has, or could have, on things outside it.
+Such as, eg:
+
+- [CLIMATE](CLIMATE.md)
+- [AI](AI.md) use
+- people using or needing accounting software
+- FOSS developers and users
+- people using or interested in Haskell
+- the Plain Text Accounting community
+- other PTA projects such as Ledger and Beancount

doc/NOTE-2.x.md

@@ -0,0 +1,62 @@
+# hledger 2.x
+
+## Strategy
+
+Summary of discussion [Thoughts on hledger 2 #2547](https://github.com/simonmichael/hledger/issues/2547):
+
+### Positions
+
+**Simon's motivations**: drop costly cruft, marketing power of "2.0", lot tracking as flagship feature, AI-era demarcation, decouple from the 3-month release cycle.
+
+**New users (rickles42, Daniii44)**: Beancount's v2->v3 transition was a cautionary tale -- intermingled docs, broken companion tools, unclear what works with which version. Don't repeat that.
+
+**adept (collaborator)**: don't break compatibility without a clear goal that requires it. History is full of needless rewrites that killed projects.
+
+### Recommended: "Boring 2.0"
+
+Stay on master, release 2.0 when ready. Don't maintain parallel long-lived branches.
+
+1. **Linear release path**: 1.52 -> 1.99.1 (preview) -> 1.99.2 -> ... -> 2.0. Avoids the cost of maintaining two diverging trunks.
+
+2. **Minimise breaking changes; make them opt-in first**: new behaviours behind flags (like `--lots`), old behaviours deprecated with warnings for a release or two, then removed. Proven pattern (Rust editions, Python `__future__`, GHC extensions).
+
+3. **Lot tracking alone justifies 2.0**: it's a large, data-model-impacting feature. Combined with accumulated improvements, it's enough. Bundling too many breaking cleanups risks the Beancount trap.
+
+4. **Keep docs unified**: a single docset with "New in 2.0" / "Changed in 2.0" callouts, not two divergent doc trees.
+
+5. **AI demarcation is worth noting but shouldn't drive versioning**: it's a process change, not user-facing. Mention in release notes, not a reason to break compatibility.
+
+### Key Principle
+
+Take the marketing win (call it 2.0) but keep the technical disruption minimal.
+
+### Current most likely plan:
+
+- Keep using one master branch.
+- On next release day (march 1st), release both 1.52 (minor updates) and 1.99.1 (2.0 preview 1, with lot tracking).
+- Don't intentionally break anything, except in the usual way (as rarely as possible, with easy workarounds and deprecation periods).
+
+## Goals
+
+SM 2026-02:\
+Some goals for 2.x:
+
+- continue and improve 1.x's reliability
+- excellent lots/capital gains tracking
+- more interoperability/convertibility
+- more speed
+- more customisation paths
+
+and:
+
+- more use of AI as a dev tool; clarify policies
+- more use of jj to simplify version management
+- more aggressive cleanup and simplification of code/doc/process/finance..
+- easier contribution
+
+and for 1.x:
+
+- continued installability/usability
+- preserve the stable/known hledger 1.x feature set
+- preserve the non-AI-assisted codebase; draw a line between pre and post-AI eras
+

doc/NOTE-amount-classes.md

@@ -0,0 +1,138 @@
+# Typeclass Semantics for Amounts
+
+**Date:** 2026-02-01
+**Context:** Design question on whether to define amount semantics via Monoid first, then Num, or vice versa.
+
+## Question
+
+Is it better to define amounts' semantics in terms of standard typeclasses like Monoid first, and then define Num operations in terms of those?
+
+## Current State
+
+### MixedAmount (hledger-lib/Hledger/Data/Amount.hs:848-863)
+
+```haskell
+instance Semigroup MixedAmount where
+  (<>) = maPlus
+
+instance Monoid MixedAmount where
+  mempty = nullmixedamt
+
+instance Num MixedAmount where
+  (+) = maPlus          -- delegates to Monoid operation
+  (*) = error "..."     -- intentionally partial
+  signum = error "..."  -- intentionally partial
+```
+
+### Amount (hledger-lib/Hledger/Data/Amount.hs:300-307)
+
+```haskell
+instance Num Amount where
+  (+) = similarAmountsOp (+)  -- errors if commodities differ
+  (*) = similarAmountsOp (*)  -- questionable semantics
+  -- No Semigroup/Monoid instance at all
+```
+
+## Analysis
+
+### MixedAmount Follows Monoid-First Design
+
+**Strengths:**
+- ✅ Core semantics defined via `maPlus :: MixedAmount -> MixedAmount -> MixedAmount` (line 905-906)
+- ✅ Num instance delegates to Monoid (`(+) = maPlus`)
+- ✅ Explicitly rejects nonsensical operations (multiplication, signum)
+- ✅ Matches DESIGN-amounts-keys.md observation: "MixedAmount forms a commutative monoid" (line 114-121)
+
+### Amount Does NOT
+
+**Problems:**
+- ❌ Only has Num, no Monoid/Semigroup
+- ❌ Can't have a proper Monoid (no identity: `nullamt + $1` ≠ `$1` due to commodity difference)
+- ❌ Num instance is **partial** (errors on mismatched commodities)
+- ❌ Implements `(*)` with unclear semantics
+
+## Recommendation: Monoid-First is Better
+
+### Reasons
+
+1. **Semantic Clarity**
+   - The key operation is aggregation (combining amounts)
+   - Monoid captures exactly this - no more, no less
+   - When deciding "what goes in the key?", you're really asking "when does `<>` combine vs keep separate?"
+
+2. **Partial Num is a Code Smell**
+   - If you need `error` in Num methods, the type doesn't truly satisfy the Num contract
+   - Better to not have the instance than to have a partial one
+
+3. **Aligns with Design Documents**
+   - DESIGN-amounts-keys.md explicitly identifies the commutative monoid structure as fundamental (line 114-121)
+   - The core operation `add1` (line 123-129) is monoid addition
+
+4. **Better Composition**
+   - Monoid instances compose beautifully (e.g., `Map k v` is a Monoid if `v` is)
+   - This helps with the `MixedAmount = Map Key Amount` design
+
+5. **Forces Clear Thinking**
+   - Monoid has simpler laws (associativity + identity)
+   - Easier to verify and test
+   - Num brings unnecessary baggage (multiplication, division, etc.)
+
+### Theoretical Foundation
+
+From abstract algebra perspective:
+
+- **Monoid**: Just needs associativity, identity, and closure - minimal structure
+- **Num**: Implies ring-like structure with multiplication - too much structure for amounts
+- **For amounts**: Addition forms a commutative monoid, but multiplication is not well-defined
+  - What is `$1 * $1`? `$1`? Type error? `$²1`?
+  - What is `$1 * €1`? Nonsensical.
+
+## Concrete Suggestions
+
+### Short Term (Low Risk)
+- Keep current MixedAmount design (already follows Monoid-first)
+- Document that Num instance is a convenience wrapper around Monoid
+- Consider deprecation warnings on partial operations
+
+### Medium Term (Moderate Risk)
+- Drop Amount's Num instance entirely
+- Add clear utility functions for amount arithmetic:
+  ```haskell
+  amountPlus :: Amount -> Amount -> Either String Amount
+  -- Returns Left if commodities don't match
+  ```
+
+### Long Term (Requires Migration)
+- Consider Amount Semigroup instance IF there's a sensible (<>) that doesn't require same commodity
+- Or: Keep Amount without Monoid (since no proper identity) but use Semigroup for combining
+- Make MixedAmount the primary abstraction for all arithmetic
+
+## Tradeoffs
+
+**Lost Convenience:**
+- Can't write `amount1 + amount2`
+- Must write `amount1 <> amount2` or explicit function calls
+
+**But:**
+- This is already partial anyway (errors on commodity mismatch)
+- Making it explicit forces handling the error case
+- More honest API
+
+## Related
+
+- **DESIGN-amounts-keys.md** - Discusses MixedAmount monoid structure
+- **hledger-lib/Hledger/Data/Amount.hs:905** - `maPlus` implementation
+- **hledger-lib/Hledger/Data/Amount.hs:848** - Current Semigroup/Monoid instances
+
+## Open Questions
+
+1. Should Amount have a Semigroup instance? What would `<>` mean for amounts with different commodities?
+2. If we remove Num from Amount, what impact on existing code?
+3. Should we use a different type for "amounts that can be added" vs "amounts that must be kept separate"?
+4. Could we use a phantom type to track whether an Amount is "simple" (can add) vs "complex" (need MixedAmount)?
+
+## Conclusion
+
+**Monoid-first design is theoretically cleaner and aligns better with amount semantics.** The current MixedAmount implementation already follows this pattern. Amount's Num instance is a historical convenience that causes more confusion than it solves.
+
+Recommendation: Embrace Monoid as the primary abstraction for amount aggregation, with Num as a thin, well-documented convenience layer that explicitly delegates to Monoid operations.