4 files changed, 210 insertions, 14 deletions
diff --git a/.ai/scripts/lint-org.el b/.ai/scripts/lint-org.el
index 1bd4582..928f83b 100644
--- a/.ai/scripts/lint-org.el
+++ b/.ai/scripts/lint-org.el
@@ -76,6 +76,18 @@ The CLI defaults this to t (a linter reports, it doesn't write);
 `--fix' is what enables writes on a command-line run.")
 (defvar lo-current-file nil
   "Path of the file currently being processed.")
+
+(defun lo--spec-file-p ()
+  "Non-nil when the current file lives under a docs/specs/ directory.
+The four todo-format-family checkers encode todo.org completion conventions
+and misfire on a spec: a spec's Decisions section legitimately carries a
+level-2 DONE with no CLOSED cookie, and its review-history section carries
+level-2 dated headings.  docs/specs/ is the canonical spec home per the
+docs-lifecycle rule, so a path segment match is the scope test.  Link,
+table, and structural checks still run on specs — only the todo-format
+family is scoped out."
+  (and lo-current-file
+       (string-match-p "/docs/specs/" (expand-file-name lo-current-file))))
 (defvar lo-followups-file nil
   "When non-nil, after a non-check run any judgment items are appended to this
 path as an org section dated today.  The file is created if missing.")
@@ -657,16 +669,22 @@ left unmodified and mechanical entries are recorded with :preview t."
           ;; After org-lint items: the custom table-standard scan. Runs on the
           ;; post-fix buffer; judgment-only, so order doesn't perturb fixes.
           (lo--check-tables)
-          ;; Same shape: flag level-2 dated headers (completion defects).
-          (lo--check-level2-dated-headers)
-          ;; Structural heading defects org-lint doesn't cover.
+          ;; Structural heading defects org-lint doesn't cover. These run on
+          ;; every org file, specs included.
           (lo--check-indented-headings)
           (lo--check-empty-headings)
           (lo--check-malformed-priority-cookies)
-          (lo--check-level2-done-without-closed)
-          (lo--check-task-missing-last-reviewed)
-          (lo--check-subtask-done-not-dated)
-          (lo--check-dated-log-active-timestamp)
+          ;; The todo-format family encodes todo.org completion conventions and
+          ;; misfires on a spec (a Decisions section's undated DONE, a
+          ;; review-history dated heading, a phases task with no LAST_REVIEWED).
+          ;; Scope them out of docs/specs/; link, table, and structural checks
+          ;; above still run there.
+          (unless (lo--spec-file-p)
+            (lo--check-level2-dated-headers)
+            (lo--check-level2-done-without-closed)
+            (lo--check-task-missing-last-reviewed)
+            (lo--check-subtask-done-not-dated)
+            (lo--check-dated-log-active-timestamp))
           (when (and (not lo-check-only) (buffer-modified-p))
             (save-buffer)))
       (with-current-buffer buf (set-buffer-modified-p nil))
diff --git a/.ai/scripts/tests/test-lint-org.el b/.ai/scripts/tests/test-lint-org.el
index 9a72bef..d398c4c 100644
--- a/.ai/scripts/tests/test-lint-org.el
+++ b/.ai/scripts/tests/test-lint-org.el
@@ -910,3 +910,83 @@ heading, so it is not flagged — only two-or-more indented stars are."
   (let* ((out (lo-test--run "* Open Work\n** VERIFY [#B] Waiting on Craig\n"))
          (js (lo-test--judgments (plist-get out :issues))))
     (should (memq 'task-missing-last-reviewed (lo-test--checkers js)))))
+
+;;; ---------------------------------------------------------------------------
+;;; todo-format checkers skip docs/specs/ files (claude-rules/todo-format.md)
+;;
+;; The four todo-format-family checkers encode todo.org completion conventions.
+;; A spec legitimately uses ** DONE <decision> with no CLOSED cookie and
+;; ** <dated> — <who> review-history headings, so those checkers misfire on
+;; every spec. They must skip any file under a docs/specs/ path segment.
+
+(defun lo-test--run-at (relpath content)
+  "Write CONTENT to <tmpdir>/RELPATH, run lint on it, return :issues.
+RELPATH is a relative path (may contain slashes) so a docs/specs/ segment
+can be exercised — the checkers key on the file's path, not just its name."
+  (let* ((root (make-temp-file "lo-test-root-" t))
+         (file (expand-file-name relpath root)))
+    (make-directory (file-name-directory file) t)
+    (unwind-protect
+        (progn
+          (with-temp-file file (insert content))
+          (lo-test--reset)
+          (lo-process-file file)
+          (prog1 (list :issues lo-issues)
+            (lo-test--drop-buffer file)))
+      (delete-directory root t))))
+
+(defconst lo-test--spec-decisions
+  "* Decisions [1/1]\n** DONE Some decision\n- Context: x\n"
+  "A spec Decisions section: a level-2 DONE with no CLOSED cookie.")
+
+(defconst lo-test--spec-history
+  "* Review history\n** 2026-07-14 Tue @ 02:03:28 -0500 — Claude — responder\n- What: x\n"
+  "A spec review-history section: a level-2 dated header.")
+
+(ert-deftest lo-todo-checkers-fire-on-a-normal-org-file ()
+  "Baseline: the checkers DO fire on a non-spec path (the bug is scope, not silence)."
+  (let* ((out (lo-test--run-at "todo.org" lo-test--spec-decisions))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should (memq 'level2-done-without-closed cs))))
+
+(ert-deftest lo-level2-done-without-closed-skips-specs ()
+  (let* ((out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" lo-test--spec-decisions))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'level2-done-without-closed cs))))
+
+(ert-deftest lo-level2-dated-header-skips-specs ()
+  (let* ((out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" lo-test--spec-history))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'level-2-dated-header cs))))
+
+(ert-deftest lo-dated-log-active-timestamp-skips-specs ()
+  (let* ((c "* History\n** 2026-07-14 Tue @ 02:03:28 -0500 — did a thing\nSCHEDULED: <2026-07-20 Mon>\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'dated-log-heading-active-timestamp cs))))
+
+(ert-deftest lo-subtask-done-not-dated-skips-specs ()
+  (let* ((c "* Work\n** TODO Parent\n*** DONE A sub-decision\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'subtask-done-not-dated cs))))
+
+(ert-deftest lo-link-checks-still-fire-on-specs ()
+  "Only the todo-format family is scoped out; a broken link in a spec still flags."
+  (let* ((c "* X\n[[file:does-not-exist-xyz.org][link]]\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should (memq 'link-to-local-file cs))))
+
+(ert-deftest lo-task-missing-last-reviewed-skips-specs ()
+  "The fifth todo-format checker (added 2026-07-23) skips specs too — a spec's
+phases section may carry ** TODO [#x] items that aren't backlog tasks."
+  (let* ((c "* Implementation phases\n** TODO [#B] Phase one\nBody.\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'task-missing-last-reviewed cs)))
+  ;; And still fires on a normal file.
+  (let* ((c "* Work\n** TODO [#B] Real backlog task\nBody.\n")
+         (out (lo-test--run-at "todo.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should (memq 'task-missing-last-reviewed cs))))
diff --git a/claude-templates/.ai/scripts/lint-org.el b/claude-templates/.ai/scripts/lint-org.el
index 1bd4582..928f83b 100644
--- a/claude-templates/.ai/scripts/lint-org.el
+++ b/claude-templates/.ai/scripts/lint-org.el
@@ -76,6 +76,18 @@ The CLI defaults this to t (a linter reports, it doesn't write);
 `--fix' is what enables writes on a command-line run.")
 (defvar lo-current-file nil
   "Path of the file currently being processed.")
+
+(defun lo--spec-file-p ()
+  "Non-nil when the current file lives under a docs/specs/ directory.
+The four todo-format-family checkers encode todo.org completion conventions
+and misfire on a spec: a spec's Decisions section legitimately carries a
+level-2 DONE with no CLOSED cookie, and its review-history section carries
+level-2 dated headings.  docs/specs/ is the canonical spec home per the
+docs-lifecycle rule, so a path segment match is the scope test.  Link,
+table, and structural checks still run on specs — only the todo-format
+family is scoped out."
+  (and lo-current-file
+       (string-match-p "/docs/specs/" (expand-file-name lo-current-file))))
 (defvar lo-followups-file nil
   "When non-nil, after a non-check run any judgment items are appended to this
 path as an org section dated today.  The file is created if missing.")
@@ -657,16 +669,22 @@ left unmodified and mechanical entries are recorded with :preview t."
           ;; After org-lint items: the custom table-standard scan. Runs on the
           ;; post-fix buffer; judgment-only, so order doesn't perturb fixes.
           (lo--check-tables)
-          ;; Same shape: flag level-2 dated headers (completion defects).
-          (lo--check-level2-dated-headers)
-          ;; Structural heading defects org-lint doesn't cover.
+          ;; Structural heading defects org-lint doesn't cover. These run on
+          ;; every org file, specs included.
           (lo--check-indented-headings)
           (lo--check-empty-headings)
           (lo--check-malformed-priority-cookies)
-          (lo--check-level2-done-without-closed)
-          (lo--check-task-missing-last-reviewed)
-          (lo--check-subtask-done-not-dated)
-          (lo--check-dated-log-active-timestamp)
+          ;; The todo-format family encodes todo.org completion conventions and
+          ;; misfires on a spec (a Decisions section's undated DONE, a
+          ;; review-history dated heading, a phases task with no LAST_REVIEWED).
+          ;; Scope them out of docs/specs/; link, table, and structural checks
+          ;; above still run there.
+          (unless (lo--spec-file-p)
+            (lo--check-level2-dated-headers)
+            (lo--check-level2-done-without-closed)
+            (lo--check-task-missing-last-reviewed)
+            (lo--check-subtask-done-not-dated)
+            (lo--check-dated-log-active-timestamp))
           (when (and (not lo-check-only) (buffer-modified-p))
             (save-buffer)))
       (with-current-buffer buf (set-buffer-modified-p nil))
diff --git a/claude-templates/.ai/scripts/tests/test-lint-org.el b/claude-templates/.ai/scripts/tests/test-lint-org.el
index 9a72bef..d398c4c 100644
--- a/claude-templates/.ai/scripts/tests/test-lint-org.el
+++ b/claude-templates/.ai/scripts/tests/test-lint-org.el
@@ -910,3 +910,83 @@ heading, so it is not flagged — only two-or-more indented stars are."
   (let* ((out (lo-test--run "* Open Work\n** VERIFY [#B] Waiting on Craig\n"))
          (js (lo-test--judgments (plist-get out :issues))))
     (should (memq 'task-missing-last-reviewed (lo-test--checkers js)))))
+
+;;; ---------------------------------------------------------------------------
+;;; todo-format checkers skip docs/specs/ files (claude-rules/todo-format.md)
+;;
+;; The four todo-format-family checkers encode todo.org completion conventions.
+;; A spec legitimately uses ** DONE <decision> with no CLOSED cookie and
+;; ** <dated> — <who> review-history headings, so those checkers misfire on
+;; every spec. They must skip any file under a docs/specs/ path segment.
+
+(defun lo-test--run-at (relpath content)
+  "Write CONTENT to <tmpdir>/RELPATH, run lint on it, return :issues.
+RELPATH is a relative path (may contain slashes) so a docs/specs/ segment
+can be exercised — the checkers key on the file's path, not just its name."
+  (let* ((root (make-temp-file "lo-test-root-" t))
+         (file (expand-file-name relpath root)))
+    (make-directory (file-name-directory file) t)
+    (unwind-protect
+        (progn
+          (with-temp-file file (insert content))
+          (lo-test--reset)
+          (lo-process-file file)
+          (prog1 (list :issues lo-issues)
+            (lo-test--drop-buffer file)))
+      (delete-directory root t))))
+
+(defconst lo-test--spec-decisions
+  "* Decisions [1/1]\n** DONE Some decision\n- Context: x\n"
+  "A spec Decisions section: a level-2 DONE with no CLOSED cookie.")
+
+(defconst lo-test--spec-history
+  "* Review history\n** 2026-07-14 Tue @ 02:03:28 -0500 — Claude — responder\n- What: x\n"
+  "A spec review-history section: a level-2 dated header.")
+
+(ert-deftest lo-todo-checkers-fire-on-a-normal-org-file ()
+  "Baseline: the checkers DO fire on a non-spec path (the bug is scope, not silence)."
+  (let* ((out (lo-test--run-at "todo.org" lo-test--spec-decisions))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should (memq 'level2-done-without-closed cs))))
+
+(ert-deftest lo-level2-done-without-closed-skips-specs ()
+  (let* ((out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" lo-test--spec-decisions))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'level2-done-without-closed cs))))
+
+(ert-deftest lo-level2-dated-header-skips-specs ()
+  (let* ((out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" lo-test--spec-history))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'level-2-dated-header cs))))
+
+(ert-deftest lo-dated-log-active-timestamp-skips-specs ()
+  (let* ((c "* History\n** 2026-07-14 Tue @ 02:03:28 -0500 — did a thing\nSCHEDULED: <2026-07-20 Mon>\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'dated-log-heading-active-timestamp cs))))
+
+(ert-deftest lo-subtask-done-not-dated-skips-specs ()
+  (let* ((c "* Work\n** TODO Parent\n*** DONE A sub-decision\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'subtask-done-not-dated cs))))
+
+(ert-deftest lo-link-checks-still-fire-on-specs ()
+  "Only the todo-format family is scoped out; a broken link in a spec still flags."
+  (let* ((c "* X\n[[file:does-not-exist-xyz.org][link]]\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should (memq 'link-to-local-file cs))))
+
+(ert-deftest lo-task-missing-last-reviewed-skips-specs ()
+  "The fifth todo-format checker (added 2026-07-23) skips specs too — a spec's
+phases section may carry ** TODO [#x] items that aren't backlog tasks."
+  (let* ((c "* Implementation phases\n** TODO [#B] Phase one\nBody.\n")
+         (out (lo-test--run-at "docs/specs/2026-07-14-x-spec.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should-not (memq 'task-missing-last-reviewed cs)))
+  ;; And still fires on a normal file.
+  (let* ((c "* Work\n** TODO [#B] Real backlog task\nBody.\n")
+         (out (lo-test--run-at "todo.org" c))
+         (cs (lo-test--checkers (lo-test--judgments (plist-get out :issues)))))
+    (should (memq 'task-missing-last-reviewed cs))))