docs(constitution): add Principle X on README co-evolution

[so0k]

Summary

Amend the constitution to establish Principle X: User-Facing Documentation Co-Evolution. This principle mandates that the root README.md must be updated in the same branch whenever the command surface or user-facing behavior changes, treating an out-of-date README as a blocking review finding rather than a backlog item.

This is a corrective amendment addressing issue #10, where features 002 and 003 shipped add, verify, search, and index commands without updating the README, leaving it documenting only init.

Key Changes

• Constitution version bump: 2.1.1 → 2.2.0 (amendment, 2026-06-01)
• New Principle X (§X): Establishes the standing obligation that every CLI change ships its README update in the same branch, with blocking review enforcement
• Amended Development Workflow section: Added binding requirement that root README sync is part of every CLI change
• README.md comprehensive update:
  • Expanded introduction to clarify the consume-only, no-publish design
  • Added "The workflow" section with a quick-start scenario
  • Documented all four commands (init, search, add, verify) with examples and flags
  • Added index command (origin-maintainer tool) with full documentation
  • Clarified exit codes (added code 2 for verification failure)
  • Improved origin resolution and configuration sections
  • Separated "Commands" as a top-level section with detailed subsections per command

Rationale

The constitution now explicitly binds README updates to CLI changes, making it a load-bearing development obligation rather than an aspirational practice. This closes the gap where the README lagged the implemented command surface by multiple features. Reviews will treat stale README documentation as a blocking finding, ensuring the entry-point document stays current with shipped behavior.

The README updates themselves demonstrate the principle in action, documenting the full command surface (init, search, add, verify, index) with examples, flags, and behavioral contracts that were previously missing.

https://claude.ai/code/session_01AS1Q9DvPqPELF7kqeVze5T

[qodo-code-review]

Review Summary by Qodo

Add Principle X and comprehensively update README for full command surface

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Establish Principle X: User-Facing Documentation Co-Evolution
  - Mandates README updates in same branch as command-surface changes
  - Treats stale README as blocking review finding, not backlog item
• Comprehensively rewrite README to document full command surface
  - Add workflow section with quick-start scenario (init→search→add→verify)
  - Document all five commands with examples and flags (init, search, add, verify, index)
  - Clarify exit codes including new code 2 for verification failure
• Bump constitution version 2.1.1 → 2.2.0 with amendment record
• Amend Development Workflow section to bind README sync to CLI changes

Diagram

flowchart LR
  A["Issue #10: README<br/>lags commands"] -->|"Principle X<br/>added"| B["Constitution<br/>2.2.0"]
  A -->|"Full rewrite"| C["README documents<br/>all 5 commands"]
  B -->|"enforces"| C
  C -->|"with examples"| D["Consumer workflow<br/>+ origin tools"]

Loading

File Changes

1. .specledger/memory/constitution.md 📝 Documentation +31/-1

Add Principle X and version bump to 2.2.0

• Add Principle X (§X) establishing mandatory README co-evolution with command-surface changes
• Record version bump 2.1.1 → 2.2.0 in Sync Impact Report with amendment date 2026-06-01
• Amend Development Workflow section to bind root README sync to every CLI change
• Clarify that stale README is a defect and blocking review finding, not backlog item

.specledger/memory/constitution.md

---

2. README.md 📝 Documentation +139/-18

Comprehensive rewrite documenting full command surface

• Rewrite introduction to clarify consume-only design with no publish/write credentials
• Add "The workflow" section with quick-start scenario (init→search→add→verify→index)
• Expand Commands section with detailed subsections for all five commands (init, search, add,
 verify, index)
• Document init with global/non-interactive flags and config file location
• Document search with free-text query and topic filtering capabilities
• Document add with local/remote acquisition forms, pinning, dry-run, and force options
• Document verify with exit code 2 for verification failures and offline determinism
• Document index as origin-maintainer tool for catalog regeneration
• Update exit codes table to include code 2 (verification failure) with explanations
• Clarify origin resolution, configuration, and add stderr/stdout routing note

README.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review