Skip to content

Commit 2e01e78

Browse files
alanbldalanbld
committed
docs(rfc): Add RFC-0012 Temporal Regimes (Draft)
Introduces Temporal Regimes as an explicit abstraction for how time behaves for different kinds of project activities: - Work Regime: effort-bearing tasks, advances on working days - Event Regime: milestones/releases, exact dates on any day - Deadline Regime: contractual constraints (future) Phase 1 (current): Implicit assignment based on task.is_milestone() Phase 2 (v0.10+): Explicit `regime:` syntax in DSL This formalizes the milestone calendar exception implemented in v0.9.4 and provides a foundation for advanced temporal modeling. Also updates RFC index with missing RFCs 0009-0011.
1 parent 54b8c95 commit 2e01e78

File tree

2 files changed

+284
-4
lines changed

2 files changed

+284
-4
lines changed

‎docs/rfc/README.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,18 @@ This directory contains all Request for Comments (RFC) documents for utf8proj.
1414
| [RFC-0006](RFC-0006-FOCUS-VIEW.md) | Focus View for Gantt Charts | ✅ Implemented | 2026-01-15 |
1515
| [RFC-0007](RFC-0007-WASM-PLAYGROUND-AI-INTEGRATION.md) | WASM Playground with AI-Assisted Editing | 📝 Draft | 2026-01-15 |
1616
| [RFC-0008](RFC-0008-PROGRESS-AWARE-CPM.md) | Progress-Aware CPM | ✅ Implemented | 2026-01-15 |
17+
| [RFC-0009](RFC-0009-EXCEL-WASM-EXPORT.md) | Excel WASM Export | 📝 Draft | 2026-01-16 |
18+
| [RFC-0010](RFC-0010-AUTOMATED-TESTING-AND-DEMOS.md) | Automated Testing and Demos | ⚠️ Partial | 2026-01-16 |
19+
| [RFC-0011](RFC-0011-CLASSIFIER-ABSTRACTION.md) | Classifier Abstraction | ✅ Implemented | 2026-01-16 |
20+
| [RFC-0012](RFC-0012-TEMPORAL-REGIMES.md) | Temporal Regimes | 📝 Draft | 2026-01-18 |
1721

1822
## Implementation Summary
1923

2024
| Category | Count | RFCs |
2125
|----------|-------|------|
22-
| ✅ Fully Implemented | 6 | 0001, 0002, 0003, 0004, 0006, 0008 |
23-
| ⚠️ Partially Implemented | 1 | 0005 (Phase 1) |
24-
| 📝 Design Only | 1 | 0007 |
26+
| ✅ Fully Implemented | 7 | 0001, 0002, 0003, 0004, 0006, 0008, 0011 |
27+
| ⚠️ Partially Implemented | 2 | 0005 (Phase 1), 0010 (videos only) |
28+
| 📝 Design Only | 3 | 0007, 0009, 0012 |
2529

2630
## Status Definitions
2731

@@ -42,7 +46,7 @@ This directory contains all Request for Comments (RFC) documents for utf8proj.
4246

4347
## Creating a New RFC
4448

45-
1. Use the next available number (currently RFC-0009)
49+
1. Use the next available number (currently RFC-0013)
4650
2. Follow the naming convention: `RFC-NNNN-SHORT-TITLE.md`
4751
3. Include standard header fields (RFC Number, Status, Created, Related)
4852
4. Update this README with the new RFC entry

