# 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
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.
- `owner-decision.md`: accepted, rejected, deferred, or escalated findings.

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

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/<round>/<pass>/
-> 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
-> 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.

## 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.
- Store canonical CCPE artifacts in this repository.
- Store reusable Skill source in this repository.
