529 lines
15 KiB
Markdown
529 lines
15 KiB
Markdown
---
|
|
---
|
|
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/<round>/<local-pass>/
|
|
```
|
|
|
|
Recommended pilot examples:
|
|
|
|
```text
|
|
local_ccra_reviews/round-03/pilot-01/
|
|
local_ccra_reviews/round-04/pilot-01/
|
|
```
|
|
|
|
Expected layout:
|
|
|
|
```text
|
|
local_ccra_reviews/<round>/<local-pass>/
|
|
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/<round>/<local-pass>/`.
|
|
|
|
## 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 <round>-<local-pass> `
|
|
--context-profile ccra-local-review `
|
|
--source-root README.md `
|
|
--source-root AGENTS.md `
|
|
--source-root PROJECTS.md `
|
|
--source-root knowledge_assets `
|
|
--source-root <review-bundle-or-report-dir> `
|
|
--metadata <run-dir>\review-metadata.json `
|
|
--output-dir <run-dir>
|
|
```
|
|
|
|
Outputs:
|
|
|
|
```text
|
|
<run-dir>/review-context.md
|
|
<run-dir>/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 <review-bundle-dir> `
|
|
--output-dir <run-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
|
|
<run-dir>/helper-outputs/bundle-audit.md
|
|
<run-dir>/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 <before-results-file-or-dir> `
|
|
--after-results <after-results-file-or-dir> `
|
|
--output-dir <run-dir>\helper-outputs `
|
|
--case-id-field case_id `
|
|
--route-field route `
|
|
--expected-route-field expected_route
|
|
```
|
|
|
|
Add repeatable `--targeted-case <case-id>` when the reviewed patch intentionally targets specific cases.
|
|
|
|
Outputs:
|
|
|
|
```text
|
|
<run-dir>/helper-outputs/routing-behavior-diff.md
|
|
<run-dir>/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 <run-dir>\gate-manifest.yaml `
|
|
--output-dir <run-dir>\helper-outputs `
|
|
--mode <dry_run|run>
|
|
```
|
|
|
|
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
|
|
<run-dir>/helper-outputs/gate-run-report.md
|
|
<run-dir>/helper-outputs/gate-run-report.json
|
|
<run-dir>/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 <run-dir>\lifecycle-guard-config.yaml `
|
|
--output-dir <run-dir>\helper-outputs
|
|
```
|
|
|
|
Outputs:
|
|
|
|
```text
|
|
<run-dir>/helper-outputs/lifecycle-status-guard-scan.md
|
|
<run-dir>/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
|
|
<run-dir>/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.
|