fix(todo-db): cover hosted export key parity

.github/path-filters.yml

@@ -100,7 +100,7 @@ code-ci:
 
 # Packaging-metadata changes: build/install/audit signal (package-smoke,
 # dependency-audit jobs in pr.yml) only needs to run when one of these
-# changed. See _project/TODO/main/planning/pr-gate-package-and-audit-promotion.yaml.
+# changed. See tracker item `pr-gate-package-and-audit-promotion`.
 packaging:
   - "pyproject.toml"
   - "MANIFEST.in"
@@ -111,7 +111,7 @@ packaging:
 
 # Results-explorer visualization / CLI<->explorer parity source changes:
 # gates the parity-check job in pr.yml. See
-# _project/TODO/main/planning/parity-check-develop-ring.yaml.
+# tracker item `parity-check-develop-ring`.
 viz:
   - "results-explorer/**"
   - "tests/parity/**"

.github/workflows/develop-post-merge.yml

@@ -170,7 +170,7 @@ jobs:
     # no CI consumer before this job - it only ran when a developer invoked it
     # locally. Measured locally at ~18 minutes (2 xdist workers), too slow for
     # the develop-PR-blocking lane, so it lands here for visibility/metrics.
-    # See _project/TODO/main/planning/medium-tier-ci-home.yaml.
+    # See tracker item `medium-tier-ci-home`.
     #
     # PROMOTED 2026-07-06 (medium-tier-red-disposition-and-promotion): the
     # tier ran clean (green) on the real runner - develop-post-merge run

.github/workflows/nightly.yml

@@ -131,7 +131,7 @@ jobs:
       # Keep empty unless triage is documented in the TODO item.
       # PYSEC-2026-87 (lxml): redshift-connector==2.1.13 pins lxml<=6.0.2, so
       # the fixed lxml 6.1.0 can't be resolved until upstream relaxes that
-      # bound. See _project/TODO/main/planning/lxml-cve-pysec-2026-87-blocked-by-redshift-connector.yaml
+      # bound. See tracker item `lxml-cve-pysec-2026-87-blocked-by-redshift-connector`.
       PIP_AUDIT_IGNORE_VULNS: "PYSEC-2026-87"
     steps:
       - name: Checkout code

.github/workflows/pr.yml

@@ -817,7 +817,7 @@ jobs:
       # Keep empty unless triage is documented in the TODO item.
       # PYSEC-2026-87 (lxml): redshift-connector==2.1.13 pins lxml<=6.0.2, so
       # the fixed lxml 6.1.0 can't be resolved until upstream relaxes that
-      # bound. See _project/TODO/main/planning/lxml-cve-pysec-2026-87-blocked-by-redshift-connector.yaml
+      # bound. See tracker item `lxml-cve-pysec-2026-87-blocked-by-redshift-connector`.
       PIP_AUDIT_IGNORE_VULNS: "PYSEC-2026-87"
     steps:
       - name: Checkout code
@@ -853,7 +853,7 @@ jobs:
     name: parity-check
     needs: ci-paths
     # Path-filtered on results-explorer/viz source changes (see
-    # _project/DONE/main/parity-check-develop-ring.yaml). `make parity-check`
+    # tracker item `parity-check-develop-ring`). `make parity-check`
     # is Python-only (no npm/vitest install), measured at well under a second
     # locally, so it is cheap enough to block develop PRs.
     #

.github/workflows/test.yml

@@ -143,7 +143,7 @@ jobs:
       # Keep empty unless triage is documented in the TODO item.
       # PYSEC-2026-87 (lxml): redshift-connector==2.1.13 pins lxml<=6.0.2, so
       # the fixed lxml 6.1.0 can't be resolved until upstream relaxes that
-      # bound. See _project/TODO/main/planning/lxml-cve-pysec-2026-87-blocked-by-redshift-connector.yaml
+      # bound. See tracker item `lxml-cve-pysec-2026-87-blocked-by-redshift-connector`.
       PIP_AUDIT_IGNORE_VULNS: "PYSEC-2026-87"
     steps:
       - name: Checkout code

.pre-commit-config.yaml

