From fb3332922c6be83e2464e823f082e537a8701953 Mon Sep 17 00:00:00 2001
From: davecoulter <davecoulter@gmail.com>
Date: Mon, 20 Jul 2026 22:20:09 -0400
Subject: [PATCH] Add logIssue skill, license, citation; retire tech_debt.md

Moves tech-debt tracking from a markdown file requiring a full
branch+PR cycle to GitHub Issues, filed via a new logIssue skill.
Also adds licensing/citation metadata now that the repo is tagged
as a forkable base, and fixes a test-isolation bug found during QA.
---
 .claude/skills/log_issue.md      | 18 ++++++++++++
 CITATION.cff                     | 12 ++++++++
 CLAUDE.md                        |  4 ++-
 LICENSE                          | 28 ++++++++++++++++++
 README.md                        |  6 +++-
 docs/conf.py                     |  6 ++--
 docs/tech_debt.md                | 49 --------------------------------
 src/db/tests/test_integration.py |  8 +++++-
 8 files changed, 76 insertions(+), 55 deletions(-)
 create mode 100644 .claude/skills/log_issue.md
 create mode 100644 CITATION.cff
 create mode 100644 LICENSE
 delete mode 100644 docs/tech_debt.md

diff --git a/.claude/skills/log_issue.md b/.claude/skills/log_issue.md
new file mode 100644
index 0000000..6db924c
--- /dev/null
+++ b/.claude/skills/log_issue.md
@@ -0,0 +1,18 @@
+# Skill: Log GitHub Issue
+**Trigger Command:** `logIssue <description>` — also invoked implicitly whenever you ask to log
+something as tech debt / a feature request / a bug that has no active code change to attach it to.
+
+**Action:**
+1. Determine the category: `tech-debt`, `enhancement`, or `bug`. If ambiguous, ask which applies.
+2. Draft a title (imperative, ≤70 chars) and a body with three sections: What, Resolution
+   condition / Acceptance criteria, and Source (how/when it was surfaced).
+3. Present the drafted title, body, and label to the user for confirmation. Do not file silently.
+4. On confirmation, run `gh issue create --title "..." --body "..." --label <label>`.
+5. Report back the created issue number and URL.
+
+**Constraints:**
+- No git branch, commit, or PR — issue-tracker-only, never touches the working tree.
+- `gh issue create` is explicitly pre-authorized for this skill only. This does not extend to
+  `gh pr create` or any other `gh` write command — PRs remain text-only per CLAUDE.md's PR Workflow rule.
+- Labels are fixed to `tech-debt`, `enhancement`, and `bug`. A new category needs the user's
+  go-ahead before inventing a label.
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000..93f95b3
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: Diffpype
+type: software
+authors:
+  - family-names: Coulter
+    given-names: David A.
+    orcid: "https://orcid.org/0000-0003-4263-2228"
+repository-code: "https://github.com/davecoulter/diffpype_claude"
+license: BSD-3-Clause
+version: 0.1.1
+date-released: "2026-07-20"
diff --git a/CLAUDE.md b/CLAUDE.md
index aa3c4a2..ff9f2ff 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,6 +33,8 @@ Claude may only suggest packages or write code that aligns with this strict base
     *   `genTests on [filename.md]` → `gen_tests.md`: Interactive CLI + Application QA session. Runs one step at a time, waits for user confirmation, diagnoses failures. Only exits when all steps pass. Must be completed before `genPR`.
     *   `genPR on [filename.md]` → `gen_pr.md`: Generates commit message, PR title, and PR body from git context + the architectural doc. Assumes `genTests` has been completed — generates with pre-checked boxes and verified outcomes.
     *   `stratSesh on [filename.md]` → `strat_sesh.md`: Structured briefing on structural changes, data flow changes, and code review highlights for a completed doc. Interactive drill-down — user chooses what to explore further.
