15 KiB

Raw Blame History

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:

C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong

Local CCRA uses the same project knowledge base that supports Web CCRA:

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

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

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:

conda run -n skills-vault python -B

4. Project Run Directory

Create a run directory inside the client project:

local_ccra_reviews/<round>/<local-pass>/

Recommended pilot examples:

local_ccra_reviews/round-03/pilot-01/
local_ccra_reviews/round-04/pilot-01/

Expected layout:

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:

C:\Users\wangq\Documents\Codex\work-projects\the-mindscape-of-bro-tsong\knowledge_assets

Minimum expected files include:

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

Choose an existing Round 03 or Round 04 evidence set for pilot.
Create the run directory and helper-outputs/.
Write review-metadata.json with review goal, non-goals, open questions, target reviewer, and helper policies.
Write lifecycle-guard-config.yaml.
Write gate-manifest.yaml when validation gates are in scope and choose gate_execution_mode.
Run applicable helper Skills according to the declared bundle audit profile, gate execution mode, routing diff policy, and lifecycle scan scope.
Fill agent-invocation-packet.md from ccra-local-review-invocation-packet.template.md with turn_type: review_turn.
Write turn-prompts/review-turn.prompt.md.
Invoke a real child session or equivalent isolated participant as ccra-local-reviewer.
Save the returned long report as 04_LOCAL_CCRA_REVIEW_REPORT.md and the compact Owner-facing summary as returned-output.md.
Record Owner decisions in owner-decision.md when available.
If the Owner asks for next-review planning, continue the same child session with turn_type: planning_turn.
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

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:

<run-dir>/review-context.md
<run-dir>/review-file-manifest.json

6.2 Review Bundle Audit

Preferred CCRA-aware profile contract:

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.

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:

<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:

target_behavior_changes
non_target_behavior_changes
accepted_collateral_changes
unexpected_regressions
unchanged_expected_behavior
cases_needing_owner_or_web_calibration

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:

<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:

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.

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:

<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:

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:

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:

current_scope_blocker
owner_decision_needed
historical_or_archive_noise
policy_reference_not_claim
false_positive_or_low_confidence

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:

<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

{
  "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:

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:

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

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.

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:

# 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:

<run-dir>/agent-invocation-packet.md

Use:

C:\Users\wangq\Documents\Codex\ccpe-system\runtimes\hybrid\ccra-local-review-invocation-packet.template.md

The packet must identify:

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:

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.

15 KiB Raw Blame History

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

2. Required CCPE Files

3. Required Installed Skills

4. Project Run Directory

4.1 Required Knowledge Base

5. Minimal Setup Sequence

6. Helper Command Templates

6.1 Review Context Builder

6.2 Review Bundle Audit

6.3 Routing Behavior Diff Audit

6.4 Regression Validation Gate Runner

6.5 Lifecycle Status Guard Scan

7. Minimal Config Stubs

7.1 review-metadata.json

7.2 Same-Child-Session Turn Protocol

7.3 lifecycle-guard-config.yaml

7.4 gate-manifest.yaml

7.5 returned-output.md

8. Invocation Packet

9. Pilot Acceptance Checks

15 KiB

Raw Blame History