🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,437 @@
+# 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`*