Projects: classes as entities, and the sidebar fits short windows

A project is a class with facts (description, status, kind, party,
dates, links, notes) in one project.set event behind the format
feature projects. Four tools (books.add_project, update_project,
projects, project); documents and decisions link to projects; B-37:
on-spec costs are expensed as incurred, repayment is revenue, and the
unrecovered cost is never below zero (Kani). Viewer: a Projects list
and a project page with its figures, by month and by account. The
sidebar measures its footer instead of reserving a fixed 172 px.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj

README.md

@@ -227,6 +227,15 @@ the side gives the direction.
   once. A business card's
   liability is a card account (B-35 item 5): while none is recorded, a
   liability whose name says "card", not "gift card", is.
+- `[[setup.projects]]` `{ name, kind?, status?, party? }`: a project
+  (rules.md B-37), added with its facts, each name once: `kind`
+  `internal`, `client`, `on_spec` or `other`; `status` `active` (the
+  default), `paused`, `finished` or `abandoned`; `party` a
+  `setup.parties` name.
+- `project = "<name>"` on a line of `lines`: the line is tagged with
+  that project (a `setup.projects` name), as the books' command tags it,
+  after the line is added. Not on a reversal, which carries its
+  original's tags.
 - `payee` on an event: the payee (by name, one of `setup.payees`) the
   entry paid. Only on an entry (`lines`): a reversal takes its
   original's, a bill names its vendor, a close and a command have none.
@@ -329,6 +338,7 @@ answers is refused, never skipped.
 | `register_row` | `asset`, `as_of` | the asset's row of the fixed asset register (B-15 rules 7 and 8, B-24): `acquired`, `in_service` (`YYYY-MM-DD`), `cost`, `accumulated_scheduled` (the schedule's), `accumulated_posted` (what the books carry), `unposted` (the one less the other), `book_value` (cost less posted), each `"0.00"` once disposed; the example names the figures it shows; an asset acquired after the day is refused | `ledger-core` `tests/bookspec.rs` |
 | `register_totals` | `as_of` | the register's totals over the assets held (B-24, B-25): `total_cost`, `total_accumulated_scheduled`, `total_accumulated_posted`, `total_book_value`, `total_depreciable_basis`, `total_tax_basis_723`, `missing_basis` (a count), and how it ties to the books: `unregistered_cost`, `unposted_depreciation`, `unattributed_accumulated`; the example names the figures it shows | `ledger-core` `tests/bookspec.rs` |
 | `asset_basis` | `asset`, no dates | the asset's basis facts and the tax figures they give (B-25): `rule`, `contributor_adjusted_basis`, `fmv_at_contribution`, `tax_basis_723`, `depreciable_basis`, `built_in_gain_704c` (a loss negative), each `"none"` where it has none, and `sec704c_1c` (`"true"` for a built-in loss, which counts only for the contributor); the example names the figures it shows | `ledger-core` `tests/bookspec.rs` |
