| name | runtime-contract-audit |
| description | Audit LawnBerry Pi runtime contract drift across ports, startup behavior, systemd units, frontend proxies, docs, scripts, and config. Use for port mismatches, startup confusion, README vs runtime checks, and source-of-truth comparison work. |
| argument-hint | What runtime surface or port/startup behavior should be audited? |
| user-invocable | true |
Runtime Contract Audit
What this skill does
This skill performs a focused drift audit for ports, startup wiring, proxy behavior, and maintainer-facing runtime instructions.
Use it for
- port mismatch reports
- startup command confusion
- frontend-to-backend proxy drift
- systemd/runtime/docs inconsistency checks
- validating that a change did not silently break the established contract
Source-of-truth files
Read and compare these first:
docs/developer-toolkit.md
README.md
docs/OPERATIONS.md
docs/TESTING.md
frontend/vite.config.ts
frontend/server.mjs
frontend/playwright.config.ts
systemd/
backend/src/main.py
- relevant scripts under
scripts/
Procedure
- Capture the claimed runtime contract from maintainer docs.
- Verify the canonical ports and behavior in code and service units.
- Compare these surfaces explicitly:
- backend bind port and path prefix
- frontend dev port, preview port, and production server behavior
- proxy target for
/api
- local development commands vs deployed service commands
- docs examples vs actual service wiring
- Produce a concise mismatch table grouped by severity.
- If fixing drift, update the smallest set of docs/config files needed to restore a single consistent story.
- Re-check all touched surfaces after the edit.
Decision rules
- treat
backend/src/main.py, service units, and active frontend config as stronger truth than prose docs
- keep
8081, 3000, and 4173 unless intentionally changing the contract everywhere
- avoid broad rewrites; prioritize contradictions that would mislead maintainers or operators
Completion checks
- strongest source of truth is cited for each finding
- any port mismatch is resolved or clearly documented
- startup instructions match actual runtime behavior
- no stale proxy or service-unit references remain in edited files