+    *   `logIssue <description>` → `log_issue.md`: Files a GitHub Issue (tech-debt/enhancement/bug) directly — no branch, commit, or PR. This is now the sole tech-debt tracking mechanism, including debt discovered mid-implementation on an active branch — `docs/tech_debt.md` was retired in favor of GitHub Issues labeled `tech-debt`.
+
 
 
 ##### Operational Gotchas & Checklists
@@ -55,7 +57,7 @@ Claude may only suggest packages or write code that aligns with this strict base
 ### Directory References
 *   **Product Requirements:** Refer to `docs/prd.md` for overarching workflows.
 *   **Architecture & Design:** Refer to numbered files in `docs/architecture/` (e.g., `01_...`) for stage-by-stage design and prompting.
-*   **Technical Debt:** Refer to `docs/tech_debt.md` for tracked workarounds, dependency pins, and known limitations to revisit later.
+*   **Technical Debt:** Tracked as GitHub Issues labeled `tech-debt` — workarounds, dependency pins, and known limitations to revisit later. File new items via the `logIssue` skill rather than a markdown file.
 *   **Claude Skills:** Refer to `.claude/skills/` (or `.claude/rules/`) for repeatable execution scripts.
 
 ### Clarifications & Logs
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..3123aed
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, David A. Coulter
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
index b59e3b7..030b97f 100644
--- a/README.md
+++ b/README.md
@@ -39,4 +39,8 @@ Full architecture docs (numbered design stages, CLI guide, infrastructure diagra
 
 ## Project Status
 
-This is a **Stage 0 walking skeleton** — the reusable plumbing is complete and tested (98%+ coverage), but no astronomical detection/reduction logic has been added yet. If you're forking this as a base for a new project, everything here is meant to be kept; domain-specific logic goes on top.
\ No newline at end of file
+This is a **Stage 0 walking skeleton** — the reusable plumbing is complete and tested (98%+ coverage), but no astronomical detection/reduction logic has been added yet. If you're forking this as a base for a new project, everything here is meant to be kept; domain-specific logic goes on top.
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index 1250af9..ebf5887 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -66,8 +66,8 @@
     "uvicorn",
 ]
 
-# prd.md and tech_debt.md are reference documents, not part of the ADR wiki;
-# exclude them from the Sphinx source tree so MyST does not flag them as orphaned pages.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "prd.md", "tech_debt.md"]
+# prd.md is a reference document, not part of the ADR wiki; exclude it from
+# the Sphinx source tree so MyST does not flag it as an orphaned page.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "prd.md"]
 
 html_theme = "sphinx_rtd_theme"