+| `project` | `project`, `from`, `to` | the project's figures (B-37), every one given: `revenue`, `expenses` and `net` for the period (the revenue and expense lines tagged to it, closes left out), `to_date.revenue`, `to_date.expenses` and `to_date.net` (every tagged line through `to`), and `unrecovered_cost` (expenses less revenue to date, never below zero; `"none"` unless it is on spec) | `ledger-core` `tests/bookspec.rs`; `ledger-mcp` `project_figures_match_profit_and_loss_by_class` |
 | `schedule_plan` | `schedule`, no dates | the schedule's plan (B-16): what it recognizes at each month end named (`"YYYY-MM-DD"`), `"0.00"` at one it doesn't post; `total`, all it recognizes; the example names the figures it shows | `ledger-core` `tests/bookspec.rs` |
 | `iif_lines` | `as_of` | formats appendix: the file's lines in order, each its fields joined by tabs, without the CR LF that ends each | `ledger-package` `the_bookspec_iif_example_matches_the_engine` |
 | `iif_changes` | `as_of` | formats appendix: each text the file writes differently from the books, in file order, as `[what, books' text, file's text]` (the example's header gives `what`) | `ledger-package` `the_bookspec_iif_example_matches_the_engine` |
@@ -338,7 +348,8 @@ format query, and `uncategorized_accounts`, an array (`values = [ ...
 ]`). `period`, `day` and `calendar_year` give dates and a year,
 `account_names` names, `party_part`'s `direction`, `vendor_1099`'s
 `status` and `party_tin_last4` words, not figures; `register_row` gives
-dates beside its figures, `asset_basis` a rule's name, `"none"` and
+dates beside its figures, `project` gives `"none"` as the unrecovered cost of a
+project that isn't on spec, `asset_basis` a rule's name, `"none"` and
 `"true"` or `"false"`, and a `k1_tax_basis` line `"open"`, beside them.
 
 A command is tried on a copy of the books, as the books' own command

examples/projects-net-is-its-tagged-lines.toml

@@ -0,0 +1,162 @@
+# A project's figures are the revenue and expense lines tagged to it.
+#
+# wanderbooks: rules.md B-37 (projects); regression tests
+# `project_figures_are_its_tagged_lines` (ledger-core tests/spec_projects.rs),
+# `project_figures_match_profit_and_loss_by_class` (ledger-mcp
+# tests/spec_projects.rs).
+#
+# Expected values worked by hand: Alpha earns 5,000.00 and costs 1,800.00
+# (contractor) + 120.00 (its part of the tool) = 1,920.00; the contractor
+# billed twice in March is reversed, so March nets to zero. Beta costs
+# 80.00; its test devices (an asset) count nothing. Rent is no project's.
+# The projects and the untagged rent add up to the books' net income:
+# 3,080.00 - 80.00 - 1,500.00 = 1,500.00.
+
+id = "projects-net-is-its-tagged-lines"
+title = "A project's net is its tagged revenue less its tagged expenses"
+rule = "A project's revenue and expenses for a period MUST be the revenue and expense lines tagged to it, dated in the period, closing entries left out; a tagged balance-sheet line MUST count nothing; a shared cost counts only as split across lines; and the projects with the untagged lines MUST add up to the period's net income."
+status = "CONVENTION"
+sources = [
+  "Job-order costing: a job cost sheet accumulates the revenue and the direct costs identified with one job (management-accounting convention; no overhead is allocated here: wanderbooks docs/spec/rules.md B-37)",
+  "wanderbooks docs/spec/rules.md B-11 and B-14: a period's net income is its revenue less its expenses, closing entries left out",
+]
+tags = ["projects", "classes", "job-costing", "accrual"]
+
+[setup]
+currency = "USD"
+fiscal_year_start = "01-01"
+basis = "accrual"
+rounding = "half-even"
+
+[[setup.accounts]]
+code = "1000"
+name = "Cash"
+type = "asset"
+[[setup.accounts]]
+code = "1200"
+name = "Equipment"
+type = "asset"
+[[setup.accounts]]
+code = "4000"
+name = "Revenue"
+type = "revenue"
+[[setup.accounts]]
+code = "6000"
+name = "Contractors"
+type = "expense"
+[[setup.accounts]]
+code = "6100"
+name = "Software"
+type = "expense"
+[[setup.accounts]]
+code = "6200"
+name = "Rent"
+type = "expense"
+
+[[setup.projects]]
+name = "Alpha"
+kind = "client"
+[[setup.projects]]
+name = "Beta"
+kind = "internal"
+
+[[events]]
+date = "2026-02-03"
+description = "Alpha milestone paid"
+lines = [
+  { account = "1000", side = "debit", amount = "5000.00" },
+  { account = "4000", side = "credit", amount = "5000.00", project = "Alpha" },
+]
+[[events]]
+date = "2026-02-10"
+description = "Contractor for Alpha"
+lines = [
+  { account = "6000", side = "debit", amount = "1800.00", project = "Alpha" },
+  { account = "1000", side = "credit", amount = "1800.00" },
+]
+[[events]]
+date = "2026-02-15"
+description = "Design tool, split by use"
+lines = [
+  { account = "6100", side = "debit", amount = "120.00", project = "Alpha" },
+  { account = "6100", side = "debit", amount = "80.00", project = "Beta" },
+  { account = "1000", side = "credit", amount = "200.00" },
+]
+[[events]]
+date = "2026-02-28"
+description = "Studio rent"
+lines = [
+  { account = "6200", side = "debit", amount = "1500.00" },
+  { account = "1000", side = "credit", amount = "1500.00" },
+]
+[[events]]
+date = "2026-03-05"
+description = "Test devices for Beta"
+lines = [
+  { account = "1200", side = "debit", amount = "900.00", project = "Beta" },
+  { account = "1000", side = "credit", amount = "900.00" },
+]
+[[events]]
+date = "2026-03-12"
+description = "Contractor for Alpha, billed twice"
+lines = [
+  { account = "6000", side = "debit", amount = "1800.00", project = "Alpha" },
+  { account = "1000", side = "credit", amount = "1800.00" },
+]
+[[events]]
+date = "2026-03-13"
+description = "Reverse entry 6"
+reverses = 6
+
+[[expect]]
+query = "project"
+project = "Alpha"
+from = "2026-01-01"
+to = "2026-12-31"
+[expect.values]
+revenue = "5000.00"
+expenses = "1920.00"
+net = "3080.00"
+"to_date.revenue" = "5000.00"
+"to_date.expenses" = "1920.00"
+"to_date.net" = "3080.00"
+unrecovered_cost = "none"
+
+[[expect]]
+query = "project"
+project = "Alpha"
+from = "2026-03-01"
+to = "2026-03-31"
+[expect.values]
+revenue = "0.00"
+expenses = "0.00"
+net = "0.00"
+"to_date.revenue" = "5000.00"
+"to_date.expenses" = "1920.00"
+"to_date.net" = "3080.00"
+unrecovered_cost = "none"
+
+[[expect]]
+query = "project"
+project = "Beta"
+from = "2026-01-01"
+to = "2026-12-31"
+[expect.values]
+revenue = "0.00"
+expenses = "80.00"
+net = "-80.00"
+"to_date.revenue" = "0.00"
+"to_date.expenses" = "80.00"
+"to_date.net" = "-80.00"
+unrecovered_cost = "none"
+
+[[expect]]
+query = "profit_and_loss"
+from = "2026-01-01"
+to = "2026-12-31"
+[expect.values]
+"4000" = "5000.00"
+"6000" = "1800.00"
+"6100" = "200.00"
+"6200" = "1500.00"
+net_income = "1500.00"

examples/projects-on-spec-costs-are-expenses.toml

@@ -0,0 +1,138 @@
+# Work on spec: its costs are expenses when incurred, and the hoped-for
+# payment is income only when received; until then it is no receivable.
+#
+# wanderbooks: rules.md B-37 item 4; regression tests
+# `unrecovered_cost_only_for_on_spec_and_never_negative` (ledger-core),
+# `on_spec_project_shows_unrecovered_cost_and_others_null` (ledger-mcp).
+#
+# Expected values worked by hand: 1,400.00 + 60.00 = 1,460.00 of costs,
+# nothing receivable (1100 stays 0.00). Repaid 1,000.00: 460.00 still
+# unrecovered. Repaid 700.00 more: 1,700.00 in, 240.00 net, nothing
+# unrecovered (never below zero).
+#
+# Both sources are quoted through Deloitte's DART roadmaps and not yet
+# re-read in the ASC basic view (wanderbooks docs/spec/sources/fasb-asc.md):
+# an open item.
+
+id = "projects-on-spec-costs-are-expenses"
+title = "On-spec costs are expenses; a repayment is income when received"
+rule = "The costs of work done on spec MUST be expensed as incurred, and a payment hoped for MUST NOT be recorded, as a receivable or as income, until it is received; a project's unrecovered cost MUST be its tagged expenses less its tagged revenue to date, never below zero."
+status = "AUTHORITY"
+sources = [
+  "ASC 450-30-25-1: a contingency that might result in a gain usually is not reflected in the financial statements, since that might recognize revenue before its realization (originally FAS 5 ¶17(a))",
+  "ASC 340-40-25-5: costs to fulfill an anticipated contract are an asset only if, among other criteria, they are expected to be recovered (here recovery is uncertain: expensed; wanderbooks docs/spec/rules.md B-22)",
+]
+tags = ["projects", "on-spec", "gain-contingency", "accrual"]
+
+[setup]
+currency = "USD"
+fiscal_year_start = "01-01"
+basis = "accrual"
+rounding = "half-even"
+
+[[setup.accounts]]
+code = "1000"
+name = "Cash"
+type = "asset"
+[[setup.accounts]]
+code = "1100"
+name = "Accounts Receivable"
+type = "asset"
+[[setup.accounts]]
+code = "4000"
+name = "Revenue"
+type = "revenue"
+[[setup.accounts]]
+code = "6000"
+name = "Contractors"
+type = "expense"
+[[setup.accounts]]
+code = "6100"
+name = "Hosting"
+type = "expense"
+
+[[setup.projects]]
+name = "Harbor app"
+kind = "on_spec"
+
+[[events]]
+date = "2026-04-02"
+description = "Prototype build"
+lines = [
+  { account = "6000", side = "debit", amount = "1400.00", project = "Harbor app" },
+  { account = "1000", side = "credit", amount = "1400.00" },
+]
+[[events]]
+date = "2026-04-20"
+description = "Hosting for the prototype"
+lines = [
+  { account = "6100", side = "debit", amount = "60.00", project = "Harbor app" },
+  { account = "1000", side = "credit", amount = "60.00" },
+]
+[[events]]
+date = "2026-06-15"
+description = "Harbor repays part of the prototype"
+lines = [
+  { account = "1000", side = "debit", amount = "1000.00" },
+  { account = "4000", side = "credit", amount = "1000.00", project = "Harbor app" },
+]
+[[events]]
+date = "2026-07-01"
+description = "Harbor pays the rest, and more"
+lines = [
+  { account = "1000", side = "debit", amount = "700.00" },
+  { account = "4000", side = "credit", amount = "700.00", project = "Harbor app" },
+]
+
+[[expect]]
+query = "project"
+after = 2
+project = "Harbor app"
+from = "2026-01-01"
+to = "2026-04-30"
+[expect.values]
+revenue = "0.00"
+expenses = "1460.00"
+net = "-1460.00"
+"to_date.revenue" = "0.00"
+"to_date.expenses" = "1460.00"
+"to_date.net" = "-1460.00"
+unrecovered_cost = "1460.00"
+
+[[expect]]
+query = "balances"
+after = 2
+as_of = "2026-04-30"
+[expect.values]
+"1100" = "0.00"
+"6000" = "1400.00"
+"6100" = "60.00"
+
+[[expect]]
+query = "project"
+after = 3
+project = "Harbor app"
+from = "2026-01-01"
+to = "2026-06-30"
+[expect.values]
+revenue = "1000.00"
+expenses = "1460.00"
+net = "-460.00"
+"to_date.revenue" = "1000.00"
+"to_date.expenses" = "1460.00"
+"to_date.net" = "-460.00"
+unrecovered_cost = "460.00"
+
+[[expect]]
+query = "project"
+project = "Harbor app"
+from = "2026-01-01"
+to = "2026-12-31"
+[expect.values]
+revenue = "1700.00"
+expenses = "1460.00"
+net = "240.00"
+"to_date.revenue" = "1700.00"
+"to_date.expenses" = "1460.00"
+"to_date.net" = "240.00"
+unrecovered_cost = "0.00"