cc-ci/machine-docs/JOURNAL-cfold.md

JOURNAL — phase cfold

2026-06-11 — Phase cfold start

Investigation findings

Pre-existing test layout:

• 60 files in functional/ subdirs across 20 recipes
• 4 files in playwright/ subdirs (cryptpad, custom-html, uptime-kuma)
• Helper modules to move: _discourse.py, _ghost.py, _mailu.py, _mm.py, _mumble_proto.py, drone/functional/__init__.py
• mailu/test_backup.py, test_restore.py, ops.py explicitly add functional/ to sys.path — need updating to custom/

Decision: deprecated aliases

Per plan §2 option (RECOMMENDED): keep recognizing functional//playwright/ as deprecated aliases AND emit a loud one-line warning when a test is found in a deprecated folder. Using warnings.warn() at import time of discovery or print() directly. Will use print() (stderr) so it shows up in CI logs without needing to configure warning filters.

Implementation: subdirs = ("custom", "functional", "playwright") — canonical first — and after finding a test in functional/ or playwright/, emit: print(f"WARNING [cfold]: test found in deprecated folder '{sub}/' — move to custom/: {path}", flush=True, file=sys.stderr)

This way:

• custom/ is canonical and gets discovered first
• Old folders still work (zero breakage for repo-local tests) but emit a loud warning
• No silent coverage loss possible

2026-06-12 — M1 checkpoint: canonical custom/ layout landed locally

Code/work completed:

• runner/harness/discovery.py: canonical custom/ discovery, deprecated alias warnings, and custom_subdir_label() normalization helper.
• runner/harness/manifest.py: custom-test counts now normalize to canonical custom.
• all cc-ci custom tests/helper modules moved from tests/<recipe>/{functional,playwright}/ into tests/<recipe>/custom/.
• helper-import fallout fixed where needed (tests/mailu/{ops.py,test_backup.py,test_restore.py}).
• docs updated to describe custom/ as the canonical layout and explain the alias-compatibility window.

Mechanical move summary:

• 64 custom test files relocated into custom/
• helper modules relocated too: _discourse.py, _ghost.py, _mailu.py, _mm.py, _mumble_proto.py, tests/drone/custom/__init__.py

Verification:

nix shell nixpkgs#python312Packages.pytest --command pytest \
  tests/unit/test_discovery.py tests/unit/test_discovery_phase2.py tests/unit/test_manifest.py -q
# ..................
# 18 passed in 0.09s

Post-move grep state:

• remaining functional/ / playwright/ matches in live code are intentional: alias-policy docs, deprecated-folder assertions in the unit tests, and discovery comments describing the alias behavior.
• the pre-migration inventory in BACKLOG-cfold.md is intentionally unchanged because it is the M1 baseline record the Adversary will compare against.

Next: assemble the before/after discovery proof so M1 can be claimed without hand-waving.