Remove the unreferenced root-level extract_signatures.py helper

[pesap]

Remove the unreferenced root-level extract_signatures.py helper

Executor instructions: Follow this issue step by step. Run every
verification command and confirm the expected result before moving on. If any
STOP condition is true, stop and report instead of improvising.

Drift check (run first): git diff --stat a11b6a3..HEAD -- extract_signatures.py pyproject.toml .pre-commit-config.yaml AGENTS.md docs/source
If any in-scope file changed since this issue was written, compare the
Current behavior excerpts against live code before proceeding. If they do not
match, stop and ask for /plan to refresh this issue.

Status

• Priority: P2
• Effort: S
• Risk: LOW
• Depends on: none
• Category: tech-debt
• Planned at: commit a11b6a3, 2026-07-08

Current behavior

PR #124 adds a top-level helper script named extract_signatures.py. It is not
wired into packaging, docs, CI, or repo guidance, and it executes a hard-coded
signature extraction when the file runs.

• extract_signatures.py:1-5 — top-level script with only a generic docstring and no CLI contract.

# extract_signatures.py:1-5
"""Extract and print simple Python function signatures from a source file."""

from __future__ import annotations

import ast

• extract_signatures.py:56-74 — hard-coded method list, hard-coded source path, and module-level printing.

# extract_signatures.py:56-74
methods = [
    "update_object",
    "update_property",
    "delete_property",
    "delete_object",
    "add_scenario",
    "list_parent_objects",
    "list_child_objects",
    "list_object_memberships",
    "iterate_properties",
    "validate_database",
    "backup_database",
    "to_csv",
    "list_models",
    "list_scenarios_by_model",
]

_print_signatures_in_order(extract_signatures("src/plexosdb/db.py", methods), methods)

• Repository search at the planned commit found no caller or documentation for the helper outside itself.

$ rg -n "extract_signatures|_print_signatures_in_order" . --glob '!uv.lock' --glob '!src/plexosdb-mcp/uv.lock' --glob '!CHANGELOG.md'
./extract_signatures.py:35:def extract_signatures(file_path: str | Path, methods: list[str]) -> dict[str, str]:
./extract_signatures.py:74:_print_signatures_in_order(extract_signatures("src/plexosdb/db.py", methods), methods)

Desired behavior or Goal

Remove the ad-hoc root-level helper from the mainline repository. The root of the
repo should not contain unreferenced one-off development scripts with hard-coded
paths and import/run side effects. If maintainers later need a supported
signature-extraction tool, it should be introduced as a documented tools/
utility with a real CLI contract and tests in a separate issue.

Acceptance criteria

• extract_signatures.py no longer exists at the repository root.
• rg -n "extract_signatures|_print_signatures_in_order" . --glob '!uv.lock' --glob '!src/plexosdb-mcp/uv.lock' --glob '!CHANGELOG.md' returns no matches in tracked source/docs/config files.
• No replacement root-level Python script is added.
• No package metadata, docs, or CI references point to the removed helper.
• Existing root package and MCP package validation still pass.

Non-goals

• Do not create a new supported signature-extraction CLI in this issue.
• Do not move the helper to tools/ unless a maintainer explicitly re-scopes this issue before work starts.
• Do not change PlexosDB public APIs or MCP server behavior.
• Do not edit historical changelog entries except to remove references to this helper if any are found.

Work Plan

Validation

• rg -n "extract_signatures|_print_signatures_in_order" . --glob '!uv.lock' --glob '!src/plexosdb-mcp/uv.lock' --glob '!CHANGELOG.md' returns no matches.
• uv run pytest --cov --cov-report=xml exits 0.
• uv run --project src/plexosdb-mcp pytest -q -c src/plexosdb-mcp/pyproject.toml src/plexosdb-mcp/tests exits 0.
• uv run prek run --show-diff-on-failure --color=always --all-files --hook-stage pre-push exits 0 before handoff.

Documentation

• None expected. If docs mention extract_signatures.py, remove that mention as part of this cleanup.

Testing

• No new tests are required for deleting an unreferenced helper.
• Existing tests and search validation are sufficient.

Risks

Breaking-change

Low. The helper is not documented, packaged, or referenced by source/tests/docs at the planned commit. Risk is limited to a maintainer using it manually from the worktree.

Review-size

Low. Expected change is one file deletion plus no replacement files.

Implementation notes

Scope

In scope:

• extract_signatures.py
• Any source/docs/config references discovered by the acceptance-criteria search

Out of scope:

• src/plexosdb/ public APIs.
• src/plexosdb-mcp/ runtime code.
• Creating a new tools/ script or CLI.

Suggested steps

1. Confirm no current source/docs/config references exist beyond extract_signatures.py.
2. Delete extract_signatures.py.
3. Re-run the acceptance-criteria search.
4. Run the focused and broad validation commands.

Test details

• If validation finds a real reference to the helper, stop and update the issue scope before deleting it.

Maintenance notes

• If signature extraction becomes a repeated maintainer need, file a separate issue for a supported tools/extract_signatures.py command with argparse inputs, no import-time side effects, docs, and tests.