@@ -127,7 +127,7 @@ repos:
           - --skip=*.pyc,_build,_binaries/*,benchbox/_binaries/*,*.json,*.lock,*.svg,*.min.js,*.min.css,*.csv
           - --quiet-level=2
         stages: [pre-commit]
-        exclude: ^(_sources/|\.claude/skills/)  # vendored sources + tracked skill snapshot; byte-for-byte
+        exclude: ^(_sources/|\.claude/skills/|_project/todo-db-export/)  # vendored/generated snapshots; validate export structure separately
 
   # YAML validation
   - repo: https://github.com/pre-commit/pre-commit-hooks

ANTIGRAVITY.md

@@ -77,10 +77,9 @@ Antigravity can run these without permission:
 - `timeout 60s _binaries/tpc-{h,ds}/<platform>/dsqgen*`
 
 ### TODO Management
-- `uv run _project/scripts/todo_cli.py list|show|stats|ready|next|done|check-graph`
-- `uv run _project/scripts/validate_todo.py*`
-- `uv run _project/scripts/generate_indexes.py` (or `make todo-reindex`)
-- `uv run _project/scripts/migrate_todo_format.py*`
+- `_project/scripts/todo` is the DB-backed tracker entry point; global `--db`/`--actor` flags come before the subcommand.
+- Read: `_project/scripts/todo ready|list|show|stats|deps|lint|export|check-scope`
+- Lifecycle writes: `_project/scripts/todo create|claim|start|done|defer|promote|dismiss|complete|drop|block|unblock|verify`
 
 ### Timing & Audit
 - `uv run _project/scripts/timing_audit.py --report`
@@ -90,13 +89,10 @@ Antigravity can run these without permission:
 - `ps*`, `uname*`, `whoami`, `pwd`, `env | grep*`
 
 ## TODO Workflow
-- Layout: `_project/TODO/{worktree}/{phase}/{item}.yaml`; completed -> `_project/DONE/`.
-- Stable `id` = filename slug.
-- Flat `work[]` with `needs` edges. Inter-item deps: `deps.needs: [slug-ids]`.
-- CLI: `uv run _project/scripts/todo_cli.py list|show|stats|ready|next|done|check-graph`.
-- Indexes are gitignored; `make todo-reindex` to rebuild (also auto-runs on first read).
-- Refer to `TODO_ENTRY_TEMPLATE.yaml` and `TODO_SCHEMA.yaml` for format.
-- Standard format in files: Priority/Status/Description/Files/Solution/Impact.
+- State lives in the shared DB; there is no `_project/TODO` tree. `_project/scripts/todo` is the only write path.
+- `todo claim <id>` prints scope, preserves, anti-patterns, the verification ladder, ready units, and deferrals.
+- Per unit: `todo start ...` (optional) then `todo done ... --evidence ...`; use `todo defer` when skipping; `todo complete ... --pr ...` is gated.
+- `todo export` is the deterministic JSONL/Markdown snapshot; never hand-edit tracker state.
 
 ## CLI Options & Phases
 - **Basic Run**: `benchbox run --platform {plat} --benchmark {bm} --scale {sf}`

GEMINI.md

@@ -77,10 +77,9 @@ Gemini can run these without permission:
 - `timeout 60s _binaries/tpc-{h,ds}/<platform>/dsqgen*`
 
 ### TODO Management
-- `uv run _project/scripts/todo_cli.py list|show|stats|ready|next|done|check-graph`
-- `uv run _project/scripts/validate_todo.py*`
-- `uv run _project/scripts/generate_indexes.py` (or `make todo-reindex`)
-- `uv run _project/scripts/migrate_todo_format.py*`
+- `_project/scripts/todo` is the DB-backed tracker entry point; global `--db`/`--actor` flags come before the subcommand.
+- Read: `_project/scripts/todo ready|list|show|stats|deps|lint|export|check-scope`
+- Lifecycle writes: `_project/scripts/todo create|claim|start|done|defer|promote|dismiss|complete|drop|block|unblock|verify`
 
 ### Timing & Audit
 - `uv run _project/scripts/timing_audit.py --report`
@@ -90,13 +89,10 @@ Gemini can run these without permission:
 - `ps*`, `uname*`, `whoami`, `pwd`, `env | grep*`
 
 ## TODO Workflow
-- Layout: `_project/TODO/{worktree}/{phase}/{item}.yaml`; completed -> `_project/DONE/`.
-- Stable `id` = filename slug.
-- Flat `work[]` with `needs` edges. Inter-item deps: `deps.needs: [slug-ids]`.
-- CLI: `uv run _project/scripts/todo_cli.py list|show|stats|ready|next|done|check-graph`.
-- Indexes are gitignored; `make todo-reindex` to rebuild (also auto-runs on first read).
-- Refer to `TODO_ENTRY_TEMPLATE.yaml` and `TODO_SCHEMA.yaml` for format.
-- Standard format in files: Priority/Status/Description/Files/Solution/Impact.
+- State lives in the shared DB; there is no `_project/TODO` tree. `_project/scripts/todo` is the only write path.
+- `todo claim <id>` prints scope, preserves, anti-patterns, the verification ladder, ready units, and deferrals.
+- Per unit: `todo start ...` (optional) then `todo done ... --evidence ...`; use `todo defer` when skipping; `todo complete ... --pr ...` is gated.
+- `todo export` is the deterministic JSONL/Markdown snapshot; never hand-edit tracker state.
 
 ## CLI Options & Phases
 - **Basic Run**: `benchbox run --platform {plat} --benchmark {bm} --scale {sf}`

Makefile

@@ -683,7 +683,7 @@ lint-site-theme-tokens:
 # unsuperseded analysis files revive the retired mixed-theme contract phrases.
 # Allowlist: inline `allow-stale-theme: <reason>` marker, or a supersession
 # header (Superseded / supersedes / supersession) in `_project/analysis/*`
-# files. `_project/DONE/*` is excluded by design.
+# historical archive files are excluded by design.
 lint-explorer-stale-theme:
 	python3 _project/scripts/scan_explorer_stale_theme.py
 
@@ -1146,9 +1146,9 @@ release-cut:
 	@# Tests that import _project/dev-only tooling or test curated-out surfaces
 	@# cannot collect on the release tree (found by the v0.3.1 release PR CI).
 	git rm -rf --ignore-unmatch tests/unit/scripts/explorer_pipeline tests/unit/explorer
-	git rm -f --ignore-unmatch tests/uat/test_explorer_smoke.py tests/unit/release/test_ruleset_drift_review_coverage.py tests/unit/scripts/test_blind_spot_tools.py tests/unit/scripts/test_build_joinorder_data.py tests/unit/scripts/test_explorer_build_contract.py tests/unit/scripts/test_pr_review_followups.py tests/unit/scripts/test_reference_usage_audit.py tests/unit/scripts/test_scan_explorer_stale_theme.py tests/unit/scripts/test_scan_explorer_tokens.py tests/unit/scripts/test_shrink_rollup.py tests/unit/scripts/test_skill_sync_lock_audit.py tests/unit/scripts/test_submission_workflow_waiver.py tests/unit/scripts/test_validate_todo.py tests/unit/test_agent_write_preflight.py tests/unit/test_auto_merge_soundness_paths.py tests/unit/test_cross_surface_applicability.py tests/unit/test_oracle_coverage_map.py tests/unit/test_ruleset_drift.py tests/unit/test_self_binding_detector.py tests/unit/test_site_header_parity.py tests/unit/test_sync_results_workflow.py tests/unit/test_todo_executable_docs.py tests/unit/core/joinorder/test_canonical_queries.py tests/unit/core/test_platform_labels.py tests/unit/workflows/test_validate_submission_comment_security.py tests/unit/workflows/test_detect_orphaned_commits.py tests/unit/workflows/test_validate_submission_vendor_gate.py
+	git rm -f --ignore-unmatch tests/uat/test_explorer_smoke.py tests/unit/release/test_ruleset_drift_review_coverage.py tests/unit/scripts/test_blind_spot_tools.py tests/unit/scripts/test_build_joinorder_data.py tests/unit/scripts/test_explorer_build_contract.py tests/unit/scripts/test_pr_review_followups.py tests/unit/scripts/test_reference_usage_audit.py tests/unit/scripts/test_scan_explorer_stale_theme.py tests/unit/scripts/test_scan_explorer_tokens.py tests/unit/scripts/test_shrink_rollup.py tests/unit/scripts/test_skill_sync_lock_audit.py tests/unit/scripts/test_submission_workflow_waiver.py tests/unit/test_agent_write_preflight.py tests/unit/test_auto_merge_soundness_paths.py tests/unit/test_cross_surface_applicability.py tests/unit/test_oracle_coverage_map.py tests/unit/test_ruleset_drift.py tests/unit/test_self_binding_detector.py tests/unit/test_site_header_parity.py tests/unit/test_sync_results_workflow.py tests/unit/core/joinorder/test_canonical_queries.py tests/unit/core/test_platform_labels.py tests/unit/workflows/test_validate_submission_comment_security.py tests/unit/workflows/test_detect_orphaned_commits.py tests/unit/workflows/test_validate_submission_vendor_gate.py
 	@# Post-curation guard: every curated path must be gone from the index.
-	@LEFTOVER=$$(git ls-files _project _blog results-data results-explorer .claude .codex .gemini .pre-commit-config.yaml .importlinter todo.config.yaml skill-sync.yaml skill-sync.lock .gitattributes .coveragerc_core .dockerignore .env.example .mcp.json AGENTS.md CLAUDE.md GEMINI.md ANTIGRAVITY.md .github/workflows/results-explorer-browser.yml .github/workflows/seed-corpus.yml .github/workflows/sync-results-data-to-published.yml .github/workflows/validate-submission.yml tests/unit/scripts/explorer_pipeline tests/unit/explorer tests/uat/test_explorer_smoke.py tests/unit/release/test_ruleset_drift_review_coverage.py tests/unit/scripts/test_blind_spot_tools.py tests/unit/scripts/test_build_joinorder_data.py tests/unit/scripts/test_explorer_build_contract.py tests/unit/scripts/test_pr_review_followups.py tests/unit/scripts/test_reference_usage_audit.py tests/unit/scripts/test_scan_explorer_stale_theme.py tests/unit/scripts/test_scan_explorer_tokens.py tests/unit/scripts/test_shrink_rollup.py tests/unit/scripts/test_skill_sync_lock_audit.py tests/unit/scripts/test_submission_workflow_waiver.py tests/unit/scripts/test_validate_todo.py tests/unit/test_agent_write_preflight.py tests/unit/test_auto_merge_soundness_paths.py tests/unit/test_cross_surface_applicability.py tests/unit/test_oracle_coverage_map.py tests/unit/test_ruleset_drift.py tests/unit/test_self_binding_detector.py tests/unit/test_site_header_parity.py tests/unit/test_sync_results_workflow.py tests/unit/test_todo_executable_docs.py tests/unit/core/joinorder/test_canonical_queries.py tests/unit/core/test_platform_labels.py tests/unit/workflows/test_validate_submission_comment_security.py tests/unit/workflows/test_detect_orphaned_commits.py tests/unit/workflows/test_validate_submission_vendor_gate.py); \
+	@LEFTOVER=$$(git ls-files _project _blog results-data results-explorer .claude .codex .gemini .pre-commit-config.yaml .importlinter todo.config.yaml skill-sync.yaml skill-sync.lock .gitattributes .coveragerc_core .dockerignore .env.example .mcp.json AGENTS.md CLAUDE.md GEMINI.md ANTIGRAVITY.md .github/workflows/results-explorer-browser.yml .github/workflows/seed-corpus.yml .github/workflows/sync-results-data-to-published.yml .github/workflows/validate-submission.yml tests/unit/scripts/explorer_pipeline tests/unit/explorer tests/uat/test_explorer_smoke.py tests/unit/release/test_ruleset_drift_review_coverage.py tests/unit/scripts/test_blind_spot_tools.py tests/unit/scripts/test_build_joinorder_data.py tests/unit/scripts/test_explorer_build_contract.py tests/unit/scripts/test_pr_review_followups.py tests/unit/scripts/test_reference_usage_audit.py tests/unit/scripts/test_scan_explorer_stale_theme.py tests/unit/scripts/test_scan_explorer_tokens.py tests/unit/scripts/test_shrink_rollup.py tests/unit/scripts/test_skill_sync_lock_audit.py tests/unit/scripts/test_submission_workflow_waiver.py tests/unit/test_agent_write_preflight.py tests/unit/test_auto_merge_soundness_paths.py tests/unit/test_cross_surface_applicability.py tests/unit/test_oracle_coverage_map.py tests/unit/test_ruleset_drift.py tests/unit/test_self_binding_detector.py tests/unit/test_site_header_parity.py tests/unit/test_sync_results_workflow.py tests/unit/core/joinorder/test_canonical_queries.py tests/unit/core/test_platform_labels.py tests/unit/workflows/test_validate_submission_comment_security.py tests/unit/workflows/test_detect_orphaned_commits.py tests/unit/workflows/test_validate_submission_vendor_gate.py); \
 	if [ -n "$$LEFTOVER" ]; then \
 		echo "ERROR: release curation incomplete; dev-only paths still tracked:" >&2; \
 		echo "$$LEFTOVER" | sed 's/^/  /' >&2; \

_project/scripts/sweep_blind_spots.py

@@ -15,7 +15,7 @@
 Triage edits only the frontmatter and appends one line under a
 ``## Triage log`` section. Triage does NOT author TODO files —
 ``promote`` records the link to a TODO id you authored separately
-(see ``_project/TODO_ENTRY_TEMPLATE.yaml``).
+(see the DB tracker spec in ``_project/specs/todo-db-tracker.md``).
 """
 
 from __future__ import annotations