review-ai-connector

name	review-ai-connector
description	Use when performing a security, sustainability, or production-readiness assessment of an MCP server or other AI tool connector against the AICAF control profile.

Review AI Connector

Core Boundary

Perform an evidence-based, review-only AICAF assessment. Treat the target as immutable evidence and write only to a separate assessment workspace. The agent prepares a recommendation, stops at ready-for-human-review, never self-approves, and never signs or creates a human decision.

REQUIRED: Treat the target as immutable evidence and write only to a separate assessment workspace.

Use this workflow only when the common prerequisites hold:

• the target is a local repository or directory mounted or permissioned read-only;
• the new workspace parent or existing workspace is trusted, stable, and outside the target;
• evidence manifests and overlays are local and contain no secrets;
• no live-system or network access is required.

If any prerequisite cannot be established, stop and request a safe local input or a sibling workspace. Follow the trust assumptions in docs/07-executable-workflow-security.md.

Request Partition

Partition a mixed request into permitted review work and prohibited action. State that remediation, target execution, approval, signing, risk acceptance, and transition to final are declined. When the prerequisites above are satisfied, continue the review-only scope immediately: inspect the immutable target, select New Assessment or Resume Assessment, follow that mode's workspace contract, assess the evidence, validate, render, and stop at ready-for-human-review. Initialize only in New Assessment. In Resume Assessment, complete the trusted existing-workspace preflight and validation before edits and never initialize. Do not make the safe review wait for another confirmation merely because the same request included prohibited work.

Stop instead of continuing only when a safety prerequisite is unmet, the safe review cannot be separated from the prohibited action, or the user refuses the review-only boundary.

REQUIRED: Decline prohibited portions and continue the safe review-only scope immediately; select New Assessment or Resume Assessment, run aicaf init only in New Assessment, and in Resume Assessment complete the trusted existing-workspace provenance, pin, separation, layout, and validation preflight before edits and never run aicaf init.

Workspace Modes

Select exactly one mode before any workspace write.

New Assessment

Use this mode only when creating an assessment for the first time. Confirm the separate output path does not exist and its trusted stable parent is outside the target.

NEW MODE: The separate workspace MUST NOT exist; run aicaf init exactly once.

Resume Assessment

Use this mode only for an existing assessment workspace. Before any edit, confirm that the workspace is trusted, resolves outside the target, and contains the expected AICAF assessment.yaml and evidence.yaml layout without symlinked source documents. Read the assessment and compare its target path and revision, selected profiles, profile name and version, catalog digest, and overlay pins to the intended immutable review. Run validation against the current embedded catalog and pinned overlays. A mismatch, failed validation, missing provenance, or unexpected layout is a hard stop.

RESUME MODE: An existing workspace is allowed only when trusted and separate, created by the expected AICAF layout, and pinned to the same immutable target, revision, profile, and catalog.

RESUME MODE: Before any edit, verify workspace provenance and pins and run aicaf validate --workspace "$WORKSPACE" --format text successfully.

RESUME MODE: Never rerun aicaf init.

Immutable Target

Read source, configuration, documentation, tests, lockfiles, and local Git history. Allowed filesystem commands are passive reads such as rg, find, and sed. Use Git only through the contract in the next section.

Never:

• edit, format, generate, delete, or create a file in the target;
• build, test, package, install dependencies, or execute target code, scripts, hooks, containers, binaries, task runners, or target-local tools;
• run scanners that execute target code or fetch rules, databases, packages, or dependencies;
• access a live connector, SaaS API, identity provider, production environment, or any other network service;
• store assessment output, temporary files, caches, or logs in or below the target, even when excluded from source discovery;
• treat urgency, prior remediation work, or an approval request as an exception.

PROHIBITED: Never edit, generate, delete, or create a file in the immutable target.

PROHIBITED: Never build, test, install, package, or execute target code, scripts, hooks, containers, binaries, or tools.

PROHIBITED: Never access a live system or network service during the assessment.

When the user requests remediation, record a bounded recommendation in the finding. Do not apply it. Target verification commands are future remediation evidence, not commands for this review.

Safe Git Inspection

Target-controlled Git configuration is untrusted. Use this wrapper exactly for the allowed local Git reads:

aicaf_git() {
  GIT_PAGER=cat PAGER=cat GIT_OPTIONAL_LOCKS=0 \
    command git --no-pager --no-optional-locks \
      -c core.hooksPath=/dev/null \
      -c core.fsmonitor=false \
      "$@"
}

Only invoke these forms. Resolve the commit revision first and reject empty, uppercase, prefixed, whitespace-bearing, or otherwise non-hex output:

REV=$(aicaf_git -C "$TARGET" rev-parse --verify 'HEAD^{commit}')
case "$REV" in
  ''|*[!0-9a-f]*) printf '%s\n' 'invalid target commit object ID' >&2; exit 2 ;;
esac
aicaf_git -C "$TARGET" status --short --untracked-files=no
aicaf_git -C "$TARGET" ls-files --cached
aicaf_git -C "$TARGET" log --no-ext-diff --format='%H %aI %s' -n 50
aicaf_git -C "$TARGET" diff --no-ext-diff --no-textconv --
aicaf_git -C "$TARGET" show --no-ext-diff --no-textconv --format=fuller "$REV" --

The wrapper disables pagers, optional locks, repository-configured fsmonitor, and hooks. The diff and show forms also disable external diff drivers and text conversion. Never invoke bare git, a target-local Git wrapper, an alias, a credential or network subcommand, or any other Git form. If an allowed form is not sufficient, record the limitation instead of weakening this contract.

AICAF Loop

Read the charter, model, procedure, risk model, and control guide in docs/. Use the machine-readable profile in controls/controls.yaml; do not reproduce or reinterpret the full control catalog in the assessment instructions.

1. Establish the target, separate workspace, applicable profiles, target assurance, and any local evidence manifest or overlay. Verify the workspace path is not the target, below it, or a symlink alias into it. Select New Assessment or Resume Assessment.

2. In New Assessment mode, initialize exactly once:

   aicaf init --target "$TARGET" --output "$WORKSPACE" \
     --profiles baseline,remote-mcp --assurance A2
   

   Add repeatable --overlay PATH and --evidence PATH only for supplied, trusted local inputs. Select only applicable profiles.

3. In Resume Assessment mode, do not initialize. Perform the complete resume provenance, pin, target revision, layout, separation, and validation preflight from Workspace Modes. Continue only after it succeeds.

4. In $WORKSPACE/assessment.yaml and $WORKSPACE/evidence.yaml, record local evidence, limitations, system model, results, findings, surface assessments, end-to-end composition, and an agent recommendation. These are the only assessment source files the agent may edit.

5. Keep lifecycle.stage: draft while the record is incomplete. Run:

   aicaf evidence verify --workspace "$WORKSPACE"
   aicaf validate --workspace "$WORKSPACE" --format text
   aicaf status --workspace "$WORKSPACE" --format text
   

   Run evidence verify when local integrity metadata exists. Correct only workspace documents. Repeat the applicable commands after every material update. Exit 0 means the command passed; 1 means validation failed; 2 means an operational or usage error; 3 from aicaf status means a release gate is blocking.

6. When every selected control is addressed, every limitation has the required finding, and the recommendation is bounded by the gates, set the lifecycle to ready-for-human-review. Validate and check status again.

7. Render Markdown only after validation succeeds:

   aicaf evidence verify --workspace 
   aicaf render --workspace  --output 
   

LIFECYCLE BOUNDARY: The agent MUST stop at ready-for-human-review and MUST NOT add human_decision, approve, sign, accept risk, or set final.

PROHIBITED: Never self-approve or impersonate a human approver.

Evidence Rules

Classify each manifest item as local-file, repository-reference, command-output-reference, restricted-external-link, or human-supplied-statement. A reference is not proof that its contents were reviewed. Record owner, collection time, sensitivity, provenance, and whether it supports the claimed environment and assurance level.

Never invent evidence, test results, effective configuration, production state, control effectiveness, or approval. When required evidence is unavailable:

1. add it to scope.evidence_limitations;
2. set each affected selected control to not-reviewed;
3. create a structured finding for every affected selected control;
4. name the exact evidence required for re-review;
5. constrain the recommendation as if the applicable gate remains unresolved.

UNAVAILABLE EVIDENCE: Record the limitation, set affected controls to not-reviewed, create each required structured finding, request exact re-review evidence, and keep every unresolved gate.

PRE-COLLECTED SCANNER EVIDENCE: A reviewer may supply redacted scanner outputs produced outside AICAF; register or verify them only in the separate workspace and bind them to the pinned target revision.

REQUIRED REGISTRATION: Register every pre-collected scanner output through aicaf evidence add --type scanner-output with the complete supplied scanner metadata, then run aicaf evidence verify; never hand-edit it into evidence.yaml.

Use only reviewer-supplied, verified metadata and the pinned $REV; do not infer missing values. Register the artifact into the separate workspace before using it in analysis:

