spec: define AcceptanceCriteria and Acceptance fields on issues

AGENTS.md

@@ -53,11 +53,11 @@ transition commits manually.
 todo create --type feature --title "Title" --plan "Description"
 
 # Start work (must be on develop)
-todo start <id> --plan "Planned approach"
+todo start <id> --acceptance-criteria "What must be true for this to be done"
 # Then create the branch: git checkout -b <type>/<id>
 
 # Complete work (must be on <type>/<id>)
-todo done <id> --summary "What was delivered"
+todo done <id> --acceptance "What was delivered against the criteria"
 
 # Hold or cancel
 todo hold <id> --reason "Why"

src/README.rst

@@ -267,6 +267,10 @@ The following fields MUST appear in exactly this order::
     DueEnd: <YYYY-MM-DD>             # OPTIONAL
     Description: <first line>
                  <continuation lines>
+    AcceptanceCriteria: <first line>  # OPTIONAL, set at in-progress
+                        <continuation lines>
+    Acceptance: <first line>          # OPTIONAL, set at done
+                <continuation lines>
 
 Field Semantics
 ---------------
@@ -298,6 +302,20 @@ Field Semantics
 * **DueStart / DueEnd**:
   * Optional.
   * If only one is present, the other is implicitly equal to it.
+* **AcceptanceCriteria**:
+  * Optional. Set when transitioning to ``in-progress``.
+  * Defines what must be true for the issue to be considered done.
+  * Follows the same indentation rules as ``Description``.
+  * ``AcceptanceCriteria:`` occupies 20 characters. Content begins at column 21.
+  * Continuation lines MUST be indented with 20 spaces.
+  * Immutable after being set.
+* **Acceptance**:
+  * Optional. Set when transitioning to ``done``.
+  * Records what was delivered against the acceptance criteria.
+  * Follows the same indentation rules as ``Description``.
+  * ``Acceptance:`` occupies 12 characters. Content begins at column 13.
+  * Continuation lines MUST be indented with 12 spaces.
+  * Immutable after being set.
 
 Description Block
 -----------------
@@ -324,6 +342,8 @@ the scope of an issue, the issue MUST be cancelled and a new issue created.
 Fields that MAY change after creation:
 
 * ``Status`` (via transition commits)
+* ``AcceptanceCriteria`` (set once at ``in-progress`` transition, immutable after)
+* ``Acceptance`` (set once at ``done`` transition, immutable after)
 
 Fields that MUST NOT change after creation:
 
@@ -421,14 +441,20 @@ Transition Details
 **``todo(<ID>): in-progress``** — Start work.
 
 * Branch: MUST be on ``develop``.
-* Body: high-level description of the planned approach.
+* Body: the acceptance criteria for the issue.
+* The ``AcceptanceCriteria`` field on the issue is set from the body of
+  this commit. It defines what must be true for the issue to be considered
+  done.
 * After this commit, the issue branch ``<Type>/<ID>`` may be created from
   ``develop``.
 
 **``todo(<ID>): done``** — Complete work.
 
 * Branch: MUST be on ``<Type>/<ID>``.
-* Body: high-level summary of what was delivered.
+* Body: acceptance statement — what was delivered against the acceptance
+  criteria.
+* The ``Acceptance`` field on the issue is set from the body of this
+  commit.
 * After this commit, the issue branch may be merged into ``develop`` using
   ``--no-ff``.
 
@@ -596,19 +622,22 @@ has no body because the description is already recorded in the issue itself.
 
 Starting work (MUST be on ``develop``)::
 
-    todo start <id> --plan "High-level approach description"
+    todo start <id> --acceptance-criteria "What must be true for this to be done"
 
-This produces a ``todo(<ID>): in-progress`` commit. The issue branch
+This produces a ``todo(<ID>): in-progress`` commit. The
+``--acceptance-criteria`` text is stored in the issue's
+``AcceptanceCriteria`` field and becomes the commit body. The issue branch
 ``<Type>/<ID>`` may then be created by the user::
 
     git checkout -b feature/<id>
 
 Completing work (MUST be on ``<Type>/<ID>``)::
 
-    todo done <id> --summary "Summary of what was delivered"
+    todo done <id> --acceptance "What was delivered against the criteria"
 
-This produces a ``todo(<ID>): done`` commit. The issue branch may then be
-merged into ``develop`` using ``--no-ff``.
+This produces a ``todo(<ID>): done`` commit. The ``--acceptance`` text is
+stored in the issue's ``Acceptance`` field and becomes the commit body.
+The issue branch may then be merged into ``develop`` using ``--no-ff``.
 
 Holding an issue (MUST be on ``<Type>/<ID>``)::