<?xml version="1.0" encoding="UTF-8"?>
<gsl-prompt id="20250802T024329+0000" type="feat">
<gsl-header>

# UTC-Synchronized "Today" Folder Logic for OBK CLI
</gsl-header>

<gsl-block>

<gsl-purpose>
<gsl-title>

## 1. Purpose
</gsl-title>
<gsl-description>

Update the `obk` CLI so that all commands referencing "today" (e.g., `trace-id`, `validate-today`, `harmonize-today`) use a shared, UTC-synchronized folder/date logic. Support an explicit timezone override via CLI option, defaulting to UTC. The goal is to eliminate ambiguity between local time and UTC, ensuring CI, automation, and end-users all reference the same day by default.
</gsl-description>
</gsl-purpose>

<gsl-inputs>
<gsl-title>

## 2. Inputs
</gsl-title>
<gsl-description>

| Input                                              | Notes                                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `utc-synchronized-today-logic.md`                  | Reference article describing desired folder/date logic for “today” across all CLI commands |
| `prompt-template-for-codex-agents.md`              | Prompt file structure and section conventions                                             |
| `adhoc-task-template-for-codex-agents.md`          | Ad-hoc Codex prompt conventions and allowed file policies                                 |
| `one-line-manual-tests.md`                         | Best practices for designing concise manual TDD tests                                     |
| Stubbed prompt                         |                                     |

</gsl-description>
</gsl-inputs>

<gsl-outputs>
<gsl-title>

## 3. Outputs
</gsl-title>
<gsl-description>

- Refactored folder/date logic for “today” in `cli.py`
- CLI commands (`trace-id`, `validate-today`, `harmonize-today`) accepting and defaulting to `--timezone UTC`
- Updated help output for all affected commands
- New/updated manual and automated tests verifying consistent UTC/tz-aware folder selection

</gsl-description>
</gsl-outputs>

<gsl-workflows>
<gsl-title>

## 4. Workflows
</gsl-title>
<gsl-description>

#### Manual Acceptance Test (when it is close to midnight EST)

##### **1. Check Current Local and UTC Time**

* **Why:** So you know what “today” means in each context.
    
* **How:**
    
    ```bash
    python -c "from datetime import datetime, timezone; print('UTC:', datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M')); import time; print('Local:', time.strftime('%Y-%m-%d %H:%M'))"
    ```
    
* **What to look for:**
    
    * **UTC** time may be a different day than your local time, especially at night.
        



##### **2. Run CLI Command for Default (UTC) “Today”**

* **Why:** This tests that the CLI is UTC by default.
    
* **How:**
    
    ```bash
    python -m obk trace-id
    ```
    
* **What to look for:**
    
    * The output date (`YYYYMMDDT...`) should match the **current UTC date**.
        



##### **3. Run CLI Command with Local Timezone Override**

* **Why:** To confirm the `--timezone` flag produces local date output.
    
* **How:**
    
    ```bash
    python -m obk trace-id --timezone America/New_York
    ```
    
* **What to look for:**
    
    * The output date (`YYYYMMDDT...`) should match the **current local date in New York**.
        



##### **4. Run “Today” Folder Commands and Check Date Folders**

* **Why:** To verify that the reported folder path aligns with the correct date in both UTC and local time.
    
* **How:**
    
    ```bash
    python -m obk validate-today
    python -m obk validate-today --timezone America/New_York
    python -m obk harmonize-today --dry-run
    python -m obk harmonize-today --dry-run --timezone America/New_York
    ```
    
* **What to look for:**
    
    * The folder reported should be:
        
        * **UTC:** `.../prompts/YYYY/MM/DD` (matches UTC date)
            
        * **New York:** `.../prompts/YYYY/MM/DD` (matches NY local date)
            
    * Confirm that each “today” command reports the **same date/folder** as `trace-id` for the corresponding timezone.
        



##### **5. Compare and Log Results**

* **Why:** Final check that all commands are consistent and match your expectations.
    
* **How:**
    
    * Copy the date segments or folder paths from each output.
        
    * Visually confirm:
        
        * All UTC outputs are the same date/folder.
            
        * All `America/New_York` outputs are the same date/folder.
            
        * The two timezones may differ by one day (if you’re running late at night).
            



##### **6. [Optional] Edge Cases**

* **Try with “exotic” timezones:**
    
    ```bash
    python -m obk trace-id --timezone Pacific/Kiritimati
    ```
    
* **What to look for:**
    
    * Output should reflect the correct day in the specified exotic timezone.
        



#### **Summary Table**

| Step | Command | What Should Happen |
| --- | --- | --- |
| 1 | See above (Python oneliner) | Shows current UTC and Local time |
| 2 | `python -m obk trace-id` | Outputs UTC date |
| 3 | `python -m obk trace-id --timezone America/New_York` | Outputs NY date (may differ from UTC at night) |
| 4 | `validate-today`, `harmonize-today` (both UTC and NY) | Folder paths use correct date for UTC or NY |
| 5 | Compare outputs | UTC outputs match each other, NY outputs match each |
| 6 | `--timezone Pacific/Kiritimati` (optional) | Correct date for exotic timezones |

* * *

</gsl-description>
</gsl-workflows>
<gsl-acceptance-tests>
<gsl-title>

## 5. Acceptance Tests
</gsl-title>

<gsl-acceptance-test id="1">
<gsl-performed-action>

1. When I run `obk trace-id`, `obk validate-today`, and `obk harmonize-today` with no timezone flag
</gsl-performed-action>
<gsl-expected-result>

    All commands use UTC as the default timezone. The reported date or folder matches the current UTC day, and is the same across all three commands.
</gsl-expected-result>
</gsl-acceptance-test>

<gsl-acceptance-test id="2">
<gsl-performed-action>

2. When I run `obk trace-id --timezone America/New_York`, `obk validate-today --timezone America/New_York`, and `obk harmonize-today --timezone America/New_York`
</gsl-performed-action>
<gsl-expected-result>
    
    The reported date and/or folder for all commands reflects the current day in the specified timezone and matches across all three commands.
</gsl-expected-result>
</gsl-acceptance-test>

<gsl-acceptance-test id="3">
<gsl-performed-action>

3. When I run any of the above commands with a rare or DST-changing timezone (e.g., `Pacific/Kiritimati` or at the moment DST shifts)
</gsl-performed-action>
<gsl-expected-result>

    The reported date and folder accurately reflect the day in the chosen timezone, handling DST and “exotic” offsets correctly, with no ambiguity or mismatch.
</gsl-expected-result>
</gsl-acceptance-test>

<gsl-acceptance-test id="4">
<gsl-performed-action>

4. When I inspect the help output for `obk trace-id`, `validate-today`, and `harmonize-today`
</gsl-performed-action>
<gsl-expected-result>

    Each help screen documents that `--timezone` is supported and that UTC is the default.
</gsl-expected-result>
</gsl-acceptance-test>
</gsl-acceptance-tests>

</gsl-block>
</gsl-prompt>
