12 KiB

Raw Blame History

CLAVITOR-PRINCIPLES.md Meta-Review

Reviewer: Arthur (architect-agent)
Scope: Reviewing the principles document through the lens of its own principles
Date: 2026-04-08
Session ID: arthur-20250408-meta

Executive Summary

The document is exceptionally well-constructed for a security-critical project, demonstrating mature architectural thinking. However, at 1,472 lines across 10 parts, it risks becoming the very thing it warns against: a foundation that requires constant patching. This meta-review applies the document's own principles to itself.

Principle	Self-Score	Finding
Foundation First	8/10	Solid, but growing too large
KISS	6/10	1,472 lines is not simple
DRY	7/10	Some repetition across parts
No migrations	N/A	Doc versioning handled well
Error handling	9/10	Strong exception guidance
Audit	8/10	Daily checklist is auditable
Push back	10/10	Explicit conflict guidance
Never delegate understanding	9/10	Concrete examples throughout

Overall: The document is approaching a threshold where it may need restructuring, not expansion.

Part-by-Part Review

Part 1 — General Principles

Foundation First — Self-Assessment: The document is the foundation. It successfully establishes that foundation > speed, and agents are empowered to push back. However, the restart rule (lines 42-49) requires user approval — does the document itself need a restart? At 1,472 lines, we should ask: is this the right shape?

KISS — Self-Violation Found:

Line 67 claims "the simplest thing that works"
Yet we have 10 parts, 1,472 lines
A new agent must read 1,472 lines before touching code
Recommendation: Split into CLAVITOR-PRINCIPLES.md (core, ~500 lines) and CLAVITOR-REFERENCE.md (details, checklists, examples)

DRY — Repetition Found:

"If you delete it, delete it" appears twice (lines 80, 116)
"Security failures are LOUD" repeated in Part 1 and Part 2
Daily review instructions repeated in intro and Part 4
Recommendation: Consolidate repeated mantras into a "Principles at a Glance" appendix

Don't Add What's Not Needed — New Findings: The document keeps growing. Each new principle adds weight. The early-stage rule (line 104) says migration rule flips April 20, 2026 — but the document has no sunset clause for itself. When does it stop growing?

Recommendation: Add a principle: "The principles document has a maximum size. When it exceeds 1,500 lines, we split, not add."

Part 2 — Security: The Cardinal Rules

Threat Model Clarity:

The threat model (lines 189-193) is laser-focused: malicious skill harvesting
Three threats (A, B, C) are clearly delineated
The "primary universe" qualification (line 295-298) addresses F028 critique well

Self-Consistency Check:

Cardinal Rule #1 (Security failures are LOUD) — consistently applied
Cardinal Rule #3.5 (FIPS 140-3) — newly added, fits well
The key tier table (lines 250-257) is now consistent after F029 fix

Exceptionally Rare Terms: Lines 292-295 correctly notes that master_key, L3, P3 should appear almost nowhere. The document itself honors this — these terms appear only in the browser/CLI contexts where they belong.

Part 3 — Per-Subproject Principles

Completeness:

9 subprojects covered (vault, CLI, web, chrome, firefox, safari, crypto, admin, mobile, telemetry)
Each has "Owns" and "Must never" sections
Exception: No mobile implementation yet, but principles are ready

KISS Concern: Part 3 is 222 lines (444-647). As new subprojects are added, this will grow. The "Must never" lists are starting to repeat patterns (no L2/L3 appears in every subproject).

Recommendation: Abstract common "Must never" patterns into Part 2, reference them from Part 3.

Part 4 — Daily Review Checklist

Structure Evolution: Originally grep-driven, now correctly emphasizes LLM review (line 635-651). The document acknowledges its own limitation: grep catches patterns, not intent.

Section Proliferation:

A: Server hard vetos
B: Silent fallback
C: Test fixture security
D: Foundation drift
E: DRY violations
F: Test posture
G: Dead code elimination

Seven sections. Each new principle category adds a section. This is unsustainable.

Recommendation: Sections A-G should be a checklist registry (like the error registry in lib/errors.go), not inline documentation. Move the check commands to a separate CLAUDE.md in each subproject.

Part 5 — How to Add a New Principle

Meta-Recursion: This section describes how to modify the document itself. The deprecation format (lines 970-984) is excellent — dated, authorized, preserved.

Missing: No guidance on when to stop adding principles. The document assumes growth is always additive. Part 6 should include "When to split the document."

Part 6 — When You Have to Violate a Principle

Excellent Addition: Lines 1009-1040 add escalation and post-hoc discovery. The severe security violations section (lines 1035-1040) with permanent ban language is strong.

Self-Application: Has this document ever violated its own principles? Yes — it grew beyond KISS. Should we surface this? Yes. Does this review do that? Yes.

Part 7 — Incident Response

Operational Completeness: Lines 1055-1129 cover agent lock, unlock, token compromise, emergency procedures. This is operational documentation, not architectural principles.

KISS Violation: Incident response is important, but it's procedure, not principle. It belongs in docs/INCIDENT-RESPONSE.md, not the foundational contract.

Recommendation: Move Part 7 to separate operational documentation.

Part 8 — Compliance & Data Governance

Tiered Retention: Lines 1130-1158 correctly differentiate paying vs non-paying (7 years vs 90 days). This is business policy.

Question: Is this a principle or a policy? The document blurs the line. Principles are timeless; policies change with business models.

