Harden QNAP operator shell safeguards

[nicho1ab]

Pull Request Evidence

Governing issue and intended outcome

• Governing issue: Closes Harden QNAP deployment command generation and operator-shell safeguards #635
• Intended outcome: Make the authoritative QNAP deployment runbook sufficient to constrain safe BusyBox-compatible human-operated command generation.

Implementation scope

• Major files or components changed: docs/developer/qnap-release-deployment-runbook.md, AGENTS.md, .github/copilot-instructions.md, docs/developer/codex-workflow.md, docs/developer/testing.md, and tests/unit/test_qnap_docker_runtime_config.py.
• Important behavior intentionally left unchanged or out of scope: No QNAP execution, SSH execution, deployment, production database operation, Cloudflare change, application feature work, statewide-data work, schema change, migration change, or required GitHub workflow/check change.
• Reviewer UI regression contracts: Not applicable - no reviewer UI route, presentation, interaction, or reviewer-facing behavior changed.

Acceptance-criteria evidence

Acceptance criterion	Evidence and result
Authoritative runbook constrains safe QNAP operator commands	PASS - the runbook now defines exact connection identity, sudo/Docker Compose preflight, BusyBox compatibility, one-line standalone SSH behavior, forbidden shell controls, and bounded PASS/FAIL requirements.
Forbidden interactive-shell controls are explicitly governed	PASS - generated QNAP commands may not use set -e, set -u, set -eu, exit, heredoc execution, Bash-only syntax, or commands intended to terminate the interactive SSH session.
Exact operator-supplied connection identity is preserved	PASS - exact username@host values must be used verbatim and may not be silently replaced by an SSH alias.
SCP and sudo boundaries are explicit	PASS - local scp does not use sudo; the destination must be operator-writable; QNAP sudo requirements and preflight are documented.
Interactive command failure remains safe	PASS - branching uses BusyBox-compatible conditional handling and numbered mutations/decision gates return nonzero while printing PASS or FAIL without terminating the SSH session.
Existing Issue #675 recovery semantics remain intact	PASS - the exceptional PostgreSQL client-saturation recovery and non-empty backup hard gate remain unchanged in substance and their preservation test passed.
Focused regression contract exists	PASS - tests/unit/test_qnap_docker_runtime_config.py now protects the operator-shell safeguards and retained #675 recovery contract.

Validation and failure classification

Validation	Result	Failure classification, if applicable
Ruff	PASS	none
mypy	PASS - 91 source files	none
Full pytest suite in CI	PASS - 2036 passed, 9 skipped	none
Documentation check	PASS	none
Required workflow contract	PASS	none
Focused local QNAP/runbook tests	PASS - 42 passed	none
git diff --check	PASS	none
Initial PR evidence gate	FAIL	PR metadata/evidence-body defect only; implementation validation passed and this PR body corrects the missing required evidence sections and fields.

• Implementation-caused test failures: None.
• Pre-existing failures: None relied upon for passage.
• Environmental failures: The secondary worktree could not directly use its own Python through scripts/docs.ps1; the documented shared primary-repository Python runtime was used successfully for the repository documentation checker.
• Tests intentionally not run: None relevant after CI; the required CI run completed the full test suite successfully.

UI and accessibility evidence (when applicable)

Not applicable - no UI, accessibility behavior, hosted page, or reviewer interaction changed.

Reviewer-facing redesign artifact classification (when applicable)

Not applicable - no reviewer-facing redesign occurred.

Documentation, assumptions, and remaining risks

• Documentation impact: The authoritative QNAP deployment runbook now owns the complete operator-shell command-generation safeguards, and directly affected agent/workflow/testing guidance points back to that authority rather than defining competing procedures.
• Assumptions and limitations: These safeguards govern generated human-operated QNAP commands; they do not authorize an agent to access QNAP, SSH, Docker, PostgreSQL, Cloudflare, or production data. Host-tool availability must still be documented or verified before use.
• Remaining risks or follow-up: After Harden QNAP deployment command generation and operator-shell safeguards #635 merges, the next governed data-foundation work remains Make preserved-artifact backfills safely repeatable #475 and Fix preserved-artifact backfill failures for 27 facilities #476 before statewide facility-snapshot execution. No statewide execution is authorized by this PR.

Governed-boundary review

Governed boundary	Status	Specific explanation or evidence
Schemas and migrations	No change	No schema or migration changed.
Ingestion and source-connector contracts	No change	No ingestion, extraction, normalization, or source-connector behavior changed.
Security and privacy	Authorized change	Operator guidance is strengthened to prevent unsafe shell behavior and accidental substitution of private connection values; no authentication, authorization, secret storage, or private data handling changed.
Production data and correction behavior	No change	No production data was accessed or modified and no correction behavior changed.
Deployment and infrastructure	Authorized change	The human-operated QNAP deployment runbook command-generation contract was strengthened; no deployment or infrastructure mutation occurred.
Repository governance	Authorized change	AGENTS, Copilot, Codex workflow, and testing guidance were reconciled to defer QNAP command generation to the authoritative runbook.
Required GitHub workflows and checks	No change	No required workflow, branch rule, or required check was changed or weakened.
Tests or checks weakened to obtain passage	Authorized change	Focused regression assertions were added; no existing test or required check was removed, skipped, relaxed, renamed, or weakened.

Required GitHub checks

• validate
• docs-check
• fixtures
• security