docs: add v1.1.0 frontmatter enhancements and modular spec

.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
           node-version: "20"
 
       - name: Install semantic-release
-        run: npm install -g semantic-release @semantic-release/changelog @semantic-release/git
+        run: npm install -g semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/exec conventional-changelog-conventionalcommits
 
       - name: Run semantic-release
         env:

.releaserc.json

@@ -1,18 +1,37 @@
 {
   "branches": ["main"],
   "plugins": [
-    "@semantic-release/commit-analyzer",
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          { "type": "docs", "release": "minor" },
+          { "type": "fix", "release": "patch" },
+          { "type": "refactor", "release": "patch" },
+          { "type": "style", "release": "patch" },
+          { "type": "perf", "release": "patch" },
+          { "type": "chore", "release": false }
+        ]
+      }
+    ],
     "@semantic-release/release-notes-generator",
     [
       "@semantic-release/changelog",
       {
         "changelogFile": "CHANGELOG.md"
       }
     ],
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "sed -i 's/\\*\\*Version:\\*\\* [0-9]*\\.[0-9]*\\.[0-9]*/\\*\\*Version:\\*\\* ${nextRelease.version}/' docs/specification.md && sed -i 's/Draft v[0-9]*\\.[0-9]*\\.[0-9]*/Draft v${nextRelease.version}/g' README.md AGENTS.md"
+      }
+    ],
     [
       "@semantic-release/git",
       {
-        "assets": ["CHANGELOG.md"],
+        "assets": ["CHANGELOG.md", "docs/specification.md", "README.md", "AGENTS.md"],
         "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
       }
     ],

AGENTS.md

@@ -149,6 +149,23 @@ taskmark-spec/
 
 **Invalid Date Handling:** Warn at `file:line`, ignore field, continue parsing
 
+### YAML Front Matter
+
+**Supported Fields:**
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `locale` | Natural language date parsing + default output format | `en_US`, `fr_FR` |
+| `timezone` | Default timezone for dates without explicit timezone | `America/New_York`, `UTC` |
+| `date_format` | Output date format (strftime), overrides locale | `%Y-%m-%d`, `%d/%m/%Y` |
+
+**File Scope Rules:**
+
+- Front matter applies ONLY to the current file
+- Linked files retain their own front matter
+- No inheritance of front matter between files
+- Default: system locale/timezone, ISO 8601 output (`YYYY-MM-DD`)
+
 ### Section Headers and Inheritance
 
 ```markdown

TODO.md

@@ -2,25 +2,6 @@
 
 Project roadmap and tasks for the TaskMark specification.
 
-## v1.1.0 - Frontmatter Enhancements +taskmark-spec/v1.1.0 #documentation
-
-### Locale and Date Handling
-
-- [ ] Document `locale` frontmatter field ~2h
-  - Used for parsing natural language dates and recurrence patterns
-  - When set (without `date_format`), output uses locale's default date format instead of ISO
-- [ ] Document `date_format` frontmatter field ~1h
-  - Accepts strftime patterns (e.g., `%d/%m/%Y`)
-  - Overrides locale default format when both are set
-- [ ] Document that default output format is ISO 8601 (`YYYY-MM-DD`) when no locale/date_format set ~30m
-
-### File-Scoped Frontmatter
-
-- [ ] Document that `timezone` only applies to the current file ~30m
-- [ ] Document that `locale` only applies to the current file ~30m
-- [ ] Document that `date_format` only applies to the current file ~30m
-- [ ] Document that imported files retain their own frontmatter settings ~1h
-
 ## v1.2.0 - Documentation Updates +taskmark-spec/v1.2.0 #documentation
 
 - [ ] Document `@user` assignees in headers for inheritance ~1h

docs/spec/compatibility.md

@@ -0,0 +1,119 @@
+# Format Compatibility
+
+Conversion rules between TaskMark and other task formats. See [specification.md](../specification.md) for the core spec.
+
+---
+
+## todo.txt Conversion
+
+| Element | todo.txt | TaskMark | Conversion Rule |
+|---------|----------|---------|----------------|
+| Priority | `(A)` at start | `(A)` after state | Move after `- [ ]` |
+| Contexts | `@context` | `#context` | Replace `@` with `#` |
+| Projects | `+project` | `+project` | No change |
+| Assignees | Not supported | `@user` | Add if needed |
+| Dates | Creation date required | Optional | Remove if unwanted |
+| Sections | Not supported | `## Section` | Group by project |
+
+### Example Conversion
+
+**todo.txt:**
+
+```
+(A) 2024-03-10 Call client +Sales @phone due:2024-03-15
+x 2024-03-05 2024-03-01 Complete report +Reports
+```
+
+**TaskMark:**
+
+```markdown
+# TODO
+
+## Sales
+- [ ] (A) 2024-03-10 Call client +Sales #phone due:2024-03-15
+
+## Reports
+- [x] 2024-03-01 2024-03-05 Complete report +Reports
+```
+
+---
+
+## todo.md Conversion
+
+| Element | todo.md | TaskMark | Conversion Rule |
+|---------|---------|---------|----------------|
+| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed |
+| Priority | Not standardized | `(value)` after state | Add if needed |
+| Metadata | Freeform | `key:value` | Standardize format |
+| Recurrence | Not supported | `repeat:PATTERN` | Add if needed |
+| File links | Not supported | `[text](file.md)` | Add if needed |
+
+### Example Conversion
+
+**todo.md:**
+
+```markdown
+# Tasks
+
+- [ ] Important task
+- [x] Completed task
+- [-] Cancelled task
+```
+
+**TaskMark:**
+
+```markdown
+# TODO
+
+## Tasks
+- [ ] (A) Important task
+- [x] Completed task
+- [-] Cancelled task
+```
+
+---
+
+## xit Conversion
+
+| Element | xit | TaskMark | Conversion Rule |
+|---------|-----|---------|----------------|
+| Date headers | `2024-03-15` | `## Section` | Convert to sections |
+| States | `[ ]`, `[x]`, `[-]` | `[ ]`, `[x]`, `[-]`, `[!]` | Add `[!]` if needed |
+| Metadata | `key:value` | `key:value` | Extract core fields |
+| Priority | Not supported | `(value)` | Add if needed |
+| Projects | `project:name` | `+name` | Convert syntax |
+
+### Example Conversion
+
+**xit:**
+
+```
+2024-03-15
+[ ] Deploy to staging project:Backend
+[x] Write tests project:Backend
+[-] Skip documentation
+```
+
+**TaskMark:**
+
+```markdown
+# TODO
+
+## 2024-03-15
+- [ ] Deploy to staging +Backend
+- [x] Write tests +Backend
+- [-] Skip documentation
+```
+
+---
+
+## Bidirectional Conversion Notes
+
+| Direction | Data Loss | Notes |
+|-----------|-----------|-------|
+| todo.txt → TaskMark | None | Full compatibility |
+| TaskMark → todo.txt | Sections, blocked state, subtasks | Use project tags for sections |
+| todo.md → TaskMark | None | Full compatibility |
+| TaskMark → todo.md | Priority, metadata, recurrence | Lossy conversion |
+| xit → TaskMark | None | Full compatibility |
+| TaskMark → xit | Sections, assignees | Use date headers |

