16gagent/SYSTEM-AUDIT.md

# 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 | `<!-- Governance Reference: §N -->` 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`*