# SYSTEM-AUDIT.md — Protocol Simplification & Compatibility Audit > Generated: 2026-06-06 05:20 GMT+8 > Scope: AGENTS.md · GOVERNANCE.md · PORTFOLIO.md · Audit Scripts · Templates --- ## A. Complexity Report ### A1. Total Volume | Artifact | Bytes | Lines | Est. Tokens | |----------|-------|-------|-------------| | AGENTS.md | 19,311 | 569 | ~5,500 | | GOVERNANCE.md | 12,882 | 542 | ~3,700 | | PORTFOLIO.md | 14,513 | 614 | ~4,100 | | **3 Protocol Files** | **46,706** | **1,725** | **~13,300** | | Audit Scripts (×4) | 49,381 | 1,136 | ~14,100 | | Templates (×7) | 7,958 | 299 | ~2,300 | | **Total System** | **104,045** | **3,160** | **~29,700** | ### A2. Rule Density | Metric | AGENTS.md | GOVERNANCE.md | PORTFOLIO.md | Total | |--------|-----------|---------------|--------------|-------| | Sections (`##`) | 14 | 19 | 32 | **65** | | Subsections (`###`) | 25 | 36 | 41 | **102** | | `MUST`/`MANDATORY`/`⚠️` | 24 | 1 | 1 | **26** | | `禁止`/`必须` | 2 | 21 | 6 | **29** | | Checklist items `[- [ ]]` | 30 | 8 | 10 | **48** | | Tables | 17 | 18 | 43 | **78** | | Code blocks | 19 | 17 | 16 | **52** | | Lines with rule language | 33 | 41 | 11 | **85** | | **Total "rule signals"** | **125** | **106** | **72** | **303** | ### A3. Score/Dimension Count | Score Type | Occurrences | Defined In | |------------|-------------|------------| | `Health Score` | 18 | GOVERNANCE + PORTFOLIO | | `Delivery Score` | 6 | GOVERNANCE + PORTFOLIO | | `Quality Score` | 4 | GOVERNANCE + PORTFOLIO | | `Learning Score` | 4 | GOVERNANCE + PORTFOLIO | | `Portfolio Health` | 7 | PORTFOLIO | | `Parallelism Score` | 3 | GOVERNANCE | | `Dependency Score` | 3 | GOVERNANCE | | `Risk Score` | 3 | PORTFOLIO | | `Execution Score` | 2 | PORTFOLIO | | `ROI Score` | 2 | PORTFOLIO | | `Agent Utilization Score` | 1 | PORTFOLIO | | `Utilization Score` | 1 | PORTFOLIO | | `Project_Health` | 2 | PORTFOLIO | | `Execution_Score` (formula) | 1 | PORTFOLIO | | `Risk_Score` (formula) | 1 | PORTFOLIO | **12 distinct score concepts. 4 distinct formulas. 5 state machines.** --- ## B. Redundancy Report ### B1. Concept Overlap Matrix ``` AGENTS GOV PORT Redundancy State Machine ████ ██████ ███ 3处重叠 Quality Gate ██ █████ █████ 3处重叠 Health Score █ ███████ █████ 3处重叠 Heartbeat / progress.log ████ ██████ █████ 3处重叠 Blocker █ ███████ ███████ 3处重叠 Transition Rules ██ ██████ █████ 3处重叠 Checklist Items ██████ ████ ██████ 3处重叠 Scope Explosion ████ ██ 2处重叠 Audit ███████ ███████ 2处重叠 ``` ### B2. Identified Redundancies | # | Redundancy | Location | File Size | Savings | |---|------------|----------|-----------|---------| | R1 | **AGENTS.md §6 duplicates GOVERNANCE.md** | AGENTS.md §6a-6d | ~3KB | 15% of AGENTS.md | | R2 | **Non-protocol sections** (Memory, Red Lines, External vs Internal, Group Chats, Security Baseline, Heartbeats) | AGENTS.md tail | ~2KB | 10% of AGENTS.md | | R3 | **GOVERNANCE.md §12 Portfolio Integration duplicates PORTFOLIO.md** | GOVERNANCE.md §12 | ~1KB | 8% of GOVERNANCE.md | | R4 | **Self-referencing cross-refs** (PORTFOLIO.md references itself 15×) | PORTFOLIO.md comments | ~0.5KB | 3% of PORTFOLIO.md | | R5 | **Two-state machines with overlapping states** | GOV §1 + PORT §2 | ~2KB combined | 50% overlap in state definitions | | R6 | **Duplicate table border lines** (`|---|---|`) across all tables | All 3 files | ~0.8KB | Minor | | R7 | **Template code blocks in protocol docs** duplicate template content | All 3 files | ~3KB | 6% total | | R8 | **Audit scripts duplicate check logic** (each has own `check()`/`warn()` helper, own `readFile()`, own `SELF` runner) | All 4 scripts | ~2KB duplicated | 4% of script code | | R9 | **Quality Gate checklists duplicated** (AGENTS.md §5 + §6d + GOVERNANCE.md §9) | AGENTS + GOV | ~1KB | 2% total | | R10 | **"Canonical Reference" boilerplate** repeated in each doc header | All 3 files | ~0.3KB | Negligible | ### B3. Merge Candidates | Merge | Target File | Source Files | Est. Savings | |-------|-------------|--------------|-------------| | State Machine → one canonical definition | GOVERNANCE.md §1 | AGENTS.md §6a, PORTFOLIO.md §2 | ~1.5KB | | Quality Gate → one canonical checklist | GOVERNANCE.md §9 | AGENTS.md §5 + §6d | ~1KB | | Health Score → one formula definition | GOVERNANCE.md §7 | PORTFOLIO.md §5 (derived) | ~0.5KB | | Non-protocol content → separate file | `STYLE.md` or `POLICIES.md` | AGENTS.md tail | ~2KB | --- ## C. Compatibility Report ### C1. Cross-Reference Integrity ``` From → To Refs Broken? Notes AGENTS.md → AGENTS.md 7 No Self-refs (normal for spec doc) AGENTS.md → GOVERNANCE 5 No ✓ All valid section refs AGENTS.md → PORTFOLIO 1 No ✓ §6e Reference GOVERNANCE → AGENTS.md 7 No ✓ §0, §4, §9, §11 references GOVERNANCE → GOVERNANCE 6 No Self-refs GOVERNANCE → PORTFOLIO 2 No ✓ §12 Portfolio Integration PORTFOLIO → AGENTS.md 6 No ✓ §0, §2, §5, §14 references PORTFOLIO → GOVERNANCE 13 No ✓ Multiple valid refs PORTFOLIO → PORTFOLIO 15 No Self-refs (comment tags) **Conclusion: No broken references. All cross-refs valid and resolvable.** ``` ### C2. Bidirectional Dependency Check ``` AGENTS.md ←→ GOVERNANCE.md: YES (5→, 7←) ✓ Healthy AGENTS.md ←→ PORTFOLIO.md: YES (1→, 6←) ✓ Healthy (AGENTS rarely references PORTFOLIO directly) GOVERNANCE.md ←→ PORTFOLIO.md: YES (2→, 13←) ✓ Healthy Circular dependency: NONE ✓ ``` ### C3. State Machine Compatibility ``` GOVERNANCE states (8): NOT_STARTED → IN_PROGRESS → BLOCKED → WAITING_DEPENDENCY → READY_FOR_REVIEW → VERIFIED → FAILED → ARCHIVED PORTFOLIO states (7): PLANNING → ACTIVE → BLOCKED → RECOVERY → PAUSED → COMPLETED → ARCHIVED Shared states: BLOCKED, ARCHIVED Governance ARCHIVED = Portfolio ARCHIVED ✓ Governance BLOCKED = Portfolio BLOCKED ✓ ✓ Compatible — different domains, shared states align. ``` ### C4. Audit Script Compatibility | Check | audit-agents | audit-governance | audit-portfolio | audit-all | |-------|-------------|-----------------|----------------|-----------| | Return format | CheckResult[] | CheckResult[] | CheckResult[] | N/A | | id prefix | `AG-` | `GV-` | `PF-` | N/A | | Exported function | `runAgentAudit` | `runGovernanceAudit` | `runPortfolioAudit` | N/A | | Dynamic import in audit-all | ✓ | ✓ | ✓ | — | | Template file references | 0 | 3 | 3 | 0 | **Conclusion: Audit scripts are compatible. No interface mismatch.** **Minor issue: No shared base module — each script duplicates `check()`/`warn()` pattern.** ### C5. Conflict Detection | Potential Conflict | Files | Analysis | |-------------------|-------|----------| | State definition scope | GOV §1 vs PORT §2 | Different domains (task-level vs project-level). Overlap is intentional. No conflict. ✓ | | Health Score "final formula" | GOV §7b vs PORT §5.4 | Different layers (project vs portfolio). Different weights. No conflict. ✓ | | "Quality Gate" definition | AGENTS §5, §6d, GOV §9 | AGENTS §6d explicitly references GOV §9. Redirect, not duplication. No conflict. ✓ | | "Canonical Reference" claims | All 3 doc headers | Each doc claims its own canonical status. The headers say "canonical reference" for THAT document. Implicit hierarchical: AGENTS < GOV < PORT. No conflict. ✓ | --- ## D. Simplification Roadmap ### D1. Classification #### 🔴 Must Delete (redundant, no loss) | ID | Item | Reason | Size | |----|------|--------|------| | MD1 | AGENTS.md §6a (State Machine intro) | Fully covered by GOVERNANCE.md §1 | ~300B | | MD2 | AGENTS.md §6c (Heartbeat Compliance) | Fully covered by GOVERNANCE.md §2 | ~400B | | MD3 | AGENTS.md §6d (Governance Quality Gate) | Fully covered by GOVERNANCE.md §9 | ~500B | | MD4 | AGENTS.md Memory section | Duplicated in MEMORY.md, not protocol | ~200B | | MD5 | AGENTS.md Red Lines section | Not protocol content | ~200B | | MD6 | AGENTS.md External vs Internal | Not protocol content | ~200B | | MD7 | AGENTS.md Group Chats section | Not protocol content | ~400B | | MD8 | AGENTS.md Security Baseline | Not protocol content, in SYSTEM.md | ~500B | | MD9 | AGENTS.md Heartbeats section | Already in HEARTBEAT.md | ~100B | | MD10 | GOVERNANCE.md §12 Portfolio Integration | Duplicates PORTFOLIO.md §0/§14 | ~800B | | MD11 | PORTFOLIO.md self-ref comment tags | `` noise | ~400B | | **Total Deletable** | | | **~4KB** | #### 🟡 Can Delete (low value, optional) | ID | Item | Reason | Size | |----|------|--------|------| | CD1 | Mermaid diagrams (keep one per state machine) | Visual aid — useful but not rule | ~1KB | | CD2 | Duplicate table border rows | `|----|----|----|` under every table | ~500B | | CD3 | Inline code blocks duplicating templates | Sections showing template content | ~2KB | | CD4 | Self-cross-refs in cross-ref sections | Tables referencing files that already referenced | ~300B | | CD5 | AGENTS.md Cache Stability section | Not execution protocol | ~400B | | CD6 | AGENTS.md Session Startup section | Setup-only, not rules | ~200B | | **Total Can Delete** | | | **~4.4KB** | #### 🟢 Keep (necessary protocol) | ID | Item | Reason | |----|------|--------| | KP1 | AGENTS.md §0-5, §7, Learning Loop, Context Budget | Core execution protocol | | KP2 | GOVERNANCE.md §1-11 | Core governance protocol | | KP3 | PORTFOLIO.md §1-14 (minus noise) | Core portfolio protocol | | KP4 | All 4 audit scripts | Verification infrastructure | | KP5 | All 7 templates | Executive artifacts | #### 🔵 Core (non-negotiable) | ID | Item | Reason | |----|------|--------| | CR1 | Complexity Classification (§0) | Entry point | | CR2 | Task Tree (§1) | Planning backbone | | CR3 | PLAN + Pre-flight (§2-3) | Execution structure | | CR4 | Failure Replanning (§4) | Error handling | | CR5 | Verification (§5) | Quality control | | CR6 | Auto-Capture + Learning Loop (§7 + LL) | Knowledge feedback | | CR7 | Context Budget | Token governance | | CR8 | State Machine | All execution states | | CR9 | Heartbeat + Stale Detection | Progress tracking | | CR10 | Blocker Management | Issue management | | CR11 | Health Score (5 dimensions) | Project health | | CR12 | Auto-Stop + Recovery | Failure containment | | CR13 | Quality Gates (×3) | Output validation | | CR14 | Portfolio Registry + States | Project tracking | | CR15 | Priority System (P0-P3) | Resource allocation | | CR16 | Resource + Utilization | Agent management | | CR17 | Learning Reuse Detector | Knowledge reuse | | CR18 | Kill / Pause / Promotion Rules | Project lifecycle | | CR19 | Audit scripts ×4 | Automated verification | ### D2. Effort vs Impact ``` Impact ↑ 5KB │ MD1-MD11 (Must Delete) CD1-CD6 (Can Delete) │ Effort: 10 min Effort: 15 min │ Impact: -15% AGENTS.md Impact: -10% overall 3KB │ -10% GOV.md │ -3% PORT.md │ 1KB │ └───────────────────────────────→ Effort 5 min 15 min ``` **Recommended order:** 1. Delete non-protocol sections from AGENTS.md (MD4-MD9) — 10 min, -2KB 2. Convert AGENTS.md §6 to brief references to GOVERNANCE.md (MD1-MD3) — 5 min, -1.2KB 3. Delete GOVERNANCE.md §12 (MD10) — 2 min, -800B 4. Clean comment noise from PORTFOLIO.md (MD11) — 2 min, -400B 5. Evaluate CD1-CD6 for next iteration ### D3. Target Metrics Post-Simplification | Metric | Current | Target | Change | |--------|---------|--------|--------| | AGENTS.md | 19,311 bytes | ~14,500 | **-25%** | | GOVERNANCE.md | 12,882 bytes | ~11,500 | **-10%** | | PORTFOLIO.md | 14,513 bytes | ~13,500 | **-7%** | | **Total Protocol** | **46,706 bytes** | **~39,500** | **-15%** | | Estimated tokens | ~13,300 | ~11,200 | **-16%** | | Sections (`##`) | 65 | ~45 | **-30%** | | Lines with rules | 85 | ~60 | **-29%** | | Score dimensions | 12 | 8–9 | **-25%** | --- ## E. V2 Architecture (Lean) ### E1. File Structure ``` workspace/ ├── AGENTS.md ← Execution Protocol ONLY (§0-7 + Learning Loop + Context Budget) │ Non-protocol sections → deleted or moved to STYLE.md │ §6 → 3-line reference to GOVERNANCE.md (not full duplication) │ ├── GOVERNANCE.md ← Governance Protocol (§0-11, no §12) │ Single canonical definition of state machine │ Single canonical definition of health score │ Single canonical definition of quality gate │ ├── PORTFOLIO.md ← Portfolio Protocol (§1-14, clean comments) │ Remove self-ref comment tags │ Reference GOVERNANCE.md for state/score definitions │ ├── STYLE.md (new) ← Non-protocol: Memory/Red Lines/Security/Group Chats │ Extracted from AGENTS.md tail (no rule changes) │ ├── audit-report.md ← Generated ├── HEARTBEAT.md ← (unchanged) ├── MEMORY.md ← (unchanged) └── scripts/templates/ ← (unchanged) ``` ### E2. Rule Deduplication ``` Before After ────── ───── AGENTS.md §6a: State Machine AGENTS.md §6: "See GOVERNANCE.md §1" AGENTS.md §6c: Heartbeat AGENTS.md §6: "See GOVERNANCE.md §2" AGENTS.md §6d: Quality Gate AGENTS.md §6: "See GOVERNANCE.md §9" AGENTS.md §5: Quality Gate AGENTS.md §5: Remove duplicate checklist GOVERNANCE.md §12: Portfolio GOVERNANCE.md §12: DELETE (covered by PORTFOLIO.md) GOVERNANCE.md §1: 8 states GOVERNANCE.md §1: Canonical (no change) PORTFOLIO.md §2: 7 states PORTFOLIO.md §2: Refer to GOV §1 for BLOCKED/ARCHIVED ``` ### E3. Score Consolidation **Proposed Minimum Viable Metric Set (8 scores instead of 12):** ``` Execution Layer (GOVERNANCE.md): 1. Delivery Score — Velocity 2. Quality Score — Quality 3. Parallelism Score — Concurrency 4. Dependency Score — Wait efficiency 5. Learning Score — Knowledge capture → Health Score = weighted aggregate of 1-5 Portfolio Layer (PORTFOLIO.md): 6. Execution Score — Heartbeat health (GOVERNANCE derivative) 7. Risk Score — Blocker severity (GOVERNANCE derivative) → Project Health = weighted aggregate of 1-5 + 6-7 → Portfolio Health = weighted aggregate across projects 8. Agent Utilization — Busy/Total (cross-project) ``` **Removed (merged/redundant):** - `ROI Score` → qualitative, not calculated - `Utilization Score` → same as `Agent Utilization` - `Project_Health` → internal variable, no separate score ### E4. Audit Script Consolidation **Proposed (same 4 files, ~15% smaller each, shared utilities):** ``` scripts/ ├── audit-shared.mjs (new) ← Shared check() / warn() / readFile() / format() ├── audit-agents.mjs ← Only AGENTS.md checks (import from shared) ├── audit-governance.mjs ← Only GOVERNANCE.md checks (import from shared) ├── audit-portfolio.mjs ← Only PORTFOLIO.md checks (import from shared) └── audit-all.mjs ← Orchestrator (unchanged) ``` Estimated savings: ~2KB duplicated helper code → single source. ### E5. Token Budget Before/After ``` Current protocol injection (worst-case, all 3 files): AGENTS.md ≈ 5,500 GOVERNANCE.md ≈ 3,700 PORTFOLIO.md ≈ 4,100 ───────────────── Total: ≈ 13,300 tokens Post-simplification: AGENTS.md ≈ 3,800 (-31%) GOVERNANCE.md ≈ 3,300 (-11%) PORTFOLIO.md ≈ 3,900 (-5%) ───────────────── Total: ≈ 11,000 tokens (-17%) Target: -20% → additional ~500 bytes compression through: - Condense table borders (remove duplicate `|--|--|--|` rows) - Remove code-block-duplicated template content (replace with refs) - Collapse mermaid diagrams to simplified forms ``` --- ## F. Action Items ### Immediate (Phase 1 — Safe Deletions) | # | Action | Owner | Est. Time | |---|--------|-------|-----------| | 1 | Delete AGENTS.md Red Lines, External vs Internal, Group Chats, Security Baseline, Heartbeats | 小龙 | 5 min | | 2 | Delete AGENTS.md Memory section | 小龙 | 2 min | | 3 | Convert AGENTS.md §6 to 3-line references | 小龙 | 5 min | | 4 | Delete GOVERNANCE.md §12 | 小龙 | 2 min | ### Short-term (Phase 2 — Deduplication) | # | Action | Owner | Est. Time | |---|--------|-------|-----------| | 5 | Consolidate AGENTS.md §5 quality gate → reference only | 小龙 | 3 min | | 6 | Create audit-shared.mjs, refactor 4 scripts | 小龙 | 20 min | | 7 | Clean PORTFOLIO.md self-ref comments | 小龙 | 3 min | ### Medium-term (Phase 3 — Streamlining) | # | Action | Owner | Est. Time | |---|--------|-------|-----------| | 8 | Create STYLE.md from AGENTS.md tail content | 小龙 | 5 min | | 9 | Consolidate score definitions (12→8) across docs | 小龙 | 10 min | | 10 | Normalize table format across all 3 files | 小龙 | 10 min | --- ## G. Compatibility Summary ``` ┌─────────────────────────────────────────────────────────────┐ │ COMPATIBILITY VERDICT │ ├─────────────────────────────────────────────────────────────┤ │ Cross-Reference Integrity │ ✓ PASS (0 broken refs) │ │ Bidirectional Dependencies │ ✓ PASS (0 circular deps) │ │ State Machine Alignment │ ✓ PASS (2 shared states) │ │ Audit Interface Compatibility│ ✓ PASS (unified return) │ │ Rule Conflicts │ ✓ PASS (0 conflicts) │ │ Template File Coverage │ ✓ PASS (all referenced) │ ├─────────────────────────────────────────────────────────────┤ │ OVERALL │ ✓ COMPATIBLE │ └─────────────────────────────────────────────────────────────┘ ``` **Existing system is internally consistent. No bugs. No conflicts. Just bloat.** The protocol works correctly — it's just bigger than it needs to be. --- > *Report generated by `scripts/duplicate-analysis.mjs` + `scripts/protocol-stats.mjs`*