dj-digger 0.1.0__tar.gz

dj_digger-0.1.0/.agents/scripts/changed-files

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+root=$(git rev-parse --show-toplevel)
+cd "$root"
+{
+  git diff --name-only
+  git diff --cached --name-only
+  git ls-files --others --exclude-standard
+} | sed '/^$/d' | LC_ALL=C sort -u

dj_digger-0.1.0/.agents/scripts/handoff

@@ -0,0 +1,63 @@
+#!/bin/sh
+set -eu
+
+# Initialize fields with defaults
+status=""
+qa=""
+next=""
+risk=""
+
+# Parse flags
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --status)
+      shift
+      status="$1"
+      ;;
+    --qa)
+      shift
+      qa="$1"
+      ;;
+    --next)
+      shift
+      next="$1"
+      ;;
+    --risk)
+      shift
+      risk="$1"
+      ;;
+    *)
+      printf 'usage: handoff [--status VALUE] [--qa VALUE] [--next VALUE] [--risk VALUE]\n' >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+# Derive branch name
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+# Derive compact diff summary from real shortstat output (files/insertions/deletions)
+staged_summary=$(git diff --cached --shortstat 2>/dev/null | sed 's/^ *//' || echo "")
+unstaged_summary=$(git diff --shortstat 2>/dev/null | sed 's/^ *//' || echo "")
+
+# Create compact diff summary
+if [ -n "$staged_summary" ] && [ -n "$unstaged_summary" ]; then
+  diff_summary="staged: $staged_summary; unstaged: $unstaged_summary"
+elif [ -n "$staged_summary" ]; then
+  diff_summary="staged: $staged_summary"
+elif [ -n "$unstaged_summary" ]; then
+  diff_summary="unstaged: $unstaged_summary"
+else
+  diff_summary="no-diff"
+fi
+
+# Print exactly six lines with headings
+printf 'Status: %s\n' "$status"
+printf 'Branch: %s\n' "$branch"
+printf 'Diff: %s\n' "$diff_summary"
+printf 'QA: %s\n' "$qa"
+printf 'Next: %s\n' "$next"
+printf 'Risk: %s\n' "$risk"
+
+exit 0

dj_digger-0.1.0/.agents/scripts/package-check

@@ -0,0 +1,79 @@
+#!/bin/sh
+set -eu
+
+# Build wheel and verify packaged resources
+# Runs through project-env, unpacks into temp dir, verifies contents, cleans up
+
+root=$(git rev-parse --show-toplevel)
+
+# Create temp directory for unpacking (subshell-wrapped for isolation)
+(
+  tmpdir=$(mktemp -d)
+  trap 'rm -rf "$tmpdir"' EXIT
+
+  # Build wheel and sdist using project-env, into a temp dir so nothing lands
+  # in the real dist/ directory.
+  cd "$root"
+  ./.agents/scripts/project-env uv build -q --out-dir "$tmpdir/dist"
+
+  # Find the built wheel (most recently modified)
+  wheel_file=$(find "$tmpdir/dist" -maxdepth 1 -name '*.whl' -type f -print -quit)
+  if [ -z "$wheel_file" ]; then
+    printf 'package-check: no wheel found in dist/\n' >&2
+    exit 1
+  fi
+  if ! find "$tmpdir/dist" -maxdepth 1 -name '*.tar.gz' -type f | grep -q .; then
+    printf 'package-check: no source distribution found in dist/\n' >&2
+    exit 1
+  fi
+
+  # Unpack wheel
+  cd "$tmpdir"
+  unzip -q "$wheel_file"
+
+  # Verify every resource read by runtime code is present in the package.
+  errors=0
+  required_files='dj_digger/analysis.toml
+dj_digger/schema-bundle.json
+dj_digger/schemas/tracks.schema.json
+dj_digger/schemas/library-artifacts.schema.json
+dj_digger/schemas/snapshot-manifest.schema.json
+dj_digger/schemas/dj-analysis.schema.json
+dj_digger/schemas/dj-sections.schema.json
+dj_digger/schemas/dj-analysis-run.schema.json
+dj_digger/catalog/sql/catalog-v9.sql
+dj_digger/catalog/sql/migrate-v6-to-v7.sql
+dj_digger/catalog/sql/migrate-v7-to-v8.sql
+dj_digger/catalog/sql/migrate-v8-to-v9.sql'
+  while IFS= read -r required; do
+    [ -z "$required" ] && continue
+    if [ ! -f "$required" ]; then
+      printf 'package-check: required resource missing: %s\n' "$required" >&2
+      errors=1
+    fi
+  done <<EOF
+$required_files
+EOF
+  [ "$errors" -eq 0 ] || exit "$errors"
+
+  # Run the installed wheel through its public console entry point from a
+  # directory that contains neither the checkout nor source files.
+  package_workspace="$tmpdir/runtime"
+  mkdir -p "$package_workspace/music" "$package_workspace/exports"
+  cat > "$package_workspace/config.toml" <<'EOF'
+[workspace]
+database = "catalog.sqlite"
+exports = "exports"
+
+[[library.sources]]
+id = "disabled"
+path = "music"
+set_eligible = false
+analyze = false
+enabled = false
+EOF
+  cd "$package_workspace"
+  "$root/.agents/scripts/project-env" uvx --from "$wheel_file" dj-digger --help >/dev/null
+  "$root/.agents/scripts/project-env" uvx --from "$wheel_file" dj-digger doctor \
+    --config "$package_workspace/config.toml" --json >/dev/null
+)

