From a9d15afa93c66c32a5a4d84c99fa4a2fe3e6b7f6 Mon Sep 17 00:00:00 2001
From: Warren <warren@objectstack.ai>
Date: Tue, 1 Sep 2026 04:28:31 +0000
Subject: [PATCH] Fix the self-contradictory due_offset_days description
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reading A is adjudicated and shipped: due_offset_days counts days from
the anchor day, and 0 means the anchor day itself. The field's own
description contradicted this — it said "days from the anchor" and
then gave an example ("5" on a monthly period anchored to period
start = due on the 5th) that is off by one under that reading.

Rewrite the description with a worked example on each anchor in both
duty.object.ts and catalog-item.object.ts (the catalog copy must agree
with the duty copy, since #5's catalog instantiation copies this field
onto every duty it creates), and add the same worked examples to the
due_anchor + due_offset_days section of docs/product/data-model.md.

Also clarify the field label to "Offset (days, 0 = anchor day)" so the
zero-point is visible without opening the description tooltip.

No arithmetic changes: src/functions/period.ts and its pinned tests
are untouched.

Fixes #23

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SqkTcrxUFci7nqXdbBSe2p
---
 docs/product/data-model.md         | 4 ++++
 src/objects/catalog-item.object.ts | 6 +++++-
 src/objects/duty.object.ts         | 4 ++--
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/product/data-model.md b/docs/product/data-model.md
index 1adccc7..e7596ed 100644
--- a/docs/product/data-model.md
+++ b/docs/product/data-model.md
@@ -41,6 +41,10 @@ tickable.
 **`due_anchor` + `due_offset_days`.** A quarterly duty "due in Q3" is due on
 30 September to everyone behind on it. Anchoring inside the period is what stops
 annual and semi-annual work collapsing onto the last week of December.
+`due_offset_days` counts days from the anchor day, and the anchor day itself is
+offset `0` — on `period_start`, `0` is the first day of the period and `4` is
+the fifth day; on `period_end`, `0` is the last day of the period and `-3` is
+three days before the last.
 
 **`lead_days`.** A task that appears on its due date is already late. Lead time is
 the difference between a system that reminds you and one that reports on you.
diff --git a/src/objects/catalog-item.object.ts b/src/objects/catalog-item.object.ts
index 9941243..3cf2180 100644
--- a/src/objects/catalog-item.object.ts
+++ b/src/objects/catalog-item.object.ts
@@ -68,7 +68,11 @@ export const CatalogItem = ObjectSchema.create({
       ],
     }),
 
-    due_offset_days: Field.number({ label: 'Offset (days)', defaultValue: 0 }),
+    due_offset_days: Field.number({
+      label: 'Offset (days, 0 = anchor day)',
+      defaultValue: 0,
+      description: 'Days from the anchor day, which is offset 0. On "Start of period": 0 = the first day of the period, 4 = the fifth day. On "End of period": 0 = the last day of the period, -3 = three days before the last.',
+    }),
     lead_days: Field.number({ label: 'Lead time (days)', defaultValue: 7, min: 0 }),
     grace_days: Field.number({ label: 'Grace (days)', defaultValue: 0, min: 0 }),
 
diff --git a/src/objects/duty.object.ts b/src/objects/duty.object.ts
index 7a845df..6dedcb6 100644
--- a/src/objects/duty.object.ts
+++ b/src/objects/duty.object.ts
@@ -118,9 +118,9 @@ export const Duty = ObjectSchema.create({
     }),
 
     due_offset_days: Field.number({
-      label: 'Offset (days)',
+      label: 'Offset (days, 0 = anchor day)',
       defaultValue: 0,
-      description: 'Days from the anchor. "5" with a monthly period anchored to period start = due on the 5th. Negative offsets count back from period end.',
+      description: 'Days from the anchor day, which is offset 0. On "Start of period": 0 = the first day of the period, 4 = the fifth day. On "End of period": 0 = the last day of the period, -3 = three days before the last.',
     }),
 
     lead_days: Field.number({