--- --- artifact_type: runtime-setup-guide runtime_id: ccra-local-review agent_id: ccra-local-reviewer version: 0.1.2 status: draft created: 2026-06-19 updated: 2026-06-19 --- # CCRA Local Review Runtime Setup ## 1. Purpose This guide tells a client project session how to start the `ccra-local-review` runtime environment. The first intended client is: ```text C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong ``` Local CCRA uses the same project knowledge base that supports Web CCRA: ```text C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\knowledge_assets ``` Use this path directly. Do not create a second Local CCRA copy of the knowledge base. Do not treat this file as a project runbook. The client project owns concrete run records, helper configs, returned outputs, and Owner decisions. ## 2. Required CCPE Files ```text C:\Users\wangq\Documents\Codex\ccpe-system\agents\agent-specs\ccra-local-reviewer.agent.md C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review.runtime.md C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review-invocation-packet.template.md C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review-report.template.md C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review-next-review-requirements.template.md C:\Users\wangq\Documents\Codex\ccpe-system\integrations\skills-vault\ccra-local-review-helpers.integration.md ``` ## 3. Required Installed Skills ```text C:\Users\wangq\.agents\skills\review-context-builder C:\Users\wangq\.agents\skills\review-bundle-audit C:\Users\wangq\.agents\skills\routing-behavior-diff-audit C:\Users\wangq\.agents\skills\regression-validation-gate-runner C:\Users\wangq\.agents\skills\lifecycle-status-guard-scan ``` Run installed Skill scripts through: ```text conda run -n skills-vault python -B ``` ## 4. Project Run Directory Create a run directory inside the client project: ```text local_ccra_reviews/// ``` Recommended pilot examples: ```text local_ccra_reviews/round-03/pilot-01/ local_ccra_reviews/round-04/pilot-01/ ``` Expected layout: ```text local_ccra_reviews/// run-notes.md review-metadata.json gate-manifest.yaml lifecycle-guard-config.yaml agent-invocation-packet.md prompt-to-send.md turn-prompts/ review-turn.prompt.md planning-turn.prompt.md comparison-turn.prompt.md 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 owner-decision.md ``` Missing optional helper outputs must be recorded in `run-notes.md`. ## 4.1 Required Knowledge Base The run environment must make this directory available to the Local CCRA reviewer: ```text C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\knowledge_assets ``` Minimum expected files include: ```text knowledge_assets/README.md knowledge_assets/10_本地CCRA评审机制说明.md ``` Other files under `knowledge_assets/` are treated as durable review protocol, product context, model governance rules, and handoff knowledge. Per-round evidence still belongs in reports, review bundles, or `local_ccra_reviews///`. ## 5. Minimal Setup Sequence 1. Choose an existing Round 03 or Round 04 evidence set for pilot. 2. Create the run directory and `helper-outputs/`. 3. Write `review-metadata.json` with review goal, non-goals, open questions, target reviewer, and helper policies. 4. Write `lifecycle-guard-config.yaml`. 5. Write `gate-manifest.yaml` when validation gates are in scope and choose `gate_execution_mode`. 6. Run applicable helper Skills according to the declared bundle audit profile, gate execution mode, routing diff policy, and lifecycle scan scope. 7. Fill `agent-invocation-packet.md` from `ccra-local-review-invocation-packet.template.md` with `turn_type: review_turn`. 8. Write `turn-prompts/review-turn.prompt.md`. 9. Invoke a real child session or equivalent isolated participant as `ccra-local-reviewer`. 10. Save the returned long report as `04_LOCAL_CCRA_REVIEW_REPORT.md` and the compact Owner-facing summary as `returned-output.md`. 11. Record Owner decisions in `owner-decision.md` when available. 12. If the Owner asks for next-review planning, continue the same child session with `turn_type: planning_turn`. 13. Save the planning output as `next-review-requirements.md`. ## 6. Helper Command Templates Run these from any working directory by using absolute installed script paths. ### 6.1 Review Context Builder ```powershell conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\review-context-builder\scripts\review_context_builder.py ` --project-root C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong ` --review-id - ` --context-profile ccra-local-review ` --source-root README.md ` --source-root AGENTS.md ` --source-root PROJECTS.md ` --source-root knowledge_assets ` --source-root ` --metadata \review-metadata.json ` --output-dir ``` Outputs: ```text /review-context.md /review-file-manifest.json ``` ### 6.2 Review Bundle Audit Preferred CCRA-aware profile contract: ```text profile_id: ccra_mindscape_review_bundle recognized_manifest_patterns: - BUNDLE_FILE_MANIFEST_*.md - BUNDLE_FILE_MANIFEST_*.json recognized_round_suffix_examples: - 04 - 04.1 validation_sidecar: optional unless the review packet declares one as required generic_profile_mismatch_blocks_review: no required_report_fields: active_profile recognized_manifest_path missing_required_files extra_files_or_profile_warnings blocks_current_review ``` If the installed helper does not yet implement `ccra_mindscape_review_bundle`, run the closest available helper profile and record the result as `generic` plus `profile_mismatch`; the reviewer must then apply the profile contract above manually. ```powershell conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\review-bundle-audit\scripts\review_bundle_audit.py ` --bundle-root ` --output-dir \helper-outputs ` --profile ccra_mindscape_review_bundle ``` If this exits with a profile-not-found or profile-unsupported error, rerun with `--profile generic`, record `active_profile: generic`, and mark `profile_mismatch: true` in `run-notes.md` and the report. Generic-profile output is then preflight evidence, not automatic bundle failure. Outputs: ```text /helper-outputs/bundle-audit.md /helper-outputs/bundle-audit.json ``` ### 6.3 Routing Behavior Diff Audit Run only when before/after selector, QPI, routing, or regression result files exist. Routing diff is mandatory for patch verification when before/after evidence exists. It may be skipped for an initial no-hindsight `review_turn` only when no after-patch material is in scope and the skip reason is recorded as `skipped_no_after_evidence`. If the helper cannot run when before/after evidence exists, provide a manual equivalent table with: ```text target_behavior_changes non_target_behavior_changes accepted_collateral_changes unexpected_regressions unchanged_expected_behavior cases_needing_owner_or_web_calibration ``` ```powershell conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\routing-behavior-diff-audit\scripts\routing_behavior_diff_audit.py ` --before-results ` --after-results ` --output-dir \helper-outputs ` --case-id-field case_id ` --route-field route ` --expected-route-field expected_route ``` Add repeatable `--targeted-case ` when the reviewed patch intentionally targets specific cases. Outputs: ```text /helper-outputs/routing-behavior-diff.md /helper-outputs/routing-behavior-diff.json ``` ### 6.4 Regression Validation Gate Runner Choose mode from `gate_execution_mode`: ```text dry_run: allowed for planning and manifest readability only. cannot support pass claims. run: allowed only with Owner approval or explicit run authorization. executed command logs and exit codes may support pass claims. owner_waived: do not run gates. record Owner waiver as evidence limitation. not_applicable: use only when reviewed material has no executable gates in scope. ``` ```powershell conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\regression-validation-gate-runner\scripts\regression_validation_gate_runner.py ` --project-root C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong ` --gate-manifest \gate-manifest.yaml ` --output-dir \helper-outputs ` --mode ``` Use `--mode run` only after the Owner approves executing the declared gates. For `owner_waived` or `not_applicable`, skip the command and record the reason in `run-notes.md`. Outputs: ```text /helper-outputs/gate-run-report.md /helper-outputs/gate-run-report.json /helper-outputs/logs/ ``` ### 6.5 Lifecycle Status Guard Scan Declare one scope mode before running: ```text current_review_bundle: default for formal review_turn when the submitted review package is being judged. changed_files: use for patch verification or local tuning passes. knowledge_assets: use when durable CCRA/product knowledge itself is being reviewed. model_library_state: use when lifecycle/status claims in cards, models, indexes, or reports are the target. whole_repo: broad audit mode only. not default blocker mode. ``` Recommended defaults: ```text review_turn: current_review_bundle or model_library_state, depending on scope planning_turn: not_applicable unless planning itself references lifecycle claims comparison_turn: current_review_bundle or changed_files, limited to compared evidence ``` Every finding must be triaged before it blocks review readiness: ```text current_scope_blocker owner_decision_needed historical_or_archive_noise policy_reference_not_claim false_positive_or_low_confidence ``` ```powershell conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\lifecycle-status-guard-scan\scripts\lifecycle_status_guard_scan.py ` --scan-root C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong ` --config \lifecycle-guard-config.yaml ` --output-dir \helper-outputs ``` Outputs: ```text /helper-outputs/lifecycle-status-guard-scan.md /helper-outputs/lifecycle-status-guard-scan.json ``` ## 7. Minimal Config Stubs ### 7.1 review-metadata.json ```json { "review_goal": "Check whether the selected round evidence is ready for Local CCRA judgment.", "turn_type": "review_turn", "non_goals": [ "Do not decide Owner approval.", "Do not replace Web CCRA final review.", "Do not promote lifecycle status." ], "open_questions": [ "Was a real child session invoked?", "Can the child session be resumed?", "Does report quality reach Web CCRA level?" ], "target_reviewer": "ccra-local-reviewer", "bundle_audit_profile": "ccra_mindscape_review_bundle", "gate_execution_mode": "dry_run", "routing_diff_policy": "skipped_no_after_evidence", "lifecycle_scan_scope": "current_review_bundle" } ``` ### 7.2 Same-Child-Session Turn Protocol Patch 1 defines three turn types: ```text review_turn: output: 04_LOCAL_CCRA_REVIEW_REPORT.md purpose: judge current material, diagnose mechanisms, classify findings, and recommend next action. planning_turn: output: next-review-requirements.md purpose: plan next review requirements and submitted materials after the review report. continuity: must use the same child_session_id when possible. comparison_turn: output: 05_WEB_LOCAL_CCRA_COMPARISON.md or project-defined comparison path purpose: compare Local CCRA with Web CCRA/GPT feedback when Owner asks. ``` For a planning turn, the prompt must provide: ```text same child_session_id 04_LOCAL_CCRA_REVIEW_REPORT.md owner-decision.md when present next review target planning output path: next-review-requirements.md ``` The planning turn must not re-review the full current bundle unless new evidence was added or the Owner explicitly asks for re-review. ### 7.3 lifecycle-guard-config.yaml ```yaml watched_paths: - "**/*.md" - "**/*.json" - "**/*.yaml" - "**/*.yml" status_fields: - status - lifecycle - model.status - model.lifecycle forbidden_status_values: - stable - accepted - owner-approved - ccra-approved warning_status_values: - candidate - ready-for-review required_evidence_markers: - owner_decision - owner decision - ccra_review - ccra review - web ccra approved_phrases: - owner-approved - ccra-approved - Owner approved - CCRA approved forbidden_phrases: - production-ready - released to production - final approved allowed_contexts: - do not say - must not claim - example: evidence_window_chars: 240 ``` ### 7.4 gate-manifest.yaml Use project-owned commands only. This stub is intentionally empty until the client project fills it. ```yaml gates: [] ``` `gate_execution_mode` is declared in `review-metadata.json` or the invocation packet, not inferred from the helper exit code. ## 7.5 returned-output.md Keep the long report for traceability, but return this compact shape to the main project session: ```text # Returned Output - review_round: - local_pass: - turn_type: - child_session_id: - main_conclusion: - final_action_recommendation: - blocks_web_review: yes/no - blocks_owner_acceptance: yes/no - required_next_action: ## Output Paths - review_report: - planning_output: - comparison_output: ## Evidence Limitations - gate_execution_mode: - bundle_audit_profile: - routing_diff_policy: - lifecycle_scan_scope: - limitations: ``` ## 8. Invocation Packet Create: ```text /agent-invocation-packet.md ``` Use: ```text C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review-invocation-packet.template.md ``` The packet must identify: ```text canonical Agent path canonical Runtime path knowledge base path: C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\knowledge_assets review run directory turn_type and turn output path input files and review bundle paths helper outputs available or skipped bundle audit profile and recognized manifest path gate execution mode routing diff policy lifecycle scan scope output report path child-session carrier no-simulation requirement continuity policy ``` ## 9. Pilot Acceptance Checks The first pilot should answer: ```text Was a real child session or equivalent isolated participant invoked? Can the child session be resumed for tuning? Did helper outputs support file-first review rather than replace judgment? Did the Local CCRA report reach Web CCRA quality for practical tuning? What Agent, Runtime, config, or helper definitions need repair before Round 05? ``` Do not treat the pilot as Round 05 acceptance.