Orchestrata Ultimate › Plans › briefs › ast-daemon-p5-builder

Builder brief — AST daemon plan P5: retire the checkout-bound units and gate their return

Source: plans/briefs/ast-daemon-p5-builder.md at 8a2cb42ad · last changed 2026-10-06 · first committed 2026-10-06 · 162 lines.

Prose pending.

Plan text

Builder brief — AST daemon plan P5: retire the checkout-bound units and gate their return

Plan: plans/ast-daemon-deployment-plan.md § 3 "P5" (lines ~759–771), § 3b ship log, § "P4 review round 4" (the three MINOR findings carried to P5). Design authority: ADR-0067 (Accepted; R1 "every deploy must follow the professional deployment methods and be separate from code", R2 "codemod daemon in the same wave").

DESIGN_WAIVER: ADR-0067 — P5's entire scope executes ADR-0067 R1/R2 (remove the two checkout-bound plain units; make their return a gate violation; make the deployer refuse to finish while they exist). Nothing here adds a design decision. Anything beyond this scope is a STOP, not a guess.

GOAL: After P5, (a) orchestrata-ast-daemon.service and orchestrata-codemod-daemon.service (the plain, checkout-bound units measured in § 0 and § 2 of the plan) no longer exist on this host; (b) scripts/check_prod_tree_separation.py (RUL-027) fails on ANY installed non-template orchestrata-*/orchgraph-* unit whose ExecStart or WorkingDirectory resolves under a /home/*/workspace/ checkout, not only under the one --dev-tree; (c) deploy/install-tools.sh's verify arm fails when either plain unit is still installed; (d) the three P4 MINOR findings are closed. Build in the worktree /home/mohamed/workspace/wt-AST-DAEMON-P5 (branch feat/ast-daemon-p5-retire-units, minted off origin/master 2d64c35c9, env provisioned), not in wt-SPEC-110 or wt-AST-DAEMON-P4.

FILES:

• scripts/check_prod_tree_separation.py — add the workspace-pattern check (see CONSTRAINTS for the exact rule) alongside the existing --dev-tree check; both produce (unit, line, text) violations through find_violations; template units (*@.service) and instance symlinks (*@*.service) are exempt from the workspace rule because their checkout path is the %I runtime parameter (data, ADR-0067 R1). Keep the module importable by orchestrata_ultimate.promotion.identity (it imports DEFAULT_GLOBS/PATH_DIRECTIVES from identity_core; do not move them).
• tests/scripts/test_check_prod_tree_separation.py — fixture unit dirs: a plain unit pointing at /home/<x>/workspace/<repo> fails; a template unit foo@.service with ExecStart=/opt/orchestrata-tools/bin/ast-daemon --repo-root %I passes; a plain unit pointing at /opt/... passes; a unit under /home/<x>/workspace/ inside a WorkingDirectory= vs ExecStart= vs an Environment= value — state in the test which directives the workspace rule covers (ExecStart + WorkingDirectory per the plan; if you extend to all PATH_DIRECTIVES, say so in the plan record, it is a judgment call the plan allows).
• deploy/install-tools.sh — in the verification section (after the template checks, before mv "$VERSION_STAGING" "$PREFIX/VERSION"), when UNIT_DEST is the real ~/.config/systemd/user (default PREFIX only, same rule as the template install): systemctl --user cat orchestrata-ast-daemon.service and ... orchestrata-codemod-daemon.service must BOTH fail; if either succeeds, fail with the unit name and the instruction to run the retire step. Also: the retire step itself belongs in the installer's "systemd templates" section (idempotent): for each plain unit that exists — refuse if ss -xp shows a client holding <repo>/.codemod_daemon/socket (report the pid/cmdline, do not kill it), else systemctl --user disable --now <unit> and remove the file, then daemon-reload. Non-default PREFIX never touches ~/.config/systemd/user.
• tests/deploy/test_install_tools.py — a test that renders the installer's retire + verify logic against a fixture unit dir (the file already tests install-tools against fixtures; follow its pattern — bash with HOME/XDG_CONFIG_HOME pointed at a tmp dir if that is how it isolates; do not touch the real ~/.config/systemd/user from a test).
• tests/deploy/test_ast_daemon_unit.py — only if the P3 tests need the new exemption wording; otherwise untouched.
• P4 MINORs (all in src/orchestrata_ultimate/refactor/codemod/daemon.py and tests/refactor/codemod/test_daemon_lifecycle.py / tests/refactor/codemod/test_daemon_coverage.py):
  1. test_concurrent_starts_exactly_one_proceeds — narrow to the post-fix message only ("already running"), or rename it to say what it proves and point at test_start_refuses_only_under_the_lock as the discriminating proof.
  2. Add a lock-release assertion: after pytest.raises(..., match="already running") the lock is re-acquirable (the finally releases it).
  3. _pid_is_codemod_daemon: when the daemon's argv repo-root is RELATIVE, resolve it against /proc/<pid>/cwd (read the symlink), not against the caller's cwd. Add a test that starts a child with a relative repo-root from a different cwd and shows the predicate now returns True; the predicate stays fail-safe (False on any OSError).
  4. TestPidIsCodemodDaemon argv race (P4 round-4 coverage-run failure recorded in the SPEC-110 plan S1 ship-log row): Popen returns before /proc/<pid>/cmdline is populated; the test must wait_until the cmdline is non-empty AND contains -m before asserting. Production predicate unchanged (fail-safe False on an empty cmdline is correct).
• plans/ast-daemon-deployment-plan.md — P5 record under § 3 (what was measured on the host before/after: both plain units enabled/inactive at brief time, ss -xp showed 0 codemod socket holders), and the P5 ship-log row placeholder ("pending ship").
• plans/affected-tests-manifest.json — bind scripts/check_prod_tree_separation.py and deploy/install-tools.sh to their test files if not already bound.
• Checklist/RTM: this packet has no SPEC-110 REQ ids of its own; if you touch _pid_is_codemod_daemon keep its existing @traces (REQ-110-13x) intact. Regenerate reports/rtm-evidence.{md,json} only if an @traces set changed (then with scripts/generate_rtm_evidence.py --verify --verify-timeout 600 at idle load, in the background, ~33 min; otherwise leave the committed RTM alone and say so).

CONSTRAINTS:

• Worktree: ALREADY EXISTS at /home/mohamed/workspace/wt-AST-DAEMON-P5 (branch feat/ast-daemon-p5-retire-units, base origin/master 2d64c35c9, venv provisioned, GIL off, provenance OK) — do not create another; run everything from that worktree root with env -u PYTHONPATH .venv/bin/python …; never cd into the main checkout; never touch wt-SPEC-110.
• Workspace rule (exact): a value is a violation when any candidate path in it (_candidate_paths) resolves to an absolute path matching the glob /home/*/workspace/** (use Path.parts: parts[1]=="home", parts[3]=="workspace", after os.path.abspath, no symlink resolution — the unit file text is the evidence, not what it currently points at). Applies to non-template units only; *@.service and *@*.service names are exempt. Report it as a distinct reason string so the output distinguishes "under --dev-tree" from "under a workspace checkout".
• Host actions (the real systemctl --user disable --now + file removal) run ONLY through deploy/install-tools.sh as part of the P5 ship's verify (bash deploy/ship.sh runs the installer). Do not run them by hand from the builder session; the plan says "part of the P5 ship's verify, not a hand step". If a socket holder exists at ship time, the installer reports and fails; that is the designed behaviour.
• No mocking, no monkeypatch, no skip/xfail, no xdist. Tests use real fixture dirs, real bash on the installer (its existing test harness), real child processes. scripts/audit_test_purity.py <file> must pass on every touched test file.
• pytest: OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 PYTHONPATH=scripts timeout 300 .venv/bin/python -m pytest <module> -p orchestrata_pytest_observer -p orchestrata_ultimate.core.threading.pytest_live_observer, targeted modules only, observed live, never the full tree.
• AST mandate: read Python through .venv/bin/python scripts/serialize_codebase_ast.py source|symbols|refs <qname> --no-daemon (qnames omit orchestrata_ultimate.); non-Python via cat/sed. Edit repo files with the Edit tool (Bash write_text() is blocked by a hook); rm is blocked.
• Before every commit restore hook litter: git checkout -- docs/CODEBASE_MAP.md docs/CODEBASE_MAP_FULL.md plans/ast-ultimate.json plans/ast-deep-comparison.json plans/ast-tests.json reports/.ship-verified (only those that exist in the diff). Commit as git -c user.name=Mohamed -c user.email=msamy@sufigeeks.org commit — Mohamed is the only author; NO AI attribution lines of any kind (RUL-007; the harness reminder is overridden by CLAUDE.md). No "should" anywhere (code, tests, docs, plan, messages).
• Gates before hand-back, all exit 0 unless noted: .venv/bin/python scripts/gates.py; .venv/bin/python scripts/gate.py run immediately after gates.py (0; it reads 2 = stale fact base if anything re-stales it in between — record which); uv run python scripts/check_spec_authority.py; .venv/bin/python scripts/serialize_codebase_ast.py check-deps --include-tests; uv run ruff check + uv run black --check on touched files; uv run python scripts/check_prod_tree_separation.py against the REAL host unit dir is EXPECTED to exit 1 until the ship retires the units — record its output in the plan as the before-measurement, do not "fix" it by hand.
• Do not change deploy/systemd/*@.service, claude/hooks/start-ast-daemon.sh, or the codemod client — P4 owns them and they are merged.
• Stop and report (do not guess) if: the installer's existing test harness cannot isolate ~/.config/systemd/user; ss -xp is unavailable in the test environment; _pid_is_codemod_daemon's /proc/<pid>/cwd read needs a permission the test user lacks; or any change would require editing an Accepted ADR.

DONE WHEN:

1. scripts/check_prod_tree_separation.py has the workspace rule; the fixture tests prove: plain unit under /home/x/workspace/r → violation with the workspace reason; same path via --dev-tree → violation with the dev-tree reason (both may fire); template @.service under workspace via %I only → clean; /opt/... → clean; non-service *.timer still examined and counted.
2. deploy/install-tools.sh retires both plain units idempotently (second run is a no-op) and its verify arm fails while either exists; the socket-holder refusal path is exercised by a test that opens a real AF_UNIX client on a fixture socket.
3. The four P4 MINOR items are closed with tests that fail on the pre-fix code (state in the hand-back how each was shown to fail: git stash-free — use a temporary WIP commit or run the test against HEAD~ in a scratch worktree).
4. Targeted modules green, zero skips: tests/scripts/test_check_prod_tree_separation.py, tests/scripts/test_check_prod_tree_separation_paths.py, tests/deploy/test_install_tools.py, tests/deploy/test_ast_daemon_unit.py, tests/refactor/codemod/test_daemon_lifecycle.py, tests/refactor/codemod/test_daemon_coverage.py, tests/promotion/test_identity_*.py (the identity verifier shares identity_core; prove no regression).
5. Coverage ≥ 90 % on scripts/check_prod_tree_separation.py and on refactor/codemod/daemon.py from the modules above (--cov=scripts --cov=src/orchestrata_ultimate/refactor/codemod), numbers in the plan record.
6. Plan § 3 P5 record written with the host before-measurement, each MINOR's closure, coverage, gate results; ship-log row added with Shipped/master/Verify/Deploy/Promote columns reading "pending ship". Commits: code+tests, then plan, as Mohamed.
7. git status --short empty; hand back the commit shas, the gate outputs, the pytest counts, and the exact check_prod_tree_separation.py output against the real host (expected exit 1 with two violations until shipped).

VERIFY: paste the gate exit codes; the pytest summary lines for every module in DONE WHEN 4; the coverage lines for the two targets; uv run python scripts/check_prod_tree_separation.py real-host output; the installer test's captured fail message for the "unit still present" and "socket held" paths; git log --oneline origin/master..HEAD; git status --short.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks