Cyrus060224/auditcore-multi-agent-audit

AuditCore Multi-Agent Collaborative Audit and Workpaper Generation Skill

I. Architecture Overview

The AuditCore Skill adopts a "Host-Brain + Deterministic-Core" architecture:

• No External API Key Multi-Agent Blind Review Committee: Directly reuses the host agent's (Claude Code, Antigravity, Codex, OpenClaw, etc.) sub-agent dispatch capability to spawn four contextually isolated audit roles (junior-auditor, challenger-auditor, fact-checker, senior-partner).
• Deterministic Patent Algorithm Core (scripts/audit_cli.py) : Uses a stateful CLI engine to enforce PII encryption/masking and SHA-256 hash chain audit logs, three-tier materiality filtering, six-dimensional deterministic rule penetration (Benford's Law, Z-Score, rounding anomalies, weekend transactions, same-day split transactions, negative reversal/duplicate vouchers) , PyTorch-free three-way hybrid regulatory retrieval $H(q, c_i)$ , four-layer evidence topology causal graphs and bipartite graph loss verification, DAG state machine minimum-cut local rollback, and CSA-1131 four-element Word (.docx) / Markdown (.md) workpaper auto-generation with PII reverse restoration.

---

II. Three Core Iron Rules (Violation of any rule renders the audit invalid)

IRON RULE 1: Zero-Leakage Privacy Gate

• Strictly prohibited from directly reading the original account set: Before or after executing scripts/audit_cli.py init, it is absolutely forbidden to use pandas, python, cat, head, or any file reading tool to directly view the user's original .xlsx/.csv file contents!
• Strictly prohibited from touching the encrypted safe: The .auditcore_workspace/cases/<CASE_ID>/.vault_do_not_read.json file generated by init is encrypted with XOR-SHA256-HMAC to store real entity and account mappings. The host and any sub-agents are strictly forbidden from reading or decrypting this file.
• Full workflow masked reasoning: All SQL exploration and four-role blind review reasoning must strictly use masked placeholders like PERSON_0001, ACCT_0001; real entity names are only restored locally by the deterministic script during the final audit_cli.py export stage.

IRON RULE 2: Blinded Subagent Isolation

• In full-audit mode, it is strictly forbidden to "role-play all four roles in a single model monologue" in the main conversation.
• Must follow the state machine sequence, sequentially reading the corresponding role contract files under agents/ and spawning independent sub-agents (using the host's invoke_subagent / Task / Agent tools):
  1. Initial Review: agents/junior-auditor.md -> submit --role junior
  2. Independent Review: agents/challenger-auditor.md -> submit --role challenger
  3. Fact Check: agents/fact-checker.md -> submit --role factcheck
  4. Final Review Partner: agents/senior-partner.md -> submit --role senior
• Degradation Compatibility Rule: Only when the host environment does not support any sub-agent dispatch tools may the reviewer independently generate each role's JSON step-by-step in the main session, but each step must immediately call audit_cli.py commit for deterministic evidence graph verification, and steps must never be merged or skipped.

IRON RULE 3: Stateful CLI Gate & Minimum-Cut Rollback Closure

• Every role's conclusion must be submitted via scripts/audit_cli.py commit --role <role>. If the state machine sequence is violated, the CLI will return exit code 2 (STATE_GUARD_VIOLATION).
• When, after submitting factcheck, the global consistency score $S_{\text{global}} < \theta$ (default 0.80), the CLI will automatically execute dependency-aware minimum-cut local rollback, returning "rollback_triggered": true along with rollback_diagnosis.arbitration_probe (review probe), and reverting the state to STATE_JUNIOR_AUDIT or STATE_CHALLENGER_REVIEW.
• When rollback_triggered: true is encountered, the rollback_diagnosis must be injected into the target role and the sub-agent must be re-spawned until consistency is achieved and the state enters STATE_SENIOR_PARTNER! Handwriting fake workpapers to skip export is strictly forbidden.

---

III. Five Operational Mode Routing Table

Auto-select the corresponding mode based on user request (default executes full-audit):

Mode Name	Applicable Scenario & Trigger Words	Execution Path
full-audit(Default Full Workflow)	Audit account set file, comprehensive fraud/internal control deficiency check, and issue formal workpapers	Full execution of Section IV: 5-Step Stateful Protocol below (init $\to$ sql $\to$ 4-role blind review & minimum-cut rollback loop $\to$ export)
quick-scan(Quick Scan)	"Quick scan for anomalies", "Don't run multi-agent game, just show rule scan results"	1. Run audit_cli.py init --file <PATH> --case <ID> --mode quick2. Optionally run audit_cli.py export --case <ID> --out-dir <DIR> to quickly export rule scan workpapers
sql-explore(SQL Sandbox Penetration)	Execute custom cross-period/grouped aggregation queries on an initialized account set	Run audit_cli.py sql --case <ID> --query "SELECT ... FROM financial_ledger ..." (read-only SELECT / WITH only)
law-lookup(Hybrid Regulatory Retrieval)	"Look up standard clauses on split transactions/weekend entries/audit evidence"	Run audit_cli.py law --query "<keyword or question>" --top-k 5, outputs weighted evidence chain $E(q)$ and qualitative reasoning four-stage conclusion $\Psi$ directly
workpaper(Workpaper Re-export)	Re-export for a completed case with different entity name, accounting period, or export directory	Run audit_cli.py export --case <ID> --entity-name "<Entity Name>" --period "<Period>" --out-dir <DIR>

For detailed CLI parameters and JSON Schema, please refer to: references/schemas.md.

---

IV. full-audit Standard 5-Step Stateful Execution Protocol

Assume the skill root directory is <SKILL_DIR> (containing scripts/audit_cli.py). If the user does not provide an account set file and requests a demo, the built-in high-fidelity fraud simulation sample account set <SKILL_DIR>/examples/sample_vouchers_2026.xlsx can be used directly.

Step 1: Initialize Account Set, Encrypt/Mask, and Run Deterministic Rules (init)

python3 <SKILL_DIR>/scripts/audit_cli.py init \
  --file "<USER_EXCEL_OR_CSV_PATH>" \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --lang "en"

• Record the returned JSON: stats, schema_ddl, rule_findings, anomaly_samples, evidence_chain.
• The state machine is now at STATE_DYNAMIC_SQL_EXPLORATION.

Step 2: Read-Only SQLite Sandbox Penetration Query (sql)

Based on schema_ddl and rule_findings, write an aggregation review SQL for the masked financial_ledger table (e.g., review same-day split transaction counts and cumulative amounts for the same supplier, or aggregate abnormal amounts by debit account):

python3 <SKILL_DIR>/scripts/audit_cli.py sql \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --query "SELECT Date, Vendor, COUNT(*) AS tx_count, SUM(Amount) AS total_amount FROM financial_ledger GROUP BY Date, Vendor HAVING tx_count >= 2 OR total_amount >= 100000 ORDER BY total_amount DESC"

• The state machine advances to STATE_JUNIOR_AUDIT.

Step 3: Multi-Agent Independent Blind Review & Minimum-Cut Local Rollback Loop (commit Loop)

3.1 Spawn Junior Auditor (STATE_JUNIOR_AUDIT)

1. Read <SKILL_DIR>/agents/junior-auditor.md.
2. Spawn a sub-agent (or independent step), passing only masked stats, rule_findings, anomaly_samples, sql results, evidence_chain (if a rollback retrial, additionally pass rollback_diagnosis).
3. Get the JSON returned by the sub-agent (containing analysis, risk_score, cited_reg_ids), submit to CLI:

python3 <SKILL_DIR>/scripts/audit_cli.py commit \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --role junior \
  --payload '<JUNIOR_JSON>'

• State machine advances to STATE_CHALLENGER_REVIEW.

3.2 Spawn Independent Reviewer (STATE_CHALLENGER_REVIEW)

1. Read <SKILL_DIR>/agents/challenger-auditor.md.
2. Spawn an independent sub-agent, passing masked anomaly evidence, evidence_chain, and the initial review's junior_report and junior_score, requiring it to independently review and challenge with professional skepticism.
3. Get the returned JSON (containing rebuttal, adjusted_risk_score), submit to CLI:

python3 <SKILL_DIR>/scripts/audit_cli.py commit \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --role challenger \
  --payload '<CHALLENGER_JSON>'

• State machine advances to STATE_FACT_CHECK.

3.3 Spawn Fact-Checker and Verify Global Consistency (STATE_FACT_CHECK)

1. Read <SKILL_DIR>/agents/fact-checker.md.
2. Spawn an independent sub-agent to perform atomic fact decomposition (claims) and bipartite graph evidence mapping (evidence_mapping) on the initial and review conclusions.
3. Get the returned JSON (containing analysis, support_score, conflict_score, conflict_type, claims, evidence_mapping), submit to CLI:

python3 <SKILL_DIR>/scripts/audit_cli.py commit \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --role factcheck \
  --payload '<FACTCHECK_JSON>'

4. Check the CLI's returned current_state and rollback_triggered:
   • If "rollback_triggered": true: Indicates a severe conflict in the evidence graph ($S_{\text{global}} < \theta$), the CLI has automatically pruned the worst reasoning subgraph and rolled back to rollback_target_state (typically STATE_JUNIOR_AUDIT). You must extract the returned rollback_diagnosis (containing arbitration_probe and csa_guidance), go back to 3.1 (or 3.2) and re-spawn the sub-agent to correct the conclusion!
   • If "current_state": "STATE_SENIOR_PARTNER": Indicates evidence graph consistency is met, proceed to Step 4.

Step 4: Spawn Senior Partner for Final Adjudication and Audit Adjustment Entries (STATE_SENIOR_PARTNER)

1. Read <SKILL_DIR>/agents/senior-partner.md.
2. Spawn an independent sub-agent, passing masked statistics, regulatory evidence chains, verified initial/review conclusions, to generate the final verdict (final_verdict, final_risk_score, reasoning, action_item, suggested_aje).
3. Submit to CLI:

python3 <SKILL_DIR>/scripts/audit_cli.py commit \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --role senior \
  --payload '<SENIOR_JSON>'

• State machine advances to STATE_WORKPAPER_GENERATION.

Step 5: Assemble 4-Element Workpaper, Evaluate Quality $Q(Y)$, Reverse PII, and Export CSA-1131 Workpaper (export)

python3 <SKILL_DIR>/scripts/audit_cli.py export \
  --case "CASE_2026_01" \
  --workspace ".auditcore_workspace" \
  --out-dir "./audit_outputs" \
  --entity-name "Audited Entity" \
  --period "FY2026"

• The CLI will automatically reverse-restore PII entity names and generate:
  1. workpaper_docx_path: Formal .docx Word audit working paper compliant with Chinese Auditing Standard No. 1131;
  2. workpaper_markdown_path: Structured .md audit working paper;
  3. quality_evaluation: An evaluation report containing $Q_{\text{ev}}$, $Q_{\text{con}}$, $Q_{\text{cmp}}$, total score $Q(Y)$, and zero-tolerance hallucination check results.
• Report to the user the final audit findings, showing the restored real entity names, audit adjustment entries (AJE), quality score $Q(Y)$, and paths to the generated .docx / .md files.

---

V. Common Excuses & Anti-Laziness Comparison Table (Rationalization Table & Red Flags)

Common Agent Laziness Excuse (Rationalization)	Objective Facts & Iron Rule Countermeasures (Reality & Iron Rule)
"The account set file is small; let me use pandas.read_excel to quickly check the columns and suppliers inside."	Severe Violation (Violates IRON RULE 1)! Once the original file is read directly, plaintext entity names and bank accounts are immediately exposed in the LLM context, completely destroying privacy compliance boundaries. You must only run audit_cli.py init first.
"To save time, I'll write the JSON for the initial review, review, fact-check, and partner all in one code block and commit them sequentially."	Severe Violation (Violates IRON RULE 2)! Fabricating all four roles in a single context causes severe confirmation bias. If the host supports sub-agents, they must be spawned independently; even if executed sequentially, you must read the CLI's evidence graph feedback after each commit before proceeding.
"After the factcheck commit triggered rollback_triggered: true, I'll just modify the score in the JSON and submit senior directly."	State gate directly intercepts (exit code 2)! After rollback, the state machine is at STATE_JUNIOR_AUDIT (or STATE_CHALLENGER_REVIEW). Without re-running the preceding roles per rollback_diagnosis.arbitration_probe, the state machine will never grant access to STATE_SENIOR_PARTNER.
"I already know the audit conclusion; I can just write a Markdown report for the user, no need to call audit_cli.py export."	Severe Violation (Violates IRON RULE 3)! Handwritten reports cannot decrypt the real entity names in .vault_do_not_read.json (can only output PERSON_0001), and lack the patented four-element structure $Y={\text{idx},\text{aje},\text{jud},\text{log}}$, quality score $Q(Y)$, and the formal CSA-1131 .docx workpaper.

Red Flags — When you have any of the following thoughts, stop immediately and return to the CLI protocol:

• About to run pd.read_excel / pd.read_csv / open() to read the user's original financial file
• About to read .vault_do_not_read.json
• Fabricating regulation article numbers in the analysis that do not appear in evidence_chain (this triggers hallucinated_citations zero-tolerance demotion, forcibly lowering $Q(Y)$ to $\le 0.40$)
• Skipping sql or any commit --role step and trying to directly run export