:PROPERTIES:
:ID:       5595bf4a-9b59-420a-9f27-92bf96950b3a
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: org-gtd v4.0 Migration
#+DATE: 2026-03-30
#+FILETAGS: :emacs:gtd:org-gtd:architecture:
#+STARTUP: content

* Overview
The `org-gtd` package has been upgraded to version 4.0, representing a shift from a linear list-based task manager to a Directed Acyclic Graph (DAG) of dependencies. This architecture allows for more complex, automated workflows within the [[file:personal-software-foundry.org][Personal Software Foundry (PSF)]].

* Key Changes in v4.0

** 1. Mandatory Single Sequence
Keywords must now follow a single sequence in `org-todo-keywords`.
- *Previous:* Multiple sequences for `TODO/NEXT` and `WAIT/CNCL`.
- *New:* `(sequence "TODO(t)" "NEXT(n)" "WAIT(w@/!)" "|" "DONE(d!)" "CNCL(c@)")`.

** 2. Explicit Keyword Mapping
v4.0 requires an explicit mapping of keywords to their semantic meanings via `org-gtd-keyword-mapping`.

** 3. org-edna Integration
Dependency tracking is now natively handled by `org-edna`. Task transitions are automated via `:TRIGGER:` and `:BLOCKER:` properties, which is the mechanism used by the PSF to enforce "Safety Gates."

** 4. Custom Node Paths
Projects are no longer restricted to a single file. v4.0 uses `org-gtd-custom-node-paths` to identify where actionable and incubated items reside across the [[file:modular-emacs-configuration.org][modular folder structure]].

* PSF Integration
The PSF utilizes `org-gtd` v4.0 as its "shadow orchestration layer."
- `:PSF-STATE:` property in `gtd.org` tracks engineering progress.
- `org-edna` triggers automatically move the "Engineering State" forward as each PSF role (Architect, Coder, QA) finishes its task.

* Upgrade Process
To complete the migration:
1. Restart Emacs to load the modular `emacs-gtd.el`.
2. Execute `M-x org-gtd-upgrade-v3-to-v4`.
3. Verify that existing items are correctly identified in the new DAG.

* See Also
- [[file:modular-emacs-configuration.org][Modular Emacs Configuration]]
- [[file:personal-software-foundry.org][Personal Software Foundry (PSF)]]