docs: add session guidance for same-session, compact, or fresh start

[Amanjyot-P]

Summary

Adds a "Session guidance" section to the README explaining when Compound Engineering users should stay in the same session, compact context, or start a fresh session — anchored to the loop's durable handoff points (a committed plan, pushed code, or a landed review report) rather than session duration alone.

Addresses the request in #884: users running long sessions (especially with 1M context) weren't sure when to compact, clear, or continue, and the docs didn't call out that each loop step's artifact is itself the safe checkpoint.

Validation

• bun run release:validate — pass
• bun run plugin:validate — pass (marketplace + plugin manifest)
• bun test tests/release-metadata.test.ts tests/skill-conventions.test.ts — 304 pass, 0 fail (README-consistency and skill-convention suites)
• bun run test (full suite) — 3615 pass / 12 fail; the 12 failures are pre-existing timing-sensitive cross-model-routing and PR-watcher subprocess tests unrelated to this docs-only change (no source/skill files touched).

Security Disclosure

No security-relevant changes. This is a documentation-only change to README.md — no shell/exec, path handling, converters, credentials, or dependencies touched.

Agent Disclosure

• Model: Claude Code · Claude (this harness does not expose an exact model identifier in-session; family only)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: af9fa6646e

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Keep the review-to-compound handoff in the same session

For users following the standard loop, the next step after /ce-code-review is /ce-compound, but this recommendation tells them it is safe to start a fresh session first. A bare ce-compound captures the verified fix from the current conversation, and skills/ce-compound/SKILL.md:16-18 explicitly writes nothing when the session contains no solved problem; it does not discover or consume the prior code-review report. Consequently, following this guidance can skip the loop's namesake learning step. Recommend a fresh session only after compounding, or require passing explicit problem context/a handoff into the new session.

Useful? React with 👍 / 👎.

[Amanjyot-P]

Code Review Results

Scope: PR #1544, base main at 4e6738223d7dd66d765a598673c48c136fb78f95 -> head af9fa6646e07412bf881800bacc516fe70fd8c98; 1 changed file, 10 added lines.
Intent: Add README guidance for staying in the same session, compacting context, and starting a fresh session at durable handoff points.
Mode: markdown report-only.
Reviewers: correctness, security, testing, maintainability, project-standards, api-contract.

Confirmed Findings

No findings survived the required evidence, confidence, quote-the-line, deduplication, and validation gates.

Evidence and Disposition

One correctness reviewer proposed a P2 finding at README.md:183 about the claim that a fresh session can recover a completed /ce-code-review pass from an artifact. The candidate had a quoted changed line, confidence 75, pre_existing: false, and route gated_auto -> downstream-resolver. The cited README line and the installed ce-code-review, ce-compound, and session-history references were checked directly.

The candidate was actionable, so it required the Stage 5b validation batch. The validator could not be launched because delegated agent spawning was unavailable. Under the validation gate, a P2 finding affected by validator infrastructure failure is dropped rather than emitted as a confirmed finding. It is recorded as a residual risk below and is not treated as an approved defect.

Impact

No confirmed PR-introduced defect is reported after the required gates. The unresolved documentation risk is that users may infer that a fresh session can recover review-derived context even though the review report is stored in a per-run artifact directory and ce-compound does not document that report as an input.

Fixes

No fixes were applied. This review is report-only.

If the residual risk is confirmed in a later validation pass, the minimal proposed response is to remove /ce-code-review from the README statement that all listed steps restore prior artifacts, or explicitly direct users to remain in the same session through /ce-compound after review. An explicit durable handoff artifact is an alternative if cross-session review context is required.

Reviewer Lens Results

• Correctness: One P2 candidate was identified and then dropped by the required validation gate. No confirmed findings remain.
• Security: No findings, residual risks, or testing gaps reported.
• Testing: No findings, residual risks, or testing gaps reported.
• Maintainability: No findings, residual risks, or testing gaps reported.
• Project standards: No findings, residual risks, or testing gaps reported.
• API contract: No findings, residual risks, or testing gaps reported.

Actionable Findings

Actionable findings: none. No finding remains in the downstream-resolver queue.

Pre-existing Issues

None reported.

Residual Risks

• The dropped correctness candidate remains an unvalidated documentation risk at README.md:183: fresh-session recovery of /ce-code-review context may not work as the new guidance claims.
• No cross-model corroboration was available.

Coverage

• Input gate passed: input/READY was present; metadata.json, files.txt, full.diff, and intent.md were non-empty; all six reviewer JSON files were non-empty and parsed successfully.
• All six reviewer lenses completed. No reviewer artifact was malformed.
• Findings mechanics produced one candidate, with no malformed findings, no malformed returns, no pre-existing findings, and no duplicate findings.
• Quote-the-line gate passed for the candidate. Its first evidence item quoted README.md:183.
• One P2 candidate was dropped because the required Stage 5b validator could not be launched. Validator batch result: not run due delegated-agent infrastructure failure.
• Suppressed by confidence: none after the final mechanics pass.
• Cross-model review: not run; no corroboration or shortcut was claimed.
• Missing coverage: independent validator verdict for the one actionable P2 candidate and cross-model corroboration.
• Testing gaps reported by reviewers: none.

---

Verdict

Verdict: Ready to merge, with review coverage degraded by unavailable validator infrastructure.

Reasoning: No finding survived all required gates. One plausible documentation risk was independently checked but dropped because the required P2 validation batch could not run. Treat that risk as the first follow-up if validation infrastructure becomes available.

Fix order: Re-run validation for the README.md:183 session-recovery candidate before relying on the fresh-session guidance.

Actionable findings: none.