phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Fix ADR numbering conflicts and create comprehensive documentation indices

Browse Source 
This commit resolves all documentation issues identified in the comprehensive review:

CRITICAL FIXES:
- Renumbered duplicate ADRs to eliminate conflicts:
  * ADR-022-migration-race-condition-fix → ADR-037
  * ADR-022-syndication-formats → ADR-038
  * ADR-023-microformats2-compliance → ADR-040
  * ADR-027-versioning-strategy-for-authorization-removal → ADR-042
  * ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043
  * ADR-031-endpoint-discovery-implementation → ADR-044

- Updated all cross-references to renumbered ADRs in:
  * docs/projectplan/ROADMAP.md
  * docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md
  * docs/reports/2025-11-24-endpoint-discovery-analysis.md
  * docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md
  * docs/decisions/ADR-044-endpoint-discovery-implementation.md

- Updated README.md version from 1.0.0 to 1.1.0
- Tracked ADR-021-indieauth-provider-strategy.md in git

DOCUMENTATION IMPROVEMENTS:
- Created comprehensive INDEX.md files for all docs/ subdirectories:
  * docs/architecture/INDEX.md (28 documents indexed)
  * docs/decisions/INDEX.md (55 ADRs indexed with topical grouping)
  * docs/design/INDEX.md (phase plans and feature designs)
  * docs/standards/INDEX.md (9 standards with compliance checklist)
  * docs/reports/INDEX.md (57 implementation reports)
  * docs/deployment/INDEX.md (deployment guides)
  * docs/examples/INDEX.md (code samples and usage patterns)
  * docs/migration/INDEX.md (version migration guides)
  * docs/releases/INDEX.md (release documentation)
  * docs/reviews/INDEX.md (architectural reviews)
  * docs/security/INDEX.md (security documentation)

- Updated CLAUDE.md with complete folder descriptions including:
  * docs/migration/
  * docs/releases/
  * docs/security/

VERIFICATION:
- All ADR numbers now sequential and unique (50 total ADRs)
- No duplicate ADR numbers remain
- All cross-references updated and verified
- Documentation structure consistent and well-organized

These changes improve documentation discoverability, maintainability, and
ensure proper version tracking. All index files follow consistent format
with clear navigation guidance.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phil Skentelbery
2025-11-25 13:28:56 -07:00
parent f28a48f560
commit e589f5bd6c
34 changed files with 5820 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/reports/2025-11-24-endpoint-discovery-analysis.md
View File

@@ -9,7 +9,7 @@
## Executive Summary
I have reviewed the architect's corrected IndieAuth endpoint discovery design and the W3C IndieAuth specification. The design is fundamentally sound and correctly implements the IndieAuth specification. However, I have **critical questions** about implementation details, particularly around the "chicken-and-egg" problem of determining which endpoint to verify a token with when we don't know the user's identity beforehand.
I have reviewed the architect's corrected IndieAuth endpoint discovery design (ADR-043) and the W3C IndieAuth specification. The design is fundamentally sound and correctly implements the IndieAuth specification. However, I have **critical questions** about implementation details, particularly around the "chicken-and-egg" problem of determining which endpoint to verify a token with when we don't know the user's identity beforehand.
**Overall Assessment**: The design is architecturally correct, but needs clarification on practical implementation details before coding can begin.
@@ -148,7 +148,7 @@ The token is an opaque string like `"abc123xyz"`. We have no idea:
- Which provider issued it
- Which endpoint to verify it with
**ADR-030-CORRECTED suggests (line 204-258)**:
**ADR-043-CORRECTED suggests (line 204-258)**:
```
4. Option A: If we have cached token info, use cached 'me' URL
5. Option B: Try verification with last known endpoint for similar tokens
@@ -204,7 +204,7 @@ Please confirm this is correct or provide the proper approach.
### Question 2: Caching Strategy Details
**ADR-030-CORRECTED suggests** (line 131-160):
**ADR-043-CORRECTED suggests** (line 131-160):
- Endpoint cache TTL: 3600s (1 hour)
- Token verification cache TTL: 300s (5 minutes)
@@ -363,7 +363,7 @@ The W3C spec says "first HTTP Link header takes precedence", which suggests **Op
### Question 5: URL Resolution and Validation
**From ADR-030-CORRECTED** line 217:
**From ADR-043-CORRECTED** line 217:
```python
from urllib.parse import urljoin