‎docs/rfc/RFC-0012-TEMPORAL-REGIMES.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
# RFC 0012 — Temporal Regimes: Explicit Time Semantics for Tasks and Events
2+
3+
**Status:** Draft
4+
**Author:** utf8proj core team
5+
**Created:** 2026-01-18
6+
**Target Version:** ≥ 0.10
7+
**Supersedes:** Implicit calendar-based task semantics
8+
**Related Issues:** SNET/FNET rounding on non-working days, milestone scheduling semantics
9+
10+
---
11+
12+
## Executive Summary
13+
14+
This RFC introduces **Temporal Regimes**: an explicit abstraction that defines *how time behaves* for different kinds of project activities.
15+
16+
By separating **work**, **events**, and **deadlines** at the semantic level, utf8proj resolves long-standing scheduling ambiguities, fixes known bugs (e.g. SNET on weekends), and establishes a foundation for advanced project modeling that traditional tools cannot express.
17+
18+
---
19+
20+
## 1. Motivation: The Calendar Conflation Problem
21+
22+
### 1.1 One Calendar, Too Many Meanings
23+
24+
Today, utf8proj (like most PM tools) relies on calendars to model fundamentally different temporal concepts:
25+
26+
| Real-World Concept | Current Modeling | Issue |
27+
|-------------------|------------------|-------|
28+
| **Work effort** (coding, construction) | Working-day calendar | ✅ Correct |
29+
| **Events** (releases, audits) | Working-day calendar + hacks | ❌ Events aren't work |
30+
| **Deadlines** (contractual) | Working-day calendar | ❌ Calendar mismatch |
31+
| **Milestones** | Zero-duration tasks | ❌ Rounding ambiguity |
32+
33+
Calendars are designed to answer *"when can work be done?"*
34+
They are routinely misused to answer *"when does something happen?"*
35+
36+
### 1.2 The SNET Bug as a Symptom
37+
38+
The recently fixed bug:
39+
40+
```
41+
start_no_earlier_than: 2018-06-03 # Sunday
42+
→ scheduled on 2018-06-01 (Friday)
43+
```
44+
45+
exposed the deeper issue:
46+
47+
> **Events do not follow work calendars.**
48+
49+
Fixing rounding logic alone treats the symptom, not the cause.
50+
51+
### 1.3 Why This Matters Now
52+
53+
* Professional users expect correct event scheduling
54+
* Complex projects mix work, events, and deadlines
55+
* Ad-hoc exceptions increase solver complexity and user confusion
56+
57+
---
58+
59+
## 2. Design Principles
60+
61+
1. **Calendars constrain effort, not reality**
62+
2. **Events exist independently of work availability**
63+
3. **Temporal semantics must be explicit**
64+
4. **Backward compatibility is mandatory**
65+
66+
---
67+
68+
## 3. Proposal: Temporal Regimes
69+
70+
A **Temporal Regime** defines how time behaves for a task:
71+
72+
* which days advance time
73+
* how constraints round (or do not)
74+
* how durations are interpreted
75+
76+
A task operates under exactly **one regime**, intrinsic to its nature.
77+
78+
---
79+
80+
## 4. Canonical Regimes
81+
82+
### 4.1 Work Regime (default)
83+
84+
For effort-bearing tasks.
85+
86+
```
87+
Advances on: working days
88+
Floor constraints: round forward
89+
Ceiling constraints: round backward
90+
Duration meaning: effort days
91+
```
92+
93+
Examples: development, construction, testing.
94+
95+
---
96+
97+
### 4.2 Event Regime (default for milestones)
98+
99+
For factual occurrences.
100+
101+
```
102+
Advances on: all calendar days
103+
Constraint rounding: none (exact dates)
104+
Duration meaning: point-in-time (typically 0)
105+
```
106+
107+
Examples: releases, approvals, audits, go-live dates.
108+
109+
---
110+
111+
### 4.3 Deadline Regime (future)
112+
113+
For legal or contractual constraints.
114+
115+
```
116+
Advances on: calendar days
117+
Constraint rounding: none
118+
Duration meaning: calendar days
119+
```
120+
121+
---
122+
123+
## 5. Implicit vs Explicit Regimes
124+
125+
### Phase 1 (≤ 0.9.x): Implicit Assignment
126+
127+
No syntax changes.
128+
129+
```rust
130+
if task.is_milestone() {
131+
regime = Event
132+
} else {
133+
regime = Work
134+
}
135+
```
136+
137+
This alone fixes SNET/FNET weekend behavior correctly.
138+
139+
---
140+
141+
### Phase 2 (≥ 0.10): Explicit Syntax
142+
143+
```proj
144+
task milestone "Release v1.0" {
145+
regime: event
146+
start_no_earlier_than: 2024-06-03 # Sunday, honored exactly
147+
}
148+
149+
task "Implementation" {
150+
regime: work
151+
duration: 10d # working days
152+
}
153+
```
154+
155+
Explicit regimes communicate intent and enable validation.
156+
157+
---
158+
159+
## 6. Solver Architecture Impact
160+
161+
### 6.1 Core Abstraction
162+
163+
```rust
164+
enum TemporalRegime {
165+
Work,
166+
Event,
167+
Deadline, // future
168+
}
169+
```
170+
171+
Each regime governs:
172+
173+
* date advancement
174+
* constraint application
175+
* rounding rules
176+
177+
Dependencies transfer **dates**, not regimes.
178+
179+
---
180+
181+
## 7. Mixed-Regime Dependencies
182+
183+
Example:
184+
185+
```proj
186+
task milestone "Approval" {
187+
regime: event
188+
start_no_earlier_than: 2024-06-03 # Sunday
189+
}
190+
191+
task "Implementation" {
192+
regime: work
193+
depends: "Approval"
194+
duration: 5d
195+
}
196+
```
197+
198+
**Rule:**
199+
200+
* Approval occurs Sunday
201+
* Implementation advances from Sunday using *work* rules → starts Monday
202+
203+
This mirrors real-world reasoning and avoids semantic leakage.
204+
205+
---
206+
207+
## 8. Benefits
208+
209+
### Immediate
210+
211+
* Fixes known constraint bugs naturally
212+
* Removes milestone special-casing
213+
* Simplifies solver logic
214+
215+
### Medium-Term
216+
217+
* Clearer language semantics
218+
* Better diagnostics and validation
219+
* Fewer calendar hacks
220+
221+
### Long-Term
222+
223+
* Custom temporal regimes
224+
* Industry-specific modeling
225+
* Advanced temporal analysis
226+
227+
---
228+
229+
## 9. Alternatives Rejected
230+
231+
### Calendar Exceptions
232+
233+
❌ Treat symptoms, not cause
234+
❌ Do not generalize
235+
236+
### Task Flags (`ignore_calendar`)
237+
238+
❌ Implicit semantics
239+
❌ Non-composable
240+
241+
### Separate "Event Calendars"
242+
243+
❌ Calendars still model work availability conceptually
244+
245+
---
246+
247+
## 10. Backward Compatibility
248+
249+
**Guarantee:**
250+
Existing projects will behave identically or *more correctly*.
251+
252+
Milestones that previously snapped to working days will now schedule on their actual dates without requiring changes.
253+
254+
---
255+
256+
## 11. Open Questions
257+
258+
* Should regimes be visualized explicitly in reports?
259+
* Should dependencies be validated across incompatible regimes?
260+
* When to expose user-defined regimes?
261+
262+
---
263+
264+
## 12. Conclusion
265+
266+
Temporal Regimes elevate time from an implementation detail to a first-class concept.
267+
268+
They resolve real bugs, clarify semantics, simplify the solver, and position utf8proj as a genuinely next-generation project planning language.
269+
270+
> *Calendars describe when we can work.*
271+
> *Regimes describe what time means.*
272+
273+
---
274+
275+
**Recommendation:**
276+
Approve Phase 1 for immediate inclusion, with Phase 2 targeted for 0.10.

0 commit comments

Comments
 (0)