# Local CCRA Reviews ## 1. Purpose `local_ccra_reviews/` records first-pass Local CCRA reviews for this project. The directory is a project-side review run archive. It is not the canonical CCRA Agent definition, not a reusable Skill source tree, and not the formal Web CCRA upload bundle. First-version scope: - Serves only `the-mindscape-of-bro-tsong`. - Uses CCPE Agent Runtime to create or continue a real child review session. - Passes primary inputs and outputs through local files, not through main-session chat summaries. - Treats Local CCRA output as formal local first review, but not as Owner or Web CCRA final judgment. ## 2. Ownership This repository owns: - Local review run directories. - Input file lists and review packets for a specific project round. - Runtime session metadata for continuing child review sessions. - Local CCRA reports, Owner decisions, and action registers. `ccpe-system` owns: - `ccra-local-reviewer` Agent Spec. - CCPE Agent Runtime contract. - Review rubric, lifecycle gate policy, invocation protocol, and report format. - Decisions about whether companion automation should stay Agent-specific or be routed to `skills-vault`. `skills-vault` owns only automation that CCPE or the owner explicitly abstracts as reusable, deterministic, cross-project tooling. ## 3. Directory Convention Use the public Owner / Web CCRA round as the first directory level, then use a Local CCRA pass label. Examples: ```text local_ccra_reviews/ round-05_selector-calibration-policy/ 01/ 02/ round-04/ pilot-01/ pilot-02/ round-03.2a_depth-limiting-qpi-override-patch/ 01/ ``` The public round label follows the same semantic round version as the review bundle, such as `round-05`, `round-04.1`, or `round-03.2a`. The child directory records the local review pass: - `01/`: first Local CCRA review for that public round. - `02/`: second Local CCRA review after accepted fixes. - `pilot-01/`: historical pilot used to test invocation authenticity, persistence, and report quality before formal use. - `pilot-02/`: historical pilot used to test Patch 1 two-turn review/planning behavior before formal use. - Later numbers are allowed only when the owner explicitly asks for another local review pass. ## 4. Run Directory Files Each run directory should use these files: ```text run-notes.md review-metadata.json gate-manifest.yaml lifecycle-guard-config.yaml agent-invocation-packet.md prompt-to-send.md turn-prompts/ review-context.md review-file-manifest.json helper-outputs/ bundle-audit.md bundle-audit.json routing-behavior-diff.md routing-behavior-diff.json gate-run-report.md gate-run-report.json logs/ lifecycle-status-guard-scan.md lifecycle-status-guard-scan.json 04_LOCAL_CCRA_REVIEW_REPORT.md next-review-requirements.md returned-output.md 05_WEB_LOCAL_CCRA_COMPARISON.md findings-confirmation.md owner-decision.md ``` File roles: - `run-notes.md`: run setup, helper commands, skipped helpers, dispatch record, child session id, and resume notes. - `review-metadata.json`: review goal, scope, non-goals, open questions, target reviewer, and output paths. - `gate-manifest.yaml`: project-owned validation gates for `regression-validation-gate-runner`; use `dry_run` until the owner approves execution. - `lifecycle-guard-config.yaml`: lifecycle and status overclaim scan configuration. - `agent-invocation-packet.md`: file-first packet for CCPE Agent Runtime. - `prompt-to-send.md`: prompt used when invoking a Codex child thread or equivalent carrier. - `turn-prompts/`: one prompt file per runtime turn, such as `review_turn`, `planning_turn`, and optional `comparison_turn`. - `review-context.md` and `review-file-manifest.json`: deterministic context index generated by `review-context-builder`. - `helper-outputs/`: deterministic evidence generated by registered helper Skills. Missing optional helper outputs must be recorded in `run-notes.md`. - `04_LOCAL_CCRA_REVIEW_REPORT.md`: the only judgment output from `ccra-local-reviewer`. - `next-review-requirements.md`: same-child-session planning output that defines the next review's required materials, evidence, and open Owner/Web decisions. - `returned-output.md`: the raw returned output from the child reviewer, or a pointer to the report if the report is the returned output. - `05_WEB_LOCAL_CCRA_COMPARISON.md`: optional main-session comparison between Local CCRA output and Web CCRA / GPT feedback for pilot tuning. - `findings-confirmation.md`: Chinese Owner-facing extraction of core findings requiring decision before Codex repair. - `owner-decision.md`: Owner decision states for findings, such as `accept_for_codex_fix`, `reject`, `defer_to_future_round`, or `escalate_to_web_ccra`. ## 5. Runtime Rules When the owner asks for Local CCRA review: 1. The main Codex session prepares a new local review run directory. 2. The main session invokes CCPE Agent Runtime to create or continue a child review session. 3. The runtime session id is recorded in `run-notes.md` and `agent-invocation-packet.md`. 4. `review_turn`: `ccra-local-reviewer` reads the review run inputs and referenced project files. 5. `review_turn`: `ccra-local-reviewer` writes `04_LOCAL_CCRA_REVIEW_REPORT.md`. 6. `planning_turn`: the same child session continues from the first-turn report and writes `next-review-requirements.md` when next-round planning is requested. 7. `ccra-local-reviewer` does not modify product files, selector rules, model cards, regression cases, review bundles, or Owner decisions. 8. The main Codex session writes `findings-confirmation.md` in Chinese before asking Owner to decide findings. 9. Codex does not repair a finding until Owner records the decision in `owner-decision.md`. The default formal pattern is two turns in the same child session: - `review_turn`: judge the current materials, findings, evidence gaps, and action recommendation. - `planning_turn`: convert the first-turn judgment plus Owner decisions into next-review requirements and submitted-material guidance. `planning_turn` should not re-review the full current bundle unless new evidence was added or the owner explicitly asks for re-review. Expected run behavior: - A useful Local CCRA pass is a deep file-first review, not a quick chat summary. - The normal target budget for a mature run is roughly 5-10 minutes, comparable to Web CCRA review and dependent on the client/runtime configuration. - The child reviewer may use local tools to inspect archives, query manifests, run deterministic helper Skills, and execute owner-approved regression or validation gates. - The main session should avoid interrupting a running child review only because it spends several minutes reading files or running tools. - `run-notes.md` should record observed duration when available so later tuning can distinguish normal review time from runtime problems. The project follows the CCPE setup guide at: ```text C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review-runtime-setup.md ``` ## 6. Review Loop Recommended flow: ```text Owner requests Local CCRA review -> create local_ccra_reviews/// -> run review-context-builder and applicable helper Skills -> invoke CCPE Agent Runtime child session -> review_turn writes LOCAL_CCRA_REVIEW_REPORT -> planning_turn writes next-review-requirements when needed -> Codex writes findings-confirmation.md in Chinese -> Owner records decision -> Codex executes accepted actions -> next local review pass uses the next pass label if needed -> accepted material is packaged for Web CCRA when the owner asks ``` Major public rounds normally should receive Local CCRA review after Owner / Web CCRA define the round goal. Patch rounds such as `round-03.2a` are optional and owner-directed. After `pilot-02` and CCPE Patch 2, Local CCRA v0.1.2 is usable as the formal local first-review lane with conditions. For v0.1.2, every new run should declare these helper/runtime policy fields in `review-metadata.json` or `agent-invocation-packet.md`: ```text bundle_audit_profile: ccra_mindscape_review_bundle | generic | not_applicable gate_execution_mode: dry_run | run | owner_waived | not_applicable routing_diff_policy: required | skipped_no_after_evidence | manual_equivalent_required | not_applicable lifecycle_scan_scope: current_review_bundle | changed_files | knowledge_assets | model_library_state | whole_repo ``` `returned-output.md` should preserve a compact Owner-facing summary, including final action recommendation, blocking status, required next action, output paths, and evidence limitations. `findings-confirmation.md` should preserve the Owner decision surface in Chinese. Each item should include: - core confirmation question; - Local CCRA recommendation; - Codex implementation recommendation; - proposed decision state; - allowed repair scope if accepted; - impact if not accepted; - evidence paths; - exact Owner question when clarification is required. Allowed decision states are: ```text accept_for_codex_fix reject defer_to_future_round escalate_to_web_ccra owner_clarification_required accept_as_known_limit ``` Only `accept_for_codex_fix` authorizes Codex to modify project files for that finding. For the broader Round Conductor protocol, see: ```text docs/ROUND_AUTOMATION_PROTOCOL.md ``` ## 7. Relationship To Web CCRA Bundles `ccra_review_bundle/` remains the formal Web CCRA / GPT upload archive. After a Local CCRA pass is accepted, create the formal Web CCRA bundle under the existing dated bundle convention: ```text ccra_review_bundle/round-NN_YYYY-MM-DD_topic/ ``` Do not create shorthand bundle directories such as `ccra_review_bundle/05/`. By default, the formal Web CCRA bundle does not include `04_LOCAL_CCRA_REVIEW_REPORT.md`. Include the local report only when the owner explicitly wants Web CCRA to review the local findings. ## 8. Non-Goals Local CCRA review must not: - Replace Owner judgment. - Replace Web CCRA at key product or lifecycle gates. - Upgrade model lifecycle status. - Add a third model. - Add LLM selector, RAG, database, frontend, backend, user system, or platform behavior. - Turn `ccra-local-reviewer` into an implementer. - Implement full Round-level automation or autonomous multi-pass repair loops. - Start repair before Owner decision. - Store canonical CCPE artifacts in this repository. - Store reusable Skill source in this repository.