352 lines
12 KiB
Markdown
352 lines
12 KiB
Markdown
---
|
|
artifact_type: integration-registration
|
|
name: CCRA Local Review Skills-Vault Helpers
|
|
integration_id: ccra-local-review-skills-vault-helpers
|
|
integration_type: skills-vault-automation-skills
|
|
author: CCPE System
|
|
version: 0.1.2
|
|
created: 2026-06-19
|
|
updated: 2026-06-19
|
|
status: active
|
|
used_by:
|
|
- agents/agent-specs/ccra-local-reviewer.agent.md
|
|
- runtimes/hybrid/ccra-local-review.runtime.md
|
|
---
|
|
|
|
# CCRA Local Review Skills-Vault Helpers
|
|
|
|
## 1. Registration Scope
|
|
|
|
This registration records the installed `skills-vault` automation Skills used by the `ccra-local-review` Runtime.
|
|
|
|
CCPE owns the Agent, Runtime, evaluation rules, authority boundaries, and integration contract.
|
|
|
|
`skills-vault` owns the automation Skill source, scripts, fixtures, tests, install notes, and runtime install package.
|
|
|
|
The client project owns concrete run directories, helper configs, returned reports, Owner decisions, and review evidence.
|
|
|
|
## 2. Registered Skills
|
|
|
|
```text
|
|
review-context-builder:
|
|
source_path: C:\Users\wangq\Documents\Codex\skills-vault\skills\review-context-builder
|
|
installed_path: C:\Users\wangq\.agents\skills\review-context-builder
|
|
script: scripts\review_context_builder.py
|
|
primary_outputs: review-context.md, review-file-manifest.json
|
|
runtime_stage: Stage 1 context preparation
|
|
|
|
review-bundle-audit:
|
|
source_path: C:\Users\wangq\Documents\Codex\skills-vault\skills\review-bundle-audit
|
|
installed_path: C:\Users\wangq\.agents\skills\review-bundle-audit
|
|
script: scripts\review_bundle_audit.py
|
|
primary_outputs: bundle-audit.md, bundle-audit.json
|
|
runtime_stage: Stage 1 bundle preflight
|
|
|
|
routing-behavior-diff-audit:
|
|
source_path: C:\Users\wangq\Documents\Codex\skills-vault\skills\routing-behavior-diff-audit
|
|
installed_path: C:\Users\wangq\.agents\skills\routing-behavior-diff-audit
|
|
script: scripts\routing_behavior_diff_audit.py
|
|
primary_outputs: routing-behavior-diff.md, routing-behavior-diff.json
|
|
runtime_stage: Stage 1 routing-diff evidence
|
|
|
|
regression-validation-gate-runner:
|
|
source_path: C:\Users\wangq\Documents\Codex\skills-vault\skills\regression-validation-gate-runner
|
|
installed_path: C:\Users\wangq\.agents\skills\regression-validation-gate-runner
|
|
script: scripts\regression_validation_gate_runner.py
|
|
primary_outputs: gate-run-report.md, gate-run-report.json, logs/
|
|
runtime_stage: Stage 1 validation evidence
|
|
|
|
lifecycle-status-guard-scan:
|
|
source_path: C:\Users\wangq\Documents\Codex\skills-vault\skills\lifecycle-status-guard-scan
|
|
installed_path: C:\Users\wangq\.agents\skills\lifecycle-status-guard-scan
|
|
script: scripts\lifecycle_status_guard_scan.py
|
|
primary_outputs: lifecycle-status-guard-scan.md, lifecycle-status-guard-scan.json
|
|
runtime_stage: Stage 1 lifecycle overclaim scan
|
|
```
|
|
|
|
## 3. Invocation Authority
|
|
|
|
Allowed operations:
|
|
|
|
```text
|
|
read configured project files or bundle files
|
|
read configured JSON/YAML/Markdown manifests
|
|
write reports and logs to the configured Local CCRA run directory
|
|
execute only user-approved validation gate commands declared in a manifest
|
|
record helper command, input, output, exit code, and skipped/failed state in run-notes.md or a Skill execution record
|
|
```
|
|
|
|
Forbidden operations:
|
|
|
|
```text
|
|
edit project files
|
|
repair review bundles
|
|
modify model cards, model JSON, selector rules, regression cases, or lifecycle status
|
|
install dependencies
|
|
invent validation commands
|
|
claim Owner approval, Web CCRA approval, lifecycle promotion, or release readiness
|
|
replace Local CCRA Agent judgment
|
|
```
|
|
|
|
## 4. Command Templates
|
|
|
|
Run installed scripts through the shared `skills-vault` environment.
|
|
|
|
```powershell
|
|
conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\review-context-builder\scripts\review_context_builder.py `
|
|
--project-root <client-project-root> `
|
|
--review-id <review-id> `
|
|
--context-profile ccra-local-review `
|
|
--source-root knowledge_assets `
|
|
--source-root <file-or-directory> `
|
|
--metadata <run-dir>\review-metadata.json `
|
|
--output-dir <run-dir>
|
|
|
|
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
|
|
|
|
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> `
|
|
--after-results <after-results> `
|
|
--output-dir <run-dir>\helper-outputs `
|
|
--case-id-field case_id `
|
|
--route-field route
|
|
|
|
conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\regression-validation-gate-runner\scripts\regression_validation_gate_runner.py `
|
|
--project-root <client-project-root> `
|
|
--gate-manifest <run-dir>\gate-manifest.yaml `
|
|
--output-dir <run-dir>\helper-outputs `
|
|
--mode dry_run
|
|
|
|
conda run -n skills-vault python -B C:\Users\wangq\.agents\skills\lifecycle-status-guard-scan\scripts\lifecycle_status_guard_scan.py `
|
|
--scan-root <client-project-root> `
|
|
--config <run-dir>\lifecycle-guard-config.yaml `
|
|
--output-dir <run-dir>\helper-outputs
|
|
```
|
|
|
|
If `review-bundle-audit` does not support `ccra_mindscape_review_bundle`, rerun that helper with `--profile generic`, mark `profile_mismatch`, and apply the CCRA profile contract manually before deciding whether the bundle blocks review.
|
|
|
|
Use `regression-validation-gate-runner --mode run` only after the user explicitly approves running the declared gate commands.
|
|
|
|
### 4.1 CCRA-Aware Profile And Execution Contracts
|
|
|
|
`review-bundle-audit` profile contract:
|
|
|
|
```text
|
|
profile_id: ccra_mindscape_review_bundle
|
|
recognized_manifest_patterns:
|
|
- BUNDLE_FILE_MANIFEST_*.md
|
|
- BUNDLE_FILE_MANIFEST_*.json
|
|
examples:
|
|
- BUNDLE_FILE_MANIFEST_04.md
|
|
- BUNDLE_FILE_MANIFEST_04.1.md
|
|
validation_sidecar_required: profile-dependent
|
|
validation_sidecar_absent_when_optional: profile_warning | not_applicable
|
|
generic_profile_mismatch_is_blocker: no
|
|
required_output_interpretation:
|
|
active_profile
|
|
recognized_manifest_path
|
|
missing_required_files
|
|
extra_files_or_profile_warnings
|
|
blocks_current_review
|
|
```
|
|
|
|
If the installed helper lacks this profile, the runtime may run `generic` as a fallback, but the Local CCRA report must mark `profile_mismatch` and apply the contract above before deciding whether the bundle actually blocks review.
|
|
|
|
`regression-validation-gate-runner` execution contract:
|
|
|
|
```text
|
|
gate_execution_mode:
|
|
dry_run:
|
|
planning/preflight only
|
|
cannot support pass claims
|
|
run:
|
|
requires Owner or explicit runtime approval
|
|
may support pass claims only with executed logs and exit codes
|
|
owner_waived:
|
|
command skipped by Owner decision
|
|
report as evidence limitation
|
|
not_applicable:
|
|
no executable gates in scope
|
|
```
|
|
|
|
`routing-behavior-diff-audit` requirement contract:
|
|
|
|
```text
|
|
review_turn_without_after_patch_evidence:
|
|
may_skip_with_reason: skipped_no_after_evidence
|
|
|
|
patch_verification_or_comparison_with_before_after:
|
|
helper_required: yes
|
|
fallback_if_helper_missing: manual_equivalent_table
|
|
required_categories:
|
|
- target_behavior_changes
|
|
- non_target_behavior_changes
|
|
- accepted_collateral_changes
|
|
- unexpected_regressions
|
|
- unchanged_expected_behavior
|
|
- cases_needing_owner_or_web_calibration
|
|
```
|
|
|
|
`lifecycle-status-guard-scan` scope contract:
|
|
|
|
```text
|
|
scope_modes:
|
|
- current_review_bundle
|
|
- changed_files
|
|
- knowledge_assets
|
|
- model_library_state
|
|
- whole_repo
|
|
|
|
default_blocker_mode:
|
|
current_review_bundle
|
|
changed_files
|
|
model_library_state
|
|
|
|
whole_repo:
|
|
broad_audit_mode: true
|
|
not_default_blocker_mode: true
|
|
|
|
triage_categories:
|
|
- current_scope_blocker
|
|
- owner_decision_needed
|
|
- historical_or_archive_noise
|
|
- policy_reference_not_claim
|
|
- false_positive_or_low_confidence
|
|
```
|
|
|
|
## 5. Failure Behavior
|
|
|
|
Missing installed Skill:
|
|
|
|
```text
|
|
block Stage 1 helper execution
|
|
record missing path in run-notes.md
|
|
continue only if the Local CCRA reviewer can manually inspect equivalent evidence and the report states the missing automation risk
|
|
```
|
|
|
|
Helper exit codes:
|
|
|
|
```text
|
|
review-bundle-audit:
|
|
0 no blockers
|
|
1 audit blockers
|
|
2 input or profile errors
|
|
|
|
routing-behavior-diff-audit:
|
|
use machine_readable_summary.status as automation routing evidence only
|
|
|
|
regression-validation-gate-runner:
|
|
0 PASS or DRY_RUN
|
|
1 required gate failure or timeout
|
|
2 manifest or input errors
|
|
|
|
lifecycle-status-guard-scan:
|
|
0 warnings or observations only
|
|
1 blocking lifecycle/status findings
|
|
```
|
|
|
|
Any helper failure may become a Local CCRA finding, but the helper itself does not decide review acceptance.
|
|
|
|
## 6. Helper Output Confidence
|
|
|
|
Local CCRA must classify helper output confidence before using helper reports in findings.
|
|
|
|
```text
|
|
confidence:
|
|
high:
|
|
helper profile matches the review package
|
|
inputs are current
|
|
required command mode was executed
|
|
output is specific to the reviewed evidence
|
|
|
|
medium:
|
|
helper output is useful but incomplete
|
|
helper found warnings requiring reviewer judgment
|
|
some optional evidence was skipped
|
|
|
|
low:
|
|
helper used a generic profile against project-specific bundle names
|
|
output may be stale
|
|
output is dry_run when executed validation is needed
|
|
helper findings look like false-positive candidates
|
|
|
|
not_used:
|
|
helper was unavailable, skipped, or not applicable
|
|
```
|
|
|
|
Mandatory confidence flags:
|
|
|
|
```text
|
|
used_as_evidence
|
|
stale
|
|
generic_profile
|
|
profile_mismatch
|
|
false_positive_candidate
|
|
dry_run
|
|
executed
|
|
planned
|
|
waived
|
|
missing_helper
|
|
skipped_but_should_have_run
|
|
broad_scope_noise
|
|
active_profile
|
|
recognized_manifest_path
|
|
blocks_current_review
|
|
requires_runtime_tuning
|
|
```
|
|
|
|
Known Patch 1 examples:
|
|
|
|
```text
|
|
review-bundle-audit:
|
|
generic profile may not recognize versioned bundle manifests such as BUNDLE_FILE_MANIFEST_04.md.
|
|
|
|
regression-validation-gate-runner:
|
|
dry_run proves command declaration readability, not fresh validation execution.
|
|
|
|
routing-behavior-diff-audit:
|
|
should run when before/after routing evidence exists.
|
|
|
|
lifecycle-status-guard-scan:
|
|
broad findings require reviewer triage before becoming blockers.
|
|
```
|
|
|
|
Known Patch 2 examples:
|
|
|
|
```text
|
|
review-bundle-audit:
|
|
generic profile exit 1 may be a profile mismatch when `BUNDLE_FILE_MANIFEST_04.md` is present and recognized by the CCRA profile contract.
|
|
|
|
regression-validation-gate-runner:
|
|
`dry_run` is useful for planning but cannot support a final validation pass claim.
|
|
|
|
routing-behavior-diff-audit:
|
|
skipped is acceptable for no-hindsight initial evidence; missing is an evidence gap when before/after patch evidence exists.
|
|
|
|
lifecycle-status-guard-scan:
|
|
broad whole-repo findings from older review materials or prior helper outputs must be triaged as archive noise, policy reference, false positive, or current-scope blocker.
|
|
```
|
|
|
|
## 7. Validation And Evidence
|
|
|
|
Observed local install surface:
|
|
|
|
```text
|
|
C:\Users\wangq\.agents\skills\review-context-builder\SKILL.md
|
|
C:\Users\wangq\.agents\skills\review-bundle-audit\SKILL.md
|
|
C:\Users\wangq\.agents\skills\routing-behavior-diff-audit\SKILL.md
|
|
C:\Users\wangq\.agents\skills\regression-validation-gate-runner\SKILL.md
|
|
C:\Users\wangq\.agents\skills\lifecycle-status-guard-scan\SKILL.md
|
|
```
|
|
|
|
Supplier validation remains owned by `skills-vault`. CCPE consumers should verify path availability before each formal Local CCRA run and record command results in the project run directory.
|
|
|
|
## 8. Security Notes
|
|
|
|
These helpers are read-heavy deterministic tools except `regression-validation-gate-runner`, which can execute manifest commands in `run` mode. Treat `run` mode as a human-gated action.
|
|
|
|
The helpers may write only inside the configured output directory. They must not write Owner decisions, Local CCRA reports, lifecycle promotions, or Web final review conclusions.
|