Improve greenfield doctor guidance

[samtay32]

What changed

• classify the exact newly initialized empty-project state as Almost ready in doctor --human
• give non-coders one concrete instruction to have their coding agent create the first quality-check baseline and finish setup
• keep JSON output, nonzero exit status, configuration validation, check approval, and Git requirements unchanged
• document the greenfield behavior in the README, operating manual, and changelog

Root cause

The human formatter treated only onboarding and approval failures as setup. A post-init empty folder also reports the deliberate no project quality checks configured validation failure and commonly a missing Git repository, so the formatter fell through to the generic broken-configuration message.

Safety boundary

The new classification applies only when onboarding is still pending, the sole configuration error is the missing first check baseline, and every required failure is an expected setup item. Malformed configuration, protected-file drift, pending update reconciliation, missing tools, and all other failures retain their stronger status.

Validation

• focused doctor regression tests passed
• full npm run release:check passed: 65/65 tests, package dry-run, and packed-install smoke
• all 48 tracked Markdown files passed markdownlint-cli2@0.18.1
• git diff --check passed

Summary by CodeRabbit

• New Features

  • doctor --human now reports “Almost ready” for newly initialized, empty projects while the first quality-check baseline is being created.
  • Provides clearer next steps for completing initial setup.

• Bug Fixes

  • Preserves fail-closed behavior for machine-readable validation, exit status, approvals, and Git requirements.
  • Correctly switches to “Needs attention” when project configuration is invalid.

• Documentation

  • Updated the README, changelog, and operating manual with the revised setup guidance.

[samtay32]

@coderabbitai review

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 769c5ab7-aba0-4bb2-a3e1-d5d807e18e9b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

doctor --human now reports newly initialized empty projects awaiting their first quality-check baseline as “Almost ready,” while JSON validation and exit status remain fail-closed. Tests cover this state and invalid configuration behavior, with documentation updated accordingly.

Changes

Doctor readiness reporting

Layer / File(s)	Summary
Pending baseline detection and validation bin/ultimate-agent-stack.mjs, test/agent-stack.test.mjs	Centralizes the missing-checks error, adds the “Almost ready” outcome for pending first-baseline setup, and verifies the pending and invalid-configuration states.
Documentation and release notes README.md, docs/OPERATING_MANUAL.md, CHANGELOG.md	Documents the new human-readable readiness state and confirms that structured validation, approval, Git requirements, and exit status remain fail-closed.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and clearly reflects the main change: improved doctor guidance for greenfield projects.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/greenfield-doctor-human

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bin/ultimate-agent-stack.mjs`:
- Around line 2122-2137: Update the firstBaselinePending condition near
configFailure and onboardingFailure to validate failure details, not just report
names: allow only the expected Git and approval failure details required for the
“Almost ready” state, while preserving pending onboarding and configuration
prerequisites. Add regression coverage for unexpected git,
configuration-approval, and check-approval failures so they retain stronger
statuses.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 063e2adf-be14-417f-95ce-b86b55f77d58

📥 Commits

Reviewing files that changed from the base of the PR and between 5b4d6e9 and 255bd32.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• bin/ultimate-agent-stack.mjs
• docs/OPERATING_MANUAL.md
• test/agent-stack.test.mjs

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.