Fix maintenance flow, readiness gating, and quickstart

[P4X-ng]

Summary

• repair the maintenance and repo hygiene command surface so the documented Make targets and wrapper script work again
• tighten hop readiness so /ready requires successful CONNECT forwarding while keeping denied/auth-required responses visible for diagnostics
• add a concise QUICKSTART.md and make CI run the canonical Python checks (make pycheck and make unittest)

Testing

• make pycheck && make unittest
• make maintenance
• make maintenance-all-json

  

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on improving the developer experience and system reliability by overhauling repository maintenance tools, refining the readiness gating mechanism for network hops, and introducing a streamlined quickstart guide. The changes ensure that the project's health checks are more robust, maintenance tasks are more effective, and new users can get started more easily.

Highlights

• Maintenance Flow & Repo Hygiene: The repository maintenance and hygiene command surface has been repaired and enhanced. New Makefile targets (repo-scan-json, maintenance-json, maintenance-all, maintenance-all-json, maintenance-baseline) have been added, and existing targets (repo-scan, repo-clean, maintenance, maintenance-fix) now correctly use the --no-include-third-party flag by default. The repo_hygiene.py script has been significantly refactored to improve artifact classification, add detection for stale tracked artifacts and embedded Git repos, and provide more comprehensive scan reports.
• Readiness Gating Logic: The /ready endpoint's behavior has been tightened to require successful CONNECT forwarding for a hop to be considered 'ready'. Previously, a 403 or 407 response from a proxy would still mark a hop as 'ok'. Now, while these responses remain visible in /health for diagnostics, they will cause /ready to report as not ready, ensuring that the system is only considered ready when all hops can successfully establish connections.
• Quickstart Guide: A new QUICKSTART.md file has been added to provide a concise, step-by-step guide for quickly verifying the smoke harness end-to-end. The README.md has been updated to direct users to this new quickstart guide for the shortest path to verification.
• Python Checks in CI: The Makefile has been updated to include the new scripts/repo_hygiene.py and scripts/repo_maintenance.py in the pycheck and unittest targets, ensuring that these new scripts are covered by the canonical Python checks run in CI.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/auto-copilot-functionality-docs-review.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[amazon-q-developer]

The PR successfully addresses the maintenance flow, readiness gating, and quickstart improvements as described. The changes are well-implemented:

Key improvements:

• CI workflow now uses canonical make pycheck and make unittest targets
• Readiness gating tightened to require successful 2xx CONNECT responses rather than mere reachability (407/403 now correctly mark hops as unhealthy)
• Makefile maintenance targets properly consolidated and documented
• Comprehensive repository hygiene tooling added with baseline support
• Test coverage added for hop connectivity with proper status code parsing
• QUICKSTART.md provides clear concise setup instructions

The code is functional, properly tested, and ready for merge. No blocking defects identified.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[gemini-code-assist]

Code Review

This pull request introduces several valuable improvements. The maintenance and repository hygiene scripts have been significantly refactored for better clarity, functionality, and correctness, and the Makefile targets that use them are now much cleaner. The readiness-gating logic has been tightened to correctly distinguish between a reachable proxy and one that is ready for traffic, with corresponding updates to tests and documentation. The addition of QUICKSTART.md is also a great enhancement for new users. Overall, this is a high-quality contribution. I've added a few minor suggestions to simplify the Makefile by removing some redundant command-line flags.

[gemini-code-assist]

The --no-include-third-party flag is redundant. scripts/repo_hygiene.py defaults to excluding third-party directories, so this flag can be removed to simplify the command.

	$(PYTHON) scripts/repo_hygiene.py scan --repo-root .

[gemini-code-assist]

As with repo-scan, the --no-include-third-party flag is redundant here because it reflects the default behavior of the repo_hygiene.py script.

	$(PYTHON) scripts/repo_hygiene.py clean --repo-root .

[gemini-code-assist]

The --no-include-third-party flag is redundant here as it's the default for scripts/repo_hygiene.py. The command can be simplified by removing it.

	$(PYTHON) scripts/repo_hygiene.py scan --repo-root . --json

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Error path missing new reachable and status_code fields

Medium Severity

check_hop_connectivity returns reachable and status_code in the success path (when a response is received) but omits them from the except branch (connection failure, timeout, etc.). Since the hop statuses are exposed verbatim through the /health endpoint, API consumers and any future code that accesses result["reachable"] on an error result will get a KeyError. A connection-refused hop is definitively not reachable, so "reachable": False and "status_code": None belong in the error dict too.

Additional Locations (1)

• egressd/supervisor.py#L266-L275