Claude/refactor docs turtle rdf as l ji #1366
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Integrate ggen v6 RDF-first architecture into spec-kit, enabling deterministic
ontology-driven specification generation following the constitutional equation:
spec.md = μ(feature.ttl)
## Core Architecture Changes
### 1. Constitutional Equation
- TTL files (Turtle/RDF) are the source of truth
- Markdown files are generated artifacts (never manually edited)
- SHACL shapes enforce constraints
- Idempotent transformations (μ∘μ = μ)
- Cryptographic provenance receipts
### 2. Infrastructure Updates
**Scripts (RDF-first support):**
- `scripts/bash/check-prerequisites.sh` - Returns TTL paths as primary sources
- Detects RDF vs. legacy features (checks ontology/ + ggen.toml)
- Validates TTL files first, falls back to MD for backward compatibility
- JSON output includes: TTL_SOURCES, ONTOLOGY_DIR, GENERATED_DIR
- `scripts/bash/common.sh` - Extended path variables for RDF architecture
- Added TTL source paths: FEATURE_SPEC_TTL, IMPL_PLAN_TTL, TASKS_TTL
- Added generated paths: ontology/, generated/, templates/
- SPECIFY_FEATURE env var support for exact branch matching
- `scripts/bash/setup-plan.sh` - Creates plan.ttl from templates
- Auto-detects RDF-first features
- Creates ontology/plan.ttl from template
- Symlinks templates/plan.tera
- Maintains backward compatibility for legacy MD-based features
### 3. Tera Templates (Markdown Generation)
**New templates for RDF → Markdown transformation:**
- `templates/plan.tera` (151 lines) - Renders plan.md from plan.ttl
- Technology stack, phases, decisions, risks, dependencies
- `templates/tasks.tera` (148 lines) - Renders tasks.md from tasks.ttl
- Phase-based organization, dependency tracking, parallelization
- `templates/constitution.tera` (173 lines) - Renders constitution.md
- Core principles, build standards, workflow rules, governance
### 4. RDF Helper Templates (Turtle/RDF Sources)
**Complete TTL template library (10 templates):**
- `templates/rdf-helpers/user-story.ttl.template` - User story instances with acceptance scenarios
- `templates/rdf-helpers/functional-requirement.ttl.template` - Functional requirements
- `templates/rdf-helpers/success-criterion.ttl.template` - Success criteria with metrics
- `templates/rdf-helpers/entity.ttl.template` - Domain entity definitions
- `templates/rdf-helpers/edge-case.ttl.template` - Edge case scenarios (NEW)
- `templates/rdf-helpers/assumption.ttl.template` - Assumption instances (NEW)
- `templates/rdf-helpers/plan-decision.ttl.template` - Architectural decisions (NEW)
- `templates/rdf-helpers/task.ttl.template` - Individual task instances (NEW)
- `templates/rdf-helpers/plan.ttl.template` - Complete plan structure (NEW, 2.3KB)
- `templates/rdf-helpers/tasks.ttl.template` - Complete task breakdown (NEW, 3.1KB)
### 5. Documentation
**Comprehensive RDF workflow documentation:**
- `docs/RDF_WORKFLOW_GUIDE.md` (19KB) - Complete workflow guide
- Constitutional equation explanation
- Five-stage pipeline (μ₁→μ₂→μ₃→μ₄→μ₅)
- SHACL validation guide with error examples
- Template system explanation
- Troubleshooting common issues
- End-to-end examples
- `docs/GGEN_RDF_README.md` - ggen-specific RDF integration overview
## Key Features
### SHACL Validation
- Priority values MUST be "P1", "P2", or "P3" (SHACL enforced)
- Dates in YYYY-MM-DD format with ^^xsd:date
- User stories require minimum 1 acceptance scenario
- Automatic validation during ggen render
### Five-Stage Pipeline
1. **μ₁ (Normalization)** - Canonicalize RDF + SHACL validation
2. **μ₂ (Extraction)** - SPARQL queries extract data
3. **μ₃ (Emission)** - Tera templates render markdown
4. **μ₄ (Canonicalization)** - Format markdown
5. **μ₅ (Receipt)** - Generate cryptographic hash
### Backward Compatibility
- Legacy MD-based features continue to work
- Auto-detection of RDF vs. legacy format
- Graceful fallback when TTL files missing
- SPECIFY_FEATURE env var for multi-feature branches
## Directory Structure (RDF-first features)
```
specs/NNN-feature-name/
├── ontology/ # SOURCE OF TRUTH
│ ├── feature-content.ttl
│ ├── plan.ttl
│ ├── tasks.ttl
│ └── spec-kit-schema.ttl (symlink)
├── generated/ # GENERATED ARTIFACTS
│ ├── spec.md
│ ├── plan.md
│ └── tasks.md
├── templates/ # TERA TEMPLATES (symlinks)
│ ├── spec.tera
│ ├── plan.tera
│ └── tasks.tera
├── ggen.toml # GGEN V6 CONFIG
└── checklists/
└── requirements.md
```
## Usage Examples
### Create RDF-first specification:
```bash
/speckit.specify "Add TTL validation command"
# Creates: ontology/feature-content.ttl
# Edit TTL source
vim specs/005-feature/ontology/feature-content.ttl
# Validate against SHACL
ggen validate ontology/feature-content.ttl --shapes ontology/spec-kit-schema.ttl
# Generate markdown
ggen render templates/spec.tera ontology/feature-content.ttl > generated/spec.md
```
### Create implementation plan:
```bash
/speckit.plan
# Creates: ontology/plan.ttl
# Generate markdown
ggen render templates/plan.tera ontology/plan.ttl > generated/plan.md
```
### Create task breakdown:
```bash
/speckit.tasks
# Creates: ontology/tasks.ttl
# Generate markdown
ggen render templates/tasks.tera ontology/tasks.ttl > generated/tasks.md
```
## Integration Notes
This branch integrates ggen v6's RDF-first architecture into spec-kit, enabling:
- Deterministic specification generation
- SHACL-enforced quality constraints
- Cryptographic provenance tracking
- Idempotent transformations
- Complete Turtle/RDF template library
For complete workflow documentation, see: docs/RDF_WORKFLOW_GUIDE.md
🤖 Generated with ggen v6 ontology-driven specification system
Add spec-kit-schema.ttl (25KB) containing SHACL shapes for validating: - User story priorities (must be P1, P2, or P3) - Feature metadata (dates, status, required fields) - Acceptance scenarios (min 1 per user story) - Task dependencies and parallelization - Entity definitions and requirements This schema enforces quality constraints during ggen render operations.
Ggen rdf integration
…-first workflow - Updated pyproject.toml to v0.0.23 with ggen v6 dependency documentation - Added ggen installation instructions to README.md with prerequisites - Replaced 'ggen render' with 'ggen sync' throughout RDF_WORKFLOW_GUIDE.md - Updated /speckit.specify to run ggen sync after creating TTL specifications - Updated /speckit.plan to generate markdown from plan.ttl via ggen sync - Updated /speckit.tasks to generate tasks.md from task.ttl sources - Updated /speckit.constitution with RDF-first architecture considerations - Updated /speckit.clarify to work with TTL sources and regenerate markdown - Updated /speckit.implement to ensure artifacts are synced before execution All commands now follow the RDF-first principle: TTL files are source of truth, markdown is generated via 'ggen sync' which reads ggen.toml configuration. Constitutional equation: spec.md = μ(feature.ttl) Five-stage pipeline: μ₁→μ₂→μ₃→μ₄→μ₅ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…rkflow - Added pytest configuration with integration test markers - Created testcontainer tests validating RDF-first architecture: * test_ggen_sync_generates_markdown: Verifies markdown generation from TTL * test_ggen_sync_idempotence: Verifies μ∘μ = μ (idempotence) * test_ggen_validates_ttl_syntax: Verifies invalid TTL is rejected * test_constitutional_equation_verification: Verifies deterministic transformation - Added test fixtures: * feature-content.ttl: Sample RDF feature specification * ggen.toml: Configuration with SPARQL query and template * spec.tera: Tera template for markdown generation * expected-spec.md: Expected output for validation - Updated pyproject.toml with test dependencies (pytest, testcontainers, rdflib) - Added comprehensive test documentation in tests/README.md - Updated main README with Testing & Validation section Tests verify the constitutional equation: spec.md = μ(feature.ttl) Uses Docker containers to install ggen and validate complete workflow. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…tion infrastructure - Fixed docs/GGEN_RDF_README.md to use ggen sync instead of ggen render - Updated migration section to reflect ggen.toml workflow - Updated troubleshooting section with correct ggen sync command - Added scripts/validate-promises.sh: Comprehensive validation script checking: * No ggen render references (✓ 0 found) * ggen sync usage in commands (✓ 16 references) * TTL fixtures validity (✓ 35 RDF triples) * Test collection (✓ 4 tests) * pyproject.toml syntax (✓ valid TOML) * Referenced files existence (✓ all present) * ggen.toml fixture validity (✓ valid config) * Documentation links (✓ no broken links) * Version consistency (✓ 0.0.23) * Constitutional equation references (✓ 9 found) - Added VALIDATION_REPORT.md: Complete validation documentation with: * Executive summary * 10 promise validations (all passed) * Test infrastructure details * Git history * Installation verification * CI/CD recommendations All 10 promises validated: ✅ ALL PROMISES KEPT 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The validation report documents the migration from ggen render to ggen sync, so it legitimately contains the text 'ggen render'. Exclude it from the validation check to avoid false positives. All 10 promises still validated: ✅ ALL PROMISES KEPT 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…6 integration Implement the constitutional equation for documentation: documentation.md = μ(documentation.ttl) Includes: - New ontology extension (spec-kit-docs-extension.ttl) with documentation classes: * Guide, Principle, Changelog, ConfigurationOption, Workflow * SHACL shapes for validation * Object/datatype properties for documentation metadata - Documentation metadata container (memory/documentation.ttl): * Root container with all documentation instances * Navigation structure * Cross-references between guides - ggen v6 transformation configuration (docs/ggen.toml): * 13 RDF-to-Markdown transformation pipelines * SPARQL query bindings * Tera template mappings * 5-stage deterministic transformation pipeline - SPARQL query patterns (sparql/): * guide-query.rq - Extract guide metadata * principle-query.rq - Extract principles * changelog-query.rq - Extract releases * config-query.rq - Extract configuration options * workflow-query.rq - Extract workflow steps - Tera templates (templates/): * philosophy.tera - Render principles * guide.tera - Generic guide rendering * configuration-reference.tera - Reference tables * changelog.tera - Release notes - RDF Documentation System guide explaining architecture and usage This enables: - Single source of truth documentation in RDF - Deterministic Markdown generation - SHACL validation of documentation quality - Semantic documentation relationships - Automated cross-reference management
Create memory/philosophy.ttl with extracted constitutional principles: - 6 core SDD principles (Specifications as Lingua Franca, Executable Specifications, Continuous Refinement, Research-Driven Context, Bidirectional Feedback, Branching for Exploration) - 6 Constitutional Articles (Library-First, CLI Interface, Test-First, Simplicity, Anti-Abstraction, Integration-First Testing) - Constitutional equation principle - Each principle includes ID, index, title, description, rationale, examples, and violations - Structured as sk:Principle RDF instances for deterministic transformation Enables generation of spec-driven.md from RDF via ggen sync
Create DOCUMENTATION_REFACTORING_SUMMARY.md documenting: - Complete refactoring to Turtle RDF for all documentation - Architecture overview with transformation pipeline - File inventory of 14 new files, 2000+ lines of code - Constitutional principles captured as RDF instances - Validation framework with SHACL shapes - Usage instructions for ggen sync - Constitutional alignment (demonstrates SDD applied to documentation) - Commits and next steps This summary explains the complete RDF documentation refactoring and demonstrates how SDD principles apply to the documentation system itself.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.