89088414/16gagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a188ee1426d13b4cdcbbd89965a138623414e9b2
16gagent/SYSTEM-AUDIT.md
T
大海 a188ee1426 🎉 init: 小龙的工作空间
2026-06-06 10:40:48 +08:00

19 KiB
Raw Blame History

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
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 ` ----
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

Reference in New Issue View Git Blame Copy Permalink