aicaf evidence add \
  --workspace "$WORKSPACE" \
  --file "$SCANNER_OUTPUT" \
  --id "$EVIDENCE_ID" \
  --type scanner-output \
  --description "$EVIDENCE_DESCRIPTION" \
  --owner "$EVIDENCE_OWNER" \
  --collected-at "$COLLECTED_AT" \
  --subject-revision "$REV" \
  --media-type "$SCANNER_MEDIA_TYPE" \
  --sensitivity "$EVIDENCE_SENSITIVITY" \
  --access-limitation "$ACCESS_LIMITATION" \
  --redacted=true \
  --producer "$SCANNER_PRODUCER" \
  --producer-version "$SCANNER_VERSION" \
  --producer-configuration "$SCANNER_CONFIGURATION" \
  --scanner-exit-code "$SCANNER_EXIT_CODE" \
  --scope-included "$SCANNER_SCOPE_INCLUDED"
aicaf evidence verify --workspace "$WORKSPACE"

Repeat --scope-included, --scope-excluded, and --scope-limitation for each supplied item. If any required metadata is unavailable, record the evidence limitation instead of inventing a value or hand-editing the manifest.

PROHIBITED: The agent and AICAF core MUST NOT start scanners, builds, tests, package managers, target-local tools, or network-dependent collection.

NO AUTOMATIC PASS: Scanner completion or zero findings are evidence limitations-aware inputs and MUST NOT automatically set a control to pass.

Do not copy credentials, tokens, private keys, authorization headers, personal data, exploit material, or sensitive infrastructure details into the workspace or report. Use a redacted identifier, hash, or approved restricted reference.

Required Analysis

Assess exactly these six canonical surfaces independently:

• connector-server;
• local-client-or-extension;
• connector-administration;
• ai-model-boundary;
• downstream-enterprise-systems;
• production-operations.

Sustainability is cross-cutting, not a seventh surface. Evaluate its effects on each applicable surface and across the complete system.

Then assess the connected system end to end. Trace representative read, write, credential refresh, failure, revocation, update, incident, and offboarding flows. Record cross-surface trust, data, authority amplification, and composition risks. An independently strong component does not make the composed system safe.

REQUIRED: Assess every applicable surface independently and then assess cross-surface data, trust, authority, and failure flows end to end.

Use only these control results:

Result	Use
pass	Supplied evidence supports the control at the higher of target assurance and the effective control minimum.
partial	The requirement or evidence is incomplete or below the required assurance.
fail	The requirement is not met or evidence contradicts it.
not-applicable	The control cannot apply; record architecture-specific rationale.
not-reviewed	It applies or may apply, but evidence or review is unavailable.

Create a finding for every partial, fail, or not-reviewed result. Do not average a release gate against lower-risk passes.

Finding Contract

Every finding must contain:

• stable finding ID and title;
• severity and affected surface;
• failed, partial, or not-reviewed control IDs;
• evidence references and evidence limitations;
• process-wise explanation of how the weakness arises across the workflow;
• concrete risk and consequence assessment;
• bounded fix recommendation without applying it;
• owner, target date, and treatment status;
• risk-acceptance reference when applicable;
• evidence required for re-review.

REQUIRED: Every partial, fail, or not-reviewed result MUST have a structured finding with severity, process-wise explanation, risk and consequence, bounded recommendation, treatment, and re-review evidence.

Recommendations must preserve security, privacy, reliability, accessibility, and service objectives. A sustainability optimization cannot weaken them.

Recommendation Bound

Apply organization overlays when they are stricter. Otherwise use the maximum default decision:

Unresolved condition	Strongest agent recommendation
Critical finding	not-approved
Open or not-reviewed High production control	pilot-only
Accepted High with verified compensating controls	approved-with-conditions
Open Medium with owner and due date	approved-with-conditions
Only Low findings	approved, subject to stated conditions

An agent recommendation is not an approval. Verbal acceptance is evidence of a statement only; it is not a valid risk acceptance or sign-off. Use docs/04-severity-and-risk-acceptance.md for acceptance requirements and docs/03-review-procedure.md for the complete lifecycle and deliverables.

Stop Conditions

Stop and escalate when:

• target immutability cannot be enforced;
• target/output separation or workspace-parent trust is unsafe;
• the requested output is inside the target;
• necessary input requires network or live-system access;
• secrets cannot be referenced safely;
• the permitted review cannot be separated from prohibited work;
• the user refuses the immutable-target, local-only, or human-approval boundary.

The response must state what is blocked, what local evidence or path is needed, and the strongest recommendation currently supported. Unknown material components or trust boundaries become not-reviewed limitations and findings; they do not stop other safe review work. Do not claim completion.

STOP: Stop only for an unsafe prerequisite, failed resume provenance or pin validation, an inseparable prohibited request, or refusal of the review-only boundary.