Decision Log
This document records key architectural and design decisions made during the development of DIDP and the JellyLabs.ai platform.
Format
Each decision follows this structure:
- Date: When the decision was made
- Decision: What was decided
- Context: Why this decision was needed
- Options Considered: Alternatives evaluated
- Rationale: Why this option was chosen
- Consequences: Expected outcomes and trade-offs
DL-001: Single Site with Dual Routes
Date: 2025-12-23
Decision: Implement specs and docs as dual routes (/spec/* and /docs/*) within a single Astro site, with mandatory split at maturity.
Context: The 2-FOUNDATION conversation identified a need to separate normative specifications from explanatory documentation. Two architectural approaches were discussed.
Options Considered:
| Option | Description | Pros | Cons |
|---|---|---|---|
| A | Single site, dual routes | Lower overhead, faster iteration | Architectural debt |
| B | Separate sites immediately | Clean separation from start | Development friction |
Rationale: Option A chosen because:
- Early-stage velocity matters more than architectural purity
- Unclear boundaries while protocols evolve
- Single repo reduces coordination cost
- Can migrate to Option B when triggers occur
Consequences:
- Must document trigger conditions for split
- Must maintain clear
/spec/vs/docs/boundaries - Architectural debt accepted with explicit payoff timeline
DL-002: Astro for Static Site Generation
Date: 2025-12-21 (1-FOUNDATION)
Decision: Use Astro as the static site generator for JellyLabs.ai.
Context: Need to publish protocol specifications as static HTML with minimal complexity.
Options Considered:
| Option | Description |
|---|---|
| Astro | Modern SSG with content focus |
| Hugo | Fast, Go-based SSG |
| Jekyll | Ruby-based, GitHub Pages native |
| Next.js | React-based, more complex |
| Plain HTML | No build system |
Rationale:
- Astro designed for content-focused sites
- Excellent markdown support with frontmatter
- Component islands for interactivity if needed
- Works well with Bun
- Modern tooling, active community
Consequences:
- Requires Bun/Node.js for builds
- Learning curve for Astro-specific features
- Commit to JavaScript ecosystem
DL-003: Bun as Package Manager and Runtime
Date: 2025-12-21 (1-FOUNDATION)
Decision: Use Bun instead of npm/yarn/pnpm.
Context: Need a JavaScript runtime and package manager for the Astro project.
Options Considered:
| Option | Speed | Compatibility | Maturity |
|---|---|---|---|
| Bun | Fast | Good | Newer |
| pnpm | Fast | Excellent | Mature |
| npm | Slow | Excellent | Mature |
| yarn | Medium | Excellent | Mature |
Rationale:
- Significantly faster install and execution
- Built-in TypeScript support
- Active development and improving compatibility
- Aligns with modern tooling preferences
Consequences:
- Some packages may have Bun-specific issues
- Team must have Bun installed
- May need npm fallback for CI
DL-004: Major Version in URL Path
Date: 2025-12-21 (PPP v1)
Decision: Include major version in URL path: /spec/<name>/v<major>
Context: Need versioning strategy for published specifications.
Options Considered:
| Pattern | Example | Pros | Cons |
|---|---|---|---|
/v1/ in path | /spec/didp/v1 | Clear, immutable URLs | More paths |
| Query param | /spec/didp?v=1 | Fewer paths | Less cacheable |
| Subdomain | v1.specs.jellylabs.ai | Clean separation | DNS complexity |
| No version | /spec/didp (always latest) | Simple | Breaking changes break links |
Rationale:
- Path-based versions are most cacheable
- Clear indication of version in every URL
- Follows common API versioning patterns
- Enables parallel hosting of multiple versions
Consequences:
- Must maintain multiple version paths
- Redirects needed for “latest” access
- Clear upgrade path for consumers
DL-005: Immutable Published Specifications
Date: 2025-12-21 (PPP v1)
Decision: Once a specification version is published, its content MUST NOT change (except errata).
Context: External systems may depend on exact specification wording.
Rationale:
- Enables reliable citations
- Prevents silent breaking changes
- Forces deliberate versioning decisions
- Matches RFC/W3C practices
Consequences:
- Typos require errata process
- Must plan carefully before publishing
- Version proliferation if changes frequent
DL-006: YAML for Iteration State
Date: 2025-12-21 (DIDP v1)
Decision: Use YAML for iteration_state.yaml instead of JSON or TOML.
Context: Need human-readable, machine-parseable state format.
Options Considered:
| Format | Readability | Comments | Tooling |
|---|---|---|---|
| YAML | Excellent | Yes | Good |
| JSON | Good | No | Excellent |
| TOML | Good | Yes | Medium |
Rationale:
- YAML supports comments (important for handoff notes)
- More human-readable for complex nested structures
- Well-supported across languages
- Familiar to DevOps/infrastructure audiences
Consequences:
- YAML parsing quirks (e.g.,
noas boolean) - Whitespace sensitivity
- Need schema validation
DL-007: Phase-Based Development Model
Date: 2025-12-21 (DIDP v1)
Decision: Implement strict phase-based development with defined transitions.
Context: AI-assisted development needs structure to survive context compaction.
Rationale:
- Phases create checkpoints for session recovery
- Explicit transitions prevent scope creep
- Artifacts override conversational memory
- Enables deterministic replay
Consequences:
- Less flexibility in development flow
- Overhead for small changes
- Learning curve for new adopters
Template for New Decisions
## DL-XXX: [Title]
**Date:** YYYY-MM-DD
**Decision:** [Clear statement of what was decided]
**Context:** [Why was this decision needed?]
**Options Considered:**
| Option | Description | Pros | Cons |
|--------|-------------|------|------|
| A | ... | ... | ... |
| B | ... | ... | ... |
**Rationale:** [Why was this option chosen?]
**Consequences:** [What are the expected outcomes and trade-offs?]