Recommendation: Part 8 is policy. Move to docs/COMPLIANCE.md or legal/ (Hugo's domain).

Part 9 — Localization (i18n/l10n)

Intentionally Limited: Lines 1159-1182 correctly scope: English-first, RTL not priority. The form field detection note (lines 1170-1179) is honest about unaddressed features.

KISS Honored: This part is short, scoped, and admits what it doesn't cover. Good.

Part 10 — Git Workflow

Persona System: Lines 1183-1472 introduce the 11-agent persona system (Sarah, Charles, Maria, James, Emma, Arthur, Victoria, Luna, Thomas, Hugo, Hans, George). This is organizational design, not code principles.

Foundation Concern: Part 10 is 290 lines. It's longer than Part 2 (Cardinal Rules). The document has become an employee handbook, not a code contract.

Strong Elements:

Agent naming convention (lines 1371-1386) — clear table
How agents know their name (lines 1388-1421) — directory-based detection
Agent-authored PRs — workflow guidance

Critical Question: Should a document titled "Principles" include 290 lines of Git workflow and persona definitions? Or should these be:

docs/AGENT-PERSONAS.md (Luna/Thomas collaboration)
docs/GIT-WORKFLOW.md (Charles domain)
CLAUDE.md in root (Arthur's architectural guidance)

Cross-Cutting Findings

F001: Document Size Threshold — CRITICAL

Finding: 1,472 lines Principle Violated: KISS (line 67) Evidence: New agents must read 1,472 lines before touching code Remediation:

Split into three documents:

CLAVITOR-PRINCIPLES.md (~400 lines) — The contract
- Part 1: General principles
- Part 2: Cardinal Rules
- Part 5: How to add principles
- Part 6: Violation handling
CLAUDE.md (exists in subprojects) — Agent operational guide
- Part 10: Git workflow ( persona system)
- Agent-authored PR process
- How agents know their name
docs/ directory — Reference material
- Part 7: Incident Response (operational)
- Part 8: Compliance (policy)
- Part 9: Localization (scoped feature)
- Part 4: Daily checklist (implementation details)

F002: Repetition Across Parts — HIGH

Repeated Concepts:

Concept	Count	Locations
"Delete it, delete it"	2	Lines 80, 116
"Security failures LOUD"	3	Part 1, Part 2, examples
"No L2/L3 on server"	6+	Every subproject "Must never"
"Daily review" process	2	Intro, Part 4

Remediation: Create a "Canon" section — one-line principles with symbolic names:

### Canon — The Non-Negotiables

1. **F01: Foundation First** — Never patch cracks, rebuild.
2. **S01: Security Loud** — Failures exposed, never silent.
3. **K01: KISS** — Hardcoded paths, no env vars.
4. **D01: DRY** — Third repetition = abstraction.
5. **T01: Trust Browser** — L2/L3 never touch server.

Reference these canon codes throughout, rather than repeating full text.

F003: Operational vs. Foundational Blur — MEDIUM

Operational Content in Principles Doc:

Part 4: Daily review checklist — implementation
Part 7: Incident response — procedure
Part 8: Compliance — policy
Part 10: Git workflow — process

These are not principles. They are necessary, but they are "how we work," not "what we believe."

Remediation: The document should answer: "What do we believe?" not "How do we work?"

F004: The Persona System Scope — QUESTION

Finding: 11 personas defined in Part 10 Question: Is this architectural or organizational?

Analysis:

Architectural: Subproject boundaries, trust domains, security rules
Organizational: Who does what, names, voices

Verdict: The persona system is organizational design, not architecture. It belongs in:

docs/AGENT-PERSONAS.md (for the table)
CLAUDE.md in each subproject (for "You are Sarah..." context)

F005: Self-Modification Safety — FOUNDATION

Finding: The document describes how to modify itself (Part 5) Question: Does it have sufficient safeguards?

Assessment:

Deprecation format exists (dated, authorized, preserved) ✅
No maximum size limit ❌
No "when to split" guidance ❌
No principle about principle proliferation ❌

Remediation: Add to Part 5:

### When the document is too big

If CLAVITOR-PRINCIPLES.md exceeds 1,000 lines:
1. Stop adding principles
2. Propose a split to user
3. Move operational content (Parts 4, 7, 8, 10) to docs/
4. Keep only architectural principles in the core document

Recommendations Summary

Immediate (Before Any New Content)

Freeze new principles until restructuring complete
Split the document into principles / operational / reference
Create canon codes for repeated mantras

Short-Term (This Week)

Move Part 7 (Incident Response) to docs/INCIDENT-RESPONSE.md
Move Part 8 (Compliance) to legal/COMPLIANCE.md (Hugo's domain)
Move Part 10 (Git workflow + personas) to docs/AGENT-GUIDE.md
Extract Part 4 (Checklist) to CLAUDE.md in each subproject

Medium-Term (Before April 20)

Create CLAVITOR-CANON.md — one-line principles with codes
Reference canon codes throughout, remove repetition
Set hard limit: Core document max 500 lines

Long-Term (Culture)

Review document size monthly
Surface document bloat as "foundation problem" requiring restart
Apply "No migrations" to the document itself — structural changes, not patches

Conclusion

CLAVITOR-PRINCIPLES.md is an exceptional document that has become a victim of its own success. It grew because it works — but at 1,472 lines, it now violates the KISS principle it espouses.

The meta-lesson: Even principle documents need foundation-first treatment. This review is the "stop and surface the conflict" moment for the document itself.

Arthur's recommendation:

"The foundation of our principles document is wrong because it has grown to 1,472 lines mixing architecture, operations, and organizational design. I recommend restarting the document structure: split into core principles (~400 lines), operational guides (docs/), and reference material. Sunk cost: 1,472 lines written, well-loved. Estimated restructure: 2 sessions. Proceed?"

Foundation First. No mediocrity. Ever.

Reviewed by Arthur (architect-agent), session arthur-20250408-meta

12 KiB Raw Blame History