docs/spec/examples.md

@@ -0,0 +1,138 @@
+# TaskMark Examples
+
+Detailed examples for the TaskMark format. See [specification.md](../specification.md) for the core spec.
+
+---
+
+## Minimal
+
+```markdown
+# TODO
+- [ ] Task
+```
+
+---
+
+## Full Featured
+
+```markdown
+# TODO +Acme #work
+
+## Backend Operations +Backend #critical
+
+- [ ] (A) 2024-03-10 Fix database connection @alice +Database due:2024-03-15T18:00 ~8h type:urgent ticket:ENG-4739 created:2024-03-01T10:00 started:2024-03-10T09:00
+  - [ ] (B) 2024-03-10 Update connection pooling @alice ~2h
+  - [ ] (B) 2024-03-11 Add retry logic @bob ~3h
+  - [x] (C) 2024-03-09 2024-03-10 Write migration @alice ~3h
+
+- [ ] 2024-03-15T09:00 Daily status report @alice repeat:"weekdays at 9am" due:2024-03-15T09:30 ~30m type:report
+```
+
+**After Inheritance:**
+
+- First task: `+Acme/Backend/Database`, `#work`, `#critical`
+- Subtasks: Inherit parent + section + top-level metadata
+- Daily report: `+Acme/Backend`, `#work`, `#critical`
+
+---
+
+## Date and Time Examples
+
+```markdown
+# TODO +MyProject
+
+## Date-only
+- [ ] (A) 2024-03-10 Start project planning
+- [x] (B) 2024-03-01 2024-03-05 Complete requirements
+
+## Time-specific
+- [ ] 2024-03-15T09:00 Morning standup due:2024-03-15T09:30
+- [ ] 2024-03-15T14:00 Client presentation due:2024-03-15T15:00
+
+## With timezones
+- [ ] 2024-03-15T09:00-05:00 Team call (EST)
+- [ ] 2024-03-15T15:00+01:00 European meeting
+
+## Full lifecycle
+- [ ] (A) 2024-03-10T09:00 Implement OAuth2 @alice created:2024-03-01T10:00 started:2024-03-10T09:00 due:2024-03-15T18:00
+
+## Recurring
+- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am"
+- [ ] 2024-04-01 Monthly review repeat:"first day of month"
+```
+
+**Result:** All tasks inherit `+MyProject` from top-level section.
+
+---
+
+## YAML Front Matter
+
+```markdown
+---
+locale: en_US
+timezone: America/New_York
+---
+
+# TODO
+
+## Meetings
+- [ ] 2024-03-18T09:00 Weekly standup repeat:"every monday at 9am"
+- [ ] 2024-04-01 Monthly review repeat:"first day of month"
+
+## Tasks
+- [ ] (A) 2024-03-10 Start development @alice due:2024-03-15T17:00
+```
+
+**Result:** All datetimes without explicit timezone use `America/New_York` (EST/EDT).
+
+---
+
+## Custom Date Format
+
+```markdown
+---
+locale: en_GB
+date_format: "%d/%m/%Y"
+timezone: Europe/London
+---
+
+# TODO
+
+- [ ] 10/03/2024 Project kickoff @alice
+- [x] 01/03/2024 05/03/2024 Complete requirements @bob
+```
+
+**Result:** Dates are output in day/month/year format. The `date_format` overrides the locale default.
+
+---
+
+## Multi-File with Different Front Matter
+
+**main.md:**
+
+```markdown
+---
+timezone: America/New_York
+date_format: "%Y-%m-%d"
+---
+
+# TODO +Project
+
+## Engineering +Engineering
+[UK Team](uk-team.md)
+```
+
+**uk-team.md:**
+
+```markdown
+---
+timezone: Europe/London
+date_format: "%d/%m/%Y"
+---
+
+# UK Team Tasks
+
+- [ ] 15/03/2024 Sprint planning @alice
+```
+
+**Result:** Each file uses its own front matter. The UK team file displays dates in `dd/mm/yyyy` format with London timezone, independent of the parent file's settings.