diff --git a/docs/tech_debt.md b/docs/tech_debt.md
deleted file mode 100644
index 5a7a878..0000000
--- a/docs/tech_debt.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Diffpype Technical Debt & Deferred Fixes
-
-### Preamble
-This document tracks small workarounds, dependency pins, and known limitations that should be revisited later. It is distinct from `docs/prd.md` (deferred *product* features) and `CLAUDE.md` (agentic guardrails and workflow rules). Each entry should be actionable: what the item is, and the specific condition under which it can be resolved and removed.
-
-### Open Items
-
-#### Remove `setuptools<81` pin
-*   **What:** `pyproject.toml` pins `setuptools<81` because `opentelemetry-instrumentation==0.48b0` imports `pkg_resources`, which setuptools removed starting in v81. Without the pin, all OTel instrumentors fail to import (`ModuleNotFoundError: No module named 'pkg_resources'`).
-*   **Resolution condition:** Once the `opentelemetry-instrumentation-*` packages are upgraded past `0.48b0` to a version that no longer imports `pkg_resources`, remove the `setuptools<81` pin and the corresponding `ignore:pkg_resources is deprecated as an API:UserWarning` entry in `[tool.pytest.ini_options] filterwarnings`.
-*   **Source:** `docs/architecture/23_observability.md`, added 2026-07-09.
-
-#### Adopt React Router `v7_startTransition` future flag
-*   **What:** React Router emits a future-flag warning in the browser console during manual UI testing, recommending `v7_startTransition` be enabled ahead of the v7 migration.
-*   **Resolution condition:** One-liner opt-in — add `future: { v7_startTransition: true }` to the router config in `src/ui/`. Nothing is currently broken; the UI is fully functional without it.
-*   **Source:** Surfaced during doc 20 manual UI testing, 2026-07-08. Originally logged in `CLAUDE.md`'s Clarifications; moved here 2026-07-09.
-
-#### Unify CLI-triggered traces with an explicit root span
-*   **What:** `diffpype-manage` CLI commands (e.g. `run-dummy`) don't wrap their pre/post-dispatch DB writes in a root span the way `FastAPIInstrumentor` automatically wraps HTTP requests. The Celery dispatch onward correctly forms one coherent trace (confirmed live); DB writes before `.delay()` do not join it.
-*   **Resolution condition:** Wrap `cmd_run_dummy` (or `dispatch_dummy_job`) in an explicit `tracer.start_as_current_span(...)` if/when CLI-side observability parity with the API becomes a priority. Uncertain value — the core propagation requirement (trace context flows automatically from CLI-triggered dispatch through to the worker) already works without this.
-*   **Source:** Verified live during doc 23 QA, 2026-07-09. Originally logged in `prd.md`'s Deferred/Future Scope; moved here 2026-07-09.
-
-#### Implement real `db_backup_cron` + host-accessible backup/restore path
-*   **What:** `ENABLE_DB_BACKUP_CRON` (doc 21) wires a nightly Celery Beat schedule to `src.worker.tasks.db_backup_cron`, but that task is a stub — it only logs `"Nightly backup triggered"` and performs no actual backup. There is currently no backup or restore mechanism for the `db` service's data at all.
-*   **Resolution condition:** Implement `db_backup_cron` to actually run `pg_dump` (or `pg_basebackup`) against `db`, plus a corresponding restore path (CLI command or documented procedure). Proposed approach (discussed 2026-07-20): a hybrid volume strategy — keep `diffpype_db_data` (the live Postgres data directory) as a Docker-managed named volume, since Postgres's fsync/WAL durability and POSIX locking guarantees are safest there (this matters most on Docker Desktop for Mac, where a bind mount crosses the VM boundary via VirtioFS/gRPC-FUSE — not a concern on the real Linux production target, but still the right default regardless), and add a *second*, separate bind-mounted directory used only as the backup task's output destination, so dumps land on a real host path without touching how the live data directory is stored.
-*   **Source:** Raised 2026-07-20 while reviewing the `db` image change in `docker-compose.prod.yml`; ties back to the `ENABLE_DB_BACKUP_CRON` toggle introduced in doc 21 (2026-07-09).
-
-#### Publish multi-arch (`linux/amd64` + `linux/arm64`) images
-*   **What:** `ci.yml`'s `build-and-push` job runs on GitHub's `ubuntu-latest` runners and never sets a target `platforms:`, so `docker/build-push-action` only produces `linux/amd64` images for `api`, `worker`, and `db`. Pulling and running them on an Apple Silicon (`arm64`) machine — confirmed live via `docker compose -f docker-compose.prod.yml up -d` on 2026-07-20 — works, but only under emulation, with a `platform does not match` warning for every affected service.
-*   **Resolution condition:** Add `docker/setup-qemu-action` and `docker/setup-buildx-action` to the `build-and-push` job, and set `platforms: linux/amd64,linux/arm64` on the existing `docker/build-push-action` step for all three images. Produces a single multi-arch manifest per tag, so `docker pull` transparently selects the right architecture on any host — removing the warning and the emulation overhead rather than just detecting it. Expected cost: longer CI build time for the emulated `arm64` leg.
-*   **Source:** Surfaced 2026-07-20 while verifying the `db` image publish fix locally on an Apple Silicon Mac.
-
-### Resolved Items
-
-#### Publish a `db` image to ghcr.io
-*   **What it was:** `docker-compose.prod.yml` kept a `build:` context for `db` instead of pulling a published image, because CI's `build-and-push` matrix only covered `api` and `worker`.
-*   **Resolution:** Added a `db` entry to the matrix in `.github/workflows/ci.yml`, and switched `docker-compose.prod.yml` to `image: ghcr.io/davecoulter/diffpype_claude-db:${IMAGE_TAG:-main}`. Note the corrected name — the image is `diffpype_claude-db`, not `diffpype-db` as originally recorded here; `github.repository` resolves to `davecoulter/diffpype_claude`, a naming mismatch first caught in the `api`/`worker` images and fixed the same way here. Guarded by `src/core/tests/test_docker_compose_prod.py`.
-*   **Source:** Identified during doc 24 implementation, 2026-07-09. Resolved 2026-07-20.
-
-### Logs
-#### 2026-07-20
-*   **Action:** Resolved the "Publish a `db` image to ghcr.io" item — added `db` to `ci.yml`'s `build-and-push` matrix and switched `docker-compose.prod.yml` to pull `ghcr.io/davecoulter/diffpype_claude-db` (corrected from the originally-recorded `diffpype-db` name). Added a regression test in `src/core/tests/test_docker_compose_prod.py` covering all three images (`api`, `worker`, `db`) plus confirming `db` no longer builds locally.
-*   **Action:** Added the `db_backup_cron`/backup-restore/hybrid-volume item above, surfaced while discussing production storage for the `db` service.
-*   **Action:** Verified the `db` image publish fix end-to-end via `docker compose -f docker-compose.prod.yml pull && up -d` on an Apple Silicon Mac — all three services pulled and started successfully, confirming the ghcr.io naming fix works. Surfaced a `linux/amd64`-only platform warning in the process; logged as a new multi-arch tech-debt item above rather than fixed inline, since it's orthogonal to the naming fix.
-
-#### 2026-07-09
-*   **Action:** Created this document to track technical debt separately from product-scope deferrals (`prd.md`) and agentic guardrails (`CLAUDE.md`). Added the `setuptools<81` pin as the first tracked item.
-*   **Action:** Ported two items previously scattered elsewhere: the React Router future-flag warning (moved from `CLAUDE.md`'s Clarifications) and the CLI root-span gap (moved from `prd.md`'s Deferred/Future Scope). Both are code-level gaps in already-shipped work, not unbuilt product features, so they fit this document's scope better than `prd.md`'s.
-*   **Action:** Added the missing `db` ghcr.io image publishing gap, found while implementing doc 24's `docker-compose.prod.yml`.
diff --git a/src/db/tests/test_integration.py b/src/db/tests/test_integration.py
index 10846df..3c414ea 100644
--- a/src/db/tests/test_integration.py
+++ b/src/db/tests/test_integration.py
@@ -223,9 +223,15 @@ def test_sysadmin_seeding_links_step_definition_to_user(mocker, test_engine):
         db.close()
 
     # Committed outside the transactional fixture — must clean up explicitly so the
-    # unique constraint on username doesn't bleed into subsequent tests.
+    # unique constraint on username doesn't bleed into subsequent tests. Delete
+    # JobConfiguration rows referencing this user first: any code path that dispatches
+    # a job as sysadmin (including manual CLI testing against this DB) can create one,
+    # and it would otherwise block the User delete via fk_job_configurations_user_id.
     cleanup = TestSession()
     try:
+        sysadmin_id = cleanup.query(User.id).filter_by(username="sysadmin").scalar()
+        if sysadmin_id is not None:
+            cleanup.query(JobConfiguration).filter_by(user_id=sysadmin_id).delete()
         cleanup.query(StepDefinition).filter_by(name="dummy_sleep").delete()
         cleanup.query(User).filter_by(username="sysadmin").delete()
         cleanup.commit()