202 lines
9.0 KiB
Markdown
202 lines
9.0 KiB
Markdown
# 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.
|