Merge pull request #11 from PyAutoLabs/feature/build-pulse-agent-separation

Docs: canonical Build/Pulse/Agent boundary (Stage 5)

Author: Jammy2211

AGENTS.md

@@ -0,0 +1,44 @@
+# PyAutoPulse — Agent Guidance
+
+PyAutoPulse is the **health authority** of the PyAuto release ecosystem: it owns
+all health and release-readiness checking plus continuous monitoring of the
+PyAuto repos. `pyauto-pulse readiness` is the authoritative "is it safe to
+release?" gate.
+
+## The boundary (one description, mirrored in all three repos)
+
+- **PyAutoPulse — the health authority.** All health/readiness logic lives here:
+  version drift, install-path, URL hygiene, CI/worktree/timing monitoring.
+  `pyauto-pulse readiness` is the **authoritative** green/yellow/red verdict —
+  the single "is it safe to release?" gate. Pulse is an observer: it reads and
+  emits verdicts; it never writes into other repos and never triggers Build.
+- **PyAutoBuild — the executor.** Packaging, tagging, notebook generation, and
+  PyPI publication via `release.yml`. Build runs **no** readiness checks of its
+  own and never re-derives a gate decision; it just executes.
+- **PyAutoAgent — the brain.** Hosts the agents that connect the two. It owns no
+  checks and no release steps; it gates on Pulse and delegates execution to
+  Build.
+
+## The call chain (always this order)
+
+```
+Agent  →  Pulse (gate)  →  Build (execute)
+```
+
+The agent asks `pyauto-pulse readiness --json`; only on a **green** verdict does
+it trigger Build's release. Pulse never triggers Build; Build never re-derives a
+gate decision the agent already made.
+
+## Where things live
+
+- Continuous checks (cheap, in the <30s `tick`): repo state, CI status, open PRs,
+  worktree drift, script timing, version skew.
+- Deep checks (on-demand / cloud cron, never in the tick): `verify_install` (pip
+  & conda install-path) and the URL-hygiene sweep (`url_sweep` + the central
+  `.github/workflows/url-check.yml`).
+- `readiness` rolls these into the authoritative verdict (URL hygiene is
+  monitoring only and does **not** gate it).
+
+See [`CLAUDE.md`](CLAUDE.md) for Pulse's internals — the check framework, the
+<30s tick budget, how to add a check, and the hard rules (observer-only, colour
+coding, atomic state writes).

CLAUDE.md

@@ -5,16 +5,20 @@ discovering this repository.
 
 ## What this repo is
 
-PyAutoPulse is a continuous-monitoring daemon for the PyAuto ecosystem.
-It polls 18 PyAuto repos every N minutes and surfaces drift (CI status,
-dirty checkouts, branch ahead/behind, open PRs, worktree state, script
-timing regressions) with green/yellow/red colour coding.
-
-It is **separate** from PyAutoBuild on purpose: PyAutoBuild produces
-PyPI releases; Pulse monitors developer state continuously. Pulse shells
-out to `autobuild` primitives but never imports PyAutoBuild Python.
-
-See `README.md` for user-facing docs.
+PyAutoPulse is the **health authority** of the PyAuto ecosystem. It owns all
+health and release-readiness checking: continuous monitoring (CI status, dirty
+checkouts, branch ahead/behind, open PRs, worktree state, script-timing
+regressions, version skew) plus deep on-demand/cloud checks (install
+verification, URL hygiene), all green/yellow/red colour coded. `pyauto-pulse
+readiness` is the **authoritative** "is it safe to release?" gate.
+
+It is **separate** from PyAutoBuild on purpose: PyAutoBuild is a pure executor
+(it produces PyPI releases and runs no readiness checks); Pulse owns the
+checking. Pulse shells out to `autobuild` primitives but never imports
+PyAutoBuild Python, never writes into other repos, and never triggers Build.
+
+See [`AGENTS.md`](AGENTS.md) for the canonical Build/Pulse/Agent boundary and the
+`Agent → Pulse → Build` call chain, and `README.md` for user-facing docs.
 
 ## Hard rules
 

README.md

@@ -1,6 +1,11 @@
 # PyAutoPulse
 
-Continuous-monitoring daemon for the PyAuto ecosystem.
+The **health authority** of the PyAuto ecosystem: a continuous-monitoring daemon
+that also owns all release-readiness checking. `pyauto-pulse readiness` is the
+authoritative "is it safe to release?" gate — [PyAutoBuild](https://github.com/PyAutoLabs/PyAutoBuild)
+is a pure executor and the [PyAutoAgent](https://github.com/PyAutoLabs/PyAutoAgent)
+release agent dispatches a release only on a green verdict. See `AGENTS.md` for
+the boundary.
 
 ## What it does
 

pulse/checks/url_check_live.py

@@ -417,8 +417,8 @@ def render_markdown_issue(results: list[Result], repo_label: str) -> str:
             lines.append(f"  - … and {len(r.locations) - 20} more")
         lines.append("")
     lines.append("---")
-    lines.append("*Generated by `PyAutoBuild/autobuild/url_check_live.py`. "
-                 "Re-runs every Monday 04:00 UTC.*")
+    lines.append("*Generated by `PyAutoPulse/pulse/checks/url_check_live.py` "
+                 "(central `url-check.yml`). Re-runs every Monday 04:00 UTC.*")
     return "\n".join(lines) + "\n"