Skip to content

Tracking document sources: worker evidence

Task: 57fb779b-4982-4909-8c6e-f821362ecb19, frozen version 2. Execution: 4983ee0f-5e6c-414f-9adb-83c370bebce5, 2026-10-11. Repository: h8v6/heyaira; branch: heyaira/57fb779b. Working directory for every command below: /Users/jablonskib/HeyAira-agents/.heyaira-worktrees/heyaira/57fb779b-worker. Source and starting HEAD: 5f2eb52f25e0f4f4002d6267cc691cb0057de946. Its parent: 508a74156a9f68623c0bd3779eb996be5d188f57. Initial git status --short was empty. No carried candidate or unrelated work. Checks ran on the implementation working tree above that HEAD, before the new local commit containing this evidence. The RESULT receipt records the exact resulting commit SHA. No push, PR, merge, installation, deployment, production source registration or production database mutation was performed.

server_identity matched the supplied project/resource/instance and execution principal; task_get read the exact historical v2 contract. Execution-scoped MCP does not expose continuity_context or task mutation. The Bridge delivery procedure and work contract were read; the result uses task_result.

Cause and implementation

Previously the registry and dispatch required a stored immutable SHA. Migration 056 adds nullable tracking_ref, drops SHA non-nullability, enforces exactly one pin mode, and adds a tracking uniqueness key without rewriting old rows or changing the pinned uniqueness/SHA checks. The CLI uses an exclusive option group and preserves source IDs on upsert. The existing read-only Git provider gains an exact branch-HEAD lookup using the repository's installation identity.

workflow_send shares source/branch resolution caches between both catalog profiles. It resolves task-repository sources to base_commit and other repository sources to the named branch HEAD. Only server-resolved pins can authorize tracking reads in dispatch_catalog; the public explicit pin API cannot supply arbitrary tracking commits. The stored manifest adds only resolved_from; tracking-reference and repository snapshots are checked again under the dispatch transaction's locks. Existing correction code uses the stored contract, with no new HEAD lookup. Confidence is high for the tested handler/database paths; real GitHub transport and listener-based MCP E2E remain the independent verifier/CI's responsibility.

Files touched: migration 056; src/heyaira/{admin,catalog_workflow,documents, git_provider,server,task_execution,workflow}.py; existing dispatch fixture; two targeted regression files; workflow/document-access and operations docs; MkDocs navigation; this evidence file. No skill or layer selection changed.

Actual command results

All pytest commands used TMPDIR="$PWD/.task-tmp", PYTHONPATH=src and -p no:cacheprovider. Database tests used the provided isolated test PostgreSQL over its Unix socket. No credential-bearing DSN is retained here.

Baseline command, before implementation (exit 1):

python -m pytest -q -p no:cacheprovider \
  tests/test_tracking_document_sources.py::test_tracking_task_repository_resolves_base_commit \
  tests/test_tracking_document_sources.py::test_tracking_migration_preserves_pinned_rows_and_exclusive_uniqueness \
  tests/test_tracking_document_sources.py::test_add_document_source_track_is_mutually_exclusive_with_commit_sha

Observed: 3 failed in 3.85s: UndefinedColumnError: column "tracking_ref" ... does not exist; migration assertion KeyError: 'tracking_ref'; CLI SystemExit: 2, the following arguments are required: --commit-sha.

During test development: the first implemented run was 4 failed, 16 passed in 11.02s because four assertions matched the human-readable exception text against its separate stable code. Those assertions now check the code. An expanded run passed 97 passed in 28.33s. Two later expanded runs each had 1 failed, 100 passed because the multi-file fixture first omitted the catalog's required reasoning_level, then supplied NULL instead of its required string; the fixture now uses the existing fixture's high value. No implementation failure was hidden by these test-only corrections.

Final targeted command (exit 0):

python -m pytest -q -p no:cacheprovider \
  tests/test_tracking_document_sources.py tests/test_tracking_git_provider.py \
  tests/test_dispatch_project_binding.py tests/test_git_provider.py tests/test_documents.py

........................................................................ [ 71%]
.............................                                            [100%]
101 passed in 24.91s

Named PostgreSQL acceptance command (exit 0), run before adding the extra multi-file/standalone-read/repository-revocation edge cases:

python scripts/test_postgres.py \
  tests/test_tracking_document_sources.py::test_tracking_migration_preserves_pinned_rows_and_exclusive_uniqueness \
  tests/test_tracking_document_sources.py::test_tracking_task_repository_resolves_base_commit \
  tests/test_tracking_document_sources.py::test_tracking_other_repository_resolves_head_once_and_replay_keeps_manifest \
  tests/test_tracking_document_sources.py::test_pinned_source_unchanged \
  tests/test_tracking_document_sources.py::test_catalog_source_changed_or_revoked_pinned \
  tests/test_tracking_document_sources.py::test_catalog_source_changed_or_revoked_tracking_during_read \
  tests/test_tracking_document_sources.py::test_tracking_manual_catalog_pin_requires_dispatch_resolution \
  tests/test_tracking_document_sources.py::test_tracking_new_revision_resolves_new_head \
  tests/test_tracking_document_sources.py::test_tracking_correction_keeps_workflow_manifest

...............                                                          [100%]
15 passed in 6.97s
postgres_acceptance=passed: selected tests, zero skipped tests

Existing named E2E command (exit 1 due to the runner's zero-skip policy):

python scripts/test_postgres.py \
  tests/test_catalog_workflow.py::test_catalog_dispatch_freezes_sources_and_preserves_acceptance \
  tests/test_task_execution.py::test_send_version_timeline_and_publication \
  tests/test_task_execution.py::test_time_limit_rejects_invalid

sss....                                                                  [100%]
SKIPPED [1] tests/test_catalog_workflow.py:18: listening sockets are not permitted here (agent sandbox); runs in CI
SKIPPED [2] tests/test_task_execution.py:101: listening sockets are not permitted here (agent sandbox); runs in CI
4 passed, 3 skipped in 1.62s
postgres_acceptance=failed: 3 skipped tests

These are the frozen criterion's explicit listening-socket exception, not passing E2E results. No statistics-reset exception was needed. The full suite was not run; the frozen contract assigns it to CI.

Static/documentation checks (each exit 0):

  • PYTHONPATH=src python scripts/export_mcp_contract.py --check: MCP contract is up to date (Bridge-facing schemas unchanged).
  • PYTHONPATH=src python scripts/check_docs_contract.py: documentation contract passed: 46 MCP tools covered.
  • PYTHONPATH=src python scripts/check_product_name.py: Product name check passed: use HeyAira in tracked text files.
  • PYTHONPATH=src python scripts/validate_runtime.py: runtime_validation=passed; system Git emitted sandbox cache warnings.
  • PYTHONPATH=src python -m mkdocs build --strict: INFO - Documentation built in 2.52 seconds; existing informational nav and excluded-link notices did not fail the strict build.
  • python -m compileall -q on all ten changed Python files: no output, exit 0. A separate ast.parse check printed AST syntax check passed: 10 changed Python files.
  • git diff --check: no output, exit 0.

The repository configures no Ruff, Flake8 or Pyflakes command/dependency in pyproject.toml or CI; its configured static checks are the scripts above. Optional diagnostic python -m ruff --version exited 1 with No module named ruff. Nothing was installed, and no Ruff success is claimed.

CLI command (exit 0): PYTHONPATH=src python -m heyaira.admin add-document-source --help. Its actual usage includes (--commit-sha COMMIT_SHA | --track BRANCH) and help --track BRANCH resolve a branch-tracking source at workflow_send.

Frozen criterion records

criterion_id: migration
outcome: pass
evidence_path: docs/agent-work/57fb779b-evidence.md
feedback: Read migration 056; the named PostgreSQL migration regression exits 0 and preserves every prior row field, rejecting both/neither modes and duplicate tracking registrations.

criterion_id: resolution
outcome: pass
evidence_path: docs/agent-work/57fb779b-evidence.md
feedback: Named PostgreSQL resolution tests exit 0; final targeted suite has 101 passes, covering base_commit, another repository's branch HEAD, shared worker/verifier pins and pinned behavior.

criterion_id: manifest
outcome: pass
evidence_path: docs/agent-work/57fb779b-evidence.md
feedback: Named PostgreSQL manifest/source-change tests exit 0; all provenance values, tracking validation, source/repository revocation and unchanged legacy pinned validation pass. The existing named catalog E2E test hits only the explicitly permitted listener skip.

criterion_id: revision-vs-correction
outcome: pass
evidence_path: docs/agent-work/57fb779b-evidence.md
feedback: Named PostgreSQL revision and correction regressions exit 0: the new revision reads the new HEAD; the production correction offer preserves the full stored manifest, profile, hash and original HEAD without Git reads.

criterion_id: cli-and-docs
outcome: pass
evidence_path: docs/agent-work/57fb779b-evidence.md
feedback: CLI help exits 0, exclusive argument parsing and tracking upsert regressions pass, and workflow plus operations paragraphs document resolution and corrections; strict documentation build exits 0.

criterion_id: checks
outcome: pass
evidence_path: docs/agent-work/57fb779b-evidence.md
feedback: Final targeted pytest exits 0 with 101 passed; named PostgreSQL acceptance exits 0 with 15 passed and zero skips; configured static/documentation checks and changed-file syntax checks exit 0. Three existing E2E listener skips are the permitted sandbox exception; full suite belongs to CI. Ruff is neither configured nor available.