dj_digger-0.1.0/.agents/scripts/project-env

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+export UV_CACHE_DIR=/tmp/dj-digger-uv-cache
+export UV_TOOL_DIR=/tmp/dj-digger-uv-tools
+exec "$@"

dj_digger-0.1.0/.agents/scripts/protect-local

@@ -0,0 +1,47 @@
+#!/bin/sh
+set -eu
+
+# Validate arguments
+if [ $# -eq 1 ] && { [ "$1" = "--changed" ] || [ "$1" = "--staged" ]; }; then
+  mode="$1"
+  revision_range=""
+elif [ $# -eq 2 ] && [ "$1" = "--range" ]; then
+  mode="$1"
+  revision_range="$2"
+else
+  exit 2
+fi
+
+failed=0
+
+# Get the list of paths based on mode
+if [ "$mode" = "--staged" ]; then
+  paths=$(git diff --cached --name-only 2>/dev/null || true)
+elif [ "$mode" = "--range" ]; then
+  paths=$(git diff --name-only "$revision_range" 2>/dev/null) || {
+    printf 'cannot inspect protected paths in range: %s\n' "$revision_range" >&2
+    exit 1
+  }
+else
+  paths=$( { git diff --name-only 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null; } || true)
+fi
+
+# Check each path
+while IFS= read -r path; do
+  [ -z "$path" ] && continue
+
+  case "$path" in
+    config/local.toml|workspace/*|sets/*|*.sqlite*)
+      printf 'protected local path: %s\n' "$path" >&2
+      failed=1
+      ;;
+    .specifications/*)
+      printf 'protected specification archive path: %s\n' "$path" >&2
+      failed=1
+      ;;
+  esac
+done <<EOF
+$paths
+EOF
+
+exit "$failed"

dj_digger-0.1.0/.agents/scripts/qa-run

@@ -0,0 +1,144 @@
+#!/bin/sh
+set -eu
+
+# Execute QA commands for a given profile
+# Usage: qa-run <profile> [-- target1 target2 ...]
+# Profiles: docs, focused, subsystem, catalog, analysis, exports, runtime, full
+
+if [ $# -lt 1 ]; then
+  printf 'usage: qa-run <profile> [-- targets...]\n' >&2
+  exit 2
+fi
+
+profile="$1"
+shift
+root=$(git rev-parse --show-toplevel)
+
+# Parse arguments: optional -- is $1, targets are the rest
+if [ $# -gt 0 ] && [ "$1" = "--" ]; then
+  shift
+fi
+
+# Create temp directory for logs (subshell-wrapped for isolation)
+(
+  logdir=$(mktemp -d)
+  cleanup_on_exit=1
+  trap '[ "$cleanup_on_exit" = 1 ] && rm -rf "$logdir"' EXIT
+
+  status=0
+  cmd=""
+
+  case "$profile" in
+    docs)
+      # docs profile: git diff --check only
+      cmd="git diff --check"
+      git diff --check > "$logdir/docs.log" 2>&1 || status=$?
+      ;;
+
+    focused)
+      # focused profile: run pytest targets or shell scripts passed after --
+      if [ $# -eq 0 ]; then
+        printf 'qa-run focused: no targets provided after --\n' >&2
+        exit 2
+      fi
+
+      # Process each target, one log file per target
+      i=0
+      for target in "$@"; do
+        i=$((i + 1))
+        if [ -f "$target" ]; then
+          case "$target" in
+            *.sh)
+              # Shell script: run directly
+              cmd="sh $target"
+              sh "$target" > "$logdir/focused.$i.log" 2>&1 || status=$?
+              ;;
+            *.py)
+              # Python test file: run via pytest through project-env
+              cmd="uv run pytest $target"
+              "$root/.agents/scripts/project-env" uv run pytest "$target" > "$logdir/focused.$i.log" 2>&1 || status=$?
+              ;;
+            *)
+              printf 'qa-run focused: unknown target type: %s\n' "$target" >&2
+              exit 2
+              ;;
+          esac
+        else
+          printf 'qa-run focused: target not found: %s\n' "$target" >&2
+          exit 2
+        fi
+        [ "$status" -ne 0 ] && break
+      done
+      # For failure reporting, point at the last-attempted log
+      profile_log="$logdir/focused.$i.log"
+      ;;
+
+    subsystem)
+      # subsystem profile: relevant pytest + Ruff on changed Python
+      cmd="uv run pytest tests/test_subsystem.py && uv run ruff check src/dj_digger"
+      "$root/.agents/scripts/project-env" sh -c 'uv run pytest tests/ -k subsystem && uv run ruff check src/dj_digger' > "$logdir/subsystem.log" 2>&1 || status=$?
+      ;;
+
+    catalog)
+      # catalog profile: catalog/migration tests + package-check
+      cmd="uv run pytest tests/test_catalog.py && package-check"
+      "$root/.agents/scripts/project-env" sh -c 'uv run pytest tests/ -k catalog' > "$logdir/catalog.log" 2>&1 || status=$?
+      if [ "$status" -eq 0 ]; then
+        "$root/.agents/scripts/package-check" >> "$logdir/catalog.log" 2>&1 || status=$?
+      fi
+      ;;
+
+    analysis)
+      # analysis profile: worker/pipeline tests + Ruff + mypy
+      cmd="uv run pytest tests/test_analysis.py && uv run ruff check src/dj_digger/analysis && uv run mypy src/dj_digger/analysis"
+      "$root/.agents/scripts/project-env" sh -c 'uv run pytest tests/ -k analysis && uv run ruff check src/dj_digger/analysis && uv run mypy src/dj_digger/analysis' > "$logdir/analysis.log" 2>&1 || status=$?
+      ;;
+
+    exports)
+      # exports profile: export/schema tests + fixture validation
+      cmd="uv run pytest tests/test_exports.py"
+      "$root/.agents/scripts/project-env" sh -c 'uv run pytest tests/ -k exports' > "$logdir/exports.log" 2>&1 || status=$?
+      ;;
+
+    runtime)
+      # runtime profile: CLI/application tests + Ruff + mypy
+      cmd="uv run pytest tests/test_cli.py && uv run ruff check src/dj_digger/cli.py && uv run mypy src/dj_digger"
+      "$root/.agents/scripts/project-env" sh -c 'uv run pytest tests/ -k cli && uv run ruff check src/dj_digger && uv run mypy src/dj_digger' > "$logdir/runtime.log" 2>&1 || status=$?
+      ;;
+
+    full)
+      # full profile: full pytest, Ruff, mypy, fixtures, package-check, diff check
+      cmd="uv run pytest + uv run ruff check + uv run mypy + package-check + git diff --check"
+      "$root/.agents/scripts/project-env" sh -c 'uv run pytest tests/ && uv run ruff check src/dj_digger && uv run mypy src/dj_digger' > "$logdir/full.log" 2>&1 || status=$?
+      if [ "$status" -eq 0 ]; then
+        "$root/.agents/scripts/package-check" >> "$logdir/full.log" 2>&1 || status=$?
+      fi
+      if [ "$status" -eq 0 ]; then
+        git diff --check >> "$logdir/full.log" 2>&1 || status=$?
+      fi
+      ;;
+
+    *)
+      printf 'qa-run: unknown profile: %s\n' "$profile" >&2
+      exit 2
+      ;;
+  esac
+
+  # Default profile_log to the standard per-profile log file, unless already set (focused)
+  : "${profile_log:=$logdir/$profile.log}"
+
+  # If command failed, print failure details
+  if [ "$status" -ne 0 ]; then
+    printf '%s FAILED\n' "$cmd" >&2
+    if [ -f "$profile_log" ]; then
+      tail -10 "$profile_log" >&2
+    fi
+    printf 'log: %s\n' "$profile_log" >&2
+    # Keep the log dir around so the failure message above stays useful.
+    cleanup_on_exit=0
+    exit 1
+  fi
+
+  # Success
+  printf 'PASS %s\n' "$profile"
+)

dj_digger-0.1.0/.agents/scripts/qa-select

@@ -0,0 +1,90 @@
+#!/bin/sh
+set -eu
+
+# Read paths from stdin and classify them into QA profiles
+# Returns exactly one of: docs, focused, subsystem, catalog, analysis, exports, runtime, full
+
+# Collect all categories found
+categories=""
+
+# Read each path and classify it
+while IFS= read -r path; do
+  [ -z "$path" ] && continue
+
+  category=""
+
+  # Check for documentation files
+  if [ "$path" = "README.md" ] || [ "$path" = "CHANGELOG.md" ] || \
+     [ "$path" = "docs/README.md" ] || printf '%s\n' "$path" | grep -q '^docs/'; then
+    category="docs"
+  # Check for instruction/harness files
+  elif [ "$path" = "docker-agent.yaml" ] || printf '%s\n' "$path" | grep -q '^\.docker-agent/' || \
+       [ "$path" = "Makefile" ] || [ "$path" = "conftest.py" ] || \
+       [ "$path" = "pytest.ini" ] || [ "$path" = "pyproject.toml" ] || \
+       [ "$path" = "setup.py" ] || [ "$path" = "setup.cfg" ] || \
+       [ "$path" = "tox.ini" ] || printf '%s\n' "$path" | grep -qE '^\.(agents|codex|docker-agent|github)/|^(scripts|skills|tests)/'; then
+    category="focused"
+  # Check for production modules
+  elif printf '%s\n' "$path" | grep -q '^src/dj_digger/catalog/'; then
+    category="catalog"
+  elif printf '%s\n' "$path" | grep -q '^src/dj_digger/analysis/'; then
+    category="analysis"
+  elif printf '%s\n' "$path" | grep -q '^src/dj_digger/exports/'; then
+    category="exports"
+  elif printf '%s\n' "$path" | grep -q '^src/dj_digger/copying/'; then
+    category="subsystem"
+  elif printf '%s\n' "$path" | grep -q '^src/dj_digger/.*\.py$'; then
+    # Check if it's cli.py or another top-level Python file
+    if [ "$path" = "src/dj_digger/cli.py" ] || \
+       [ "$path" = "src/dj_digger/__main__.py" ] || \
+       [ "$path" = "src/dj_digger/__init__.py" ]; then
+      category="runtime"
+    else
+      # Check if it's in any other subsystem module
+      first_module=$(printf '%s\n' "$path" | sed 's|^src/dj_digger/||' | cut -d/ -f1 | sed 's/\.py$//')
+      case "$first_module" in
+        scanning|metadata|artifacts)
+          category="subsystem"
+          ;;
+        *)
+          # Default to subsystem for unknown modules
+          category="subsystem"
+          ;;
+      esac
+    fi
+  fi
+
+  # If we found a category, add it to the list
+  if [ -n "$category" ]; then
+    # Add to categories if not already present (avoid duplicates)
+    if ! printf '%s\n' "$categories" | grep -q "^$category$"; then
+      if [ -z "$categories" ]; then
+        categories="$category"
+      else
+        categories="$categories
+$category"
+      fi
+    fi
+  fi
+done
+
+# Count distinct production categories (not including focused or docs)
+production_count=$(printf '%s\n' "$categories" | grep -v '^focused$' | grep -v '^docs$' | grep -c . || true)
+
+# If no categories found, default to focused
+if [ -z "$categories" ]; then
+  printf '%s\n' "focused"
+elif [ "$production_count" = 0 ]; then
+  # Only focused and/or docs files found
+  if printf '%s\n' "$categories" | grep -q '^docs$'; then
+    printf '%s\n' "docs"
+  else
+    printf '%s\n' "focused"
+  fi
+elif [ "$production_count" -gt 1 ]; then
+  # Multiple production categories found
+  printf '%s\n' "full"
+else
+  # Single production category
+  printf '%s\n' "$categories" | grep -v '^focused$' | grep -v '^docs$'
+fi

dj_digger-0.1.0/.agents/scripts/staged-check

@@ -0,0 +1,43 @@
+#!/bin/sh
+set -eu
+
+# Validate that at least one allowed path is provided
+if [ $# -lt 1 ]; then
+  printf 'usage: staged-check <allowed-path> [allowed-path ...]\n' >&2
+  exit 2
+fi
+
+# Get list of allowed paths (sort them)
+allowed=$(printf '%s\n' "$@" | LC_ALL=C sort)
+
+# Get list of staged paths (sort them)
+staged=$(git diff --cached --name-only 2>/dev/null | LC_ALL=C sort || true)
+
+# Compare staged paths with allowed paths
+if [ "$staged" != "$allowed" ]; then
+  printf 'staged scope mismatch\nallowed:\n%s\nstaged:\n%s\n' "$allowed" "$staged" >&2
+  exit 1
+fi
+
+# Run protect-local validation using the same directory as this script
+script_dir="$(dirname "$0")"
+if ! "$script_dir/protect-local" --staged; then
+  exit 1
+fi
+
+# Check for conflict markers in staged content (only in added lines, anchored
+# to the real marker shapes to avoid false-positives on e.g. Markdown setext
+# underlines like "=======")
+if git diff --cached | grep -qE '^\+(<{7}( |$)|={7}$|>{7}( |$))'; then
+  printf 'conflict markers detected in staged content\n' >&2
+  exit 1
+fi
+
+# Run git diff --cached --check to detect other issues
+if ! git diff --cached --check; then
+  exit 1
+fi
+
+# All checks passed
+printf 'PASS staged scope\n'
+exit 0

dj_digger-0.1.0/.agents/skills/commit/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: commit
+description: Create one scoped conventional Git commit after QA and staged-scope checks
+---
+
+## Purpose
+
+Create a local commit only when the user explicitly asks to commit. A request
+to implement, finish, wrap up, or report completion is not commit authorization.
+This skill does not push, open a pull request, amend history, or broaden the
+requested file scope.
+
+## Before committing
+
+1. Confirm the current branch and inspect `git status --short` and the relevant
+   `git diff`; preserve unrelated worktree changes.
+2. Run the focused QA required by the changed files. Pipe explicit paths to
+   `.agents/scripts/qa-select`, then run the selected profile with
+   `.agents/scripts/qa-run`.
+3. Stage only the requested paths with explicit path arguments. Never use
+   `git add .` or `git add -A`.
+4. Run `.agents/scripts/staged-check <path> ...`; inspect `git diff --cached`.
+   Protected local paths are never staged. Specs require explicit authorization
+   in the current user turn. Repository-declared protected paths and ignored
+   files are never force-staged.
+
+## Commit
+
+Use the convention in [references/message-patterns.md](references/message-patterns.md).
+The subject is English, imperative, and conventional; include a body with the
+bounded worker brief (Goal, Changed files, Observed proof, Residual risk) when
+the subject alone cannot explain a meaningful change. Do not add
+`Co-Authored-By` or `Signed-off-by` trailers. Use `git commit` without
+`--no-verify`; never amend unless the user explicitly authorizes it.
+
+## Report
+
+Finish with `.agents/scripts/handoff` and report the exact QA command, staged
+paths, commit result, and any residual risk. A commit is not authorization to
+push or open a pull request.

dj_digger-0.1.0/.agents/skills/commit/references/message-patterns.md

@@ -0,0 +1,28 @@
+# Commit message pattern
+
+Use English and the subject form:
+
+`type[(scope[, scope2, ...])]: imperative summary`
+
+- Type: `feat`, `fix`, `refactor`, `chore`, or `docs`.
+- Scope is optional. Use it only when one concise repository area clarifies the
+  change, such as `cli`, `catalog`, `analysis`, `exports`, `copy`, or `agent`.
+  The repository commonly uses unscoped subjects such as `feat: ...` and
+  `docs: ...`; do not invent a scope for consistency theatre.
+- Keep the summary lowercase, imperative, and specific; wrap identifiers and
+  paths in backticks when they appear in a body.
+- Add `(#PRD-XXXX)` only when the user supplies a ticket reference. Omit it for
+  internal tooling.
+
+Use no body for mechanical changes. For meaningful changes, use short prose for
+one cause or bullets for distinct changes. When a bounded worker brief is
+useful, include:
+
+```
+Goal: <what this commit solves>
+Changed files: <paths or area>
+Observed proof: <QA command and result>
+Residual risk: <none or precise reservation>
+```
+
+Never add `Co-Authored-By`, `Signed-off-by`, or tool-attribution trailers.

dj_digger-0.1.0/.agents/skills/implement/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: implement
+description: Run the observable RED/GREEN TDD loop; verify changes before handoff
+---
+
+## Purpose
+
+Executes the test-driven implementation loop. Verifies every change is observable, reproducible, and public-path only. Fakes on the claimed integration path invalidate the proof.
+
+## Steps
+
+1. **Understand**: Read the task brief and scoped AGENTS.md.
+2. **Plan**: Identify entry points, owned files, and dependencies.
+3. **RED**: Run test suite; confirm the test fails as expected.
+4. **Code**: Edit files to satisfy the test.
+5. **GREEN**: Run test suite; confirm the test passes.
+6. **Verify**: Confirm the change is observable:
+   - No fakes or stubs in the implementation path
+   - All real library calls are tested or marked unverified
+   - Exit codes, file state, or database state changed as expected
+7. **Report**: Observed RED command/output, GREEN command/output, residual risk.
+
+## Observable proof
+
+- Command run (exact sh invocation)
+- Exit status (0 or non-zero)
+- Files modified (git status, diff)
+- Database state (sqlite3 query output, pragma foreign_keys check)
+- Artifact presence (file path exists and contains expected content)
+
+## Limitations
+
+Inaccessible real libraries (network, cloud, third-party) are reported as unverified, not passed.
+
+## Do not do
+
+- Use fakes, stubs, or mock patches on the implementation path
+- Commit without explicit handoff
+- Skip the GREEN step
+- Ignore residual risk or boundary conditions

dj_digger-0.1.0/.agents/skills/mr/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: mr
+description: Push a branch and create or update its GitHub pull request with gh
+---
+
+## Purpose
+
+Use when the user explicitly asks to open, create, or update a merge request or
+pull request. In this repository the requested `mr` parity skill operates on
+GitHub via `gh`; pushing and PR metadata changes are visible mutations covered
+by that explicit request.
+
+Never update a closed or merged PR. Match an existing PR by exact source head
+branch and verify its state before writing; target it by PR number, not a branch
+name. Preserve existing base, assignees, labels, reviewers, and other metadata
+unless the user requests a change.
+
+## Workflow
+
+1. Resolve the source branch without checking it out. For an existing open PR,
+   preserve its `baseRefName`. For a new PR, use an explicit user target first,
+   otherwise read GitHub's default with
+   `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`. Fetch the
+   selected remote ref and prove the relationship with `git merge-base`; do not
+   guess from `origin/HEAD` or an unrelated branch name.
+2. Inspect actual commits and `git diff <base>...<head>`. Run applicable QA via
+   `.agents/scripts/qa-select` and `.agents/scripts/qa-run`; derive title, summary,
+   test plan, and risks from those results, not assumptions. Before any push,
+   run `.agents/scripts/protect-local --range <base>...<head>` and inspect the
+   committed diff for private library facts; a clean working tree alone does
+   not prove that the branch range is safe.
+3. Before pushing, query all historical matches with
+   `gh pr list --head <branch> --state all --json number,state,mergedAt,headRefName,baseRefName,url`.
+   If an exact open-head PR exists, verify it with
+   `gh pr view <number> --json state,headRefName,baseRefName,url`. If only a
+   closed or merged match exists, stop before mutation and require a new branch
+   name. Refuse a new PR whose head equals its base.
+4. Push the exact branch with `git push -u origin <branch>`.
+5. Create with `gh pr create` only when no historical PR uses that exact head;
+   otherwise update the verified open exact-head PR by number with
+   `gh pr edit <number>`. Do not touch closed or merged PRs.
+
+Use the template in [references/pr-description.md](references/pr-description.md).
+Keep title and body in English. Do not add tool-attribution lines or merge
+policy flags such as auto-delete or squash unless requested.
+
+## Report
+
+Use `.agents/scripts/handoff`; include branch, base proof, PR URL/number, push
+result, actual QA, and residual risk. This skill does not merge the PR.

dj_digger-0.1.0/.agents/skills/mr/references/pr-description.md

@@ -0,0 +1,24 @@
+# Pull request description
+
+Title:
+
+`type[(scope)]: imperative summary`
+
+Body:
+
+```markdown
+## Summary
+- <distinct change, based on actual commits and diff>
+
+## Test plan
+- [ ] <re-runnable QA command or public-path check>
+
+## Risks and notes
+- <none, or a precise residual risk and follow-up>
+```
+
+Omit the risks section only when there is no meaningful reservation. Keep
+identifiers and paths in backticks. Use checkboxes even for checks already run,
+so reviewers can reproduce them. If the branch has no applicable ticket,
+include no ticket section. Never include `Co-Authored-By`, `Signed-off-by`, or
+generated-by attribution.