0.5.0

.claude/rules/core-rules.md

@@ -1,13 +1,25 @@
 ---
+description: Coordinate map sync constraint for rule directory changes
 globs:
   - "core/**"
   - "agents/*/rules/**"
 ---
 
 # Coordinate Map Sync
 
-After creating, deleting, or renaming a rule directory, update `registry/coordinate-map.yml` to keep the mapping complete.
+This rule extends the parent scope for core and agent rule directories.
 
-Format: `slug: "COORDINATE"` (e.g., `backbone-index-completeness: "CORE:M:0004"`).
+After creating, deleting, or renaming a rule directory, update @registry/coordinate-map.yml to keep the mapping complete.
 
-See rule CORE:M:0004 for the completeness requirement.
+Format in coordinate-map.yml:
+
+```yaml
+slug: "COORDINATE"
+# e.g., backbone-index-completeness: "CORE:M:0004"
+```
+
+See CORE:M:0004 in the corresponding rule.md for the completeness requirement.
+
+Every rule directory must have these files:
+- rule.md
+- rule.yml

.claude/rules/schemas.md

@@ -1,10 +1,25 @@
 ---
+description: Backbone schema sync constraint for schema file changes
 globs:
   - "schemas/**"
 ---
 
 # Backbone Schema Sync
 
-After adding or removing schema files, update the `schemas` section in `.reporails/backbone.yml`.
+This rule extends the parent scope for schema directories.
 
-Format: `{name}: {path}` (e.g., `rule: schemas/rule.schema.yml`).
+After adding or removing schema files, update the `schemas` section in @.reporails/backbone.yml.
+
+Format in backbone.yml:
+
+```yaml
+schemas:
+  rule: schemas/rule.schema.yml
+```
+
+Schema naming convention follows:
+- schemas/rule.schema.yml
+- schemas/agent.schema.yml
+- schemas/capability.schema.yml
+
+See also @docs/pattern-guide.md

.claude/rules/skills.md

@@ -1,10 +1,20 @@
 ---
+description: Backbone path resolution constraint for skill references
 globs:
   - ".claude/skills/**"
 ---
 
 # Backbone Path References
 
-Skills resolve paths from `.reporails/backbone.yml`. When referencing a new schema or registry file, verify the path exists in `backbone.schemas` or `backbone.registry`.
+This rule extends the parent scope for skill directories.
 
-See `.shared/knowledge/backbone-resolution.md` for the full resolution table.
+Skills resolve paths from @.reporails/backbone.yml. When referencing a new schema or registry file, verify the path exists in `backbone.schemas` or `backbone.registry`.
+
+Example path check in a SKILL.md:
+
+```yaml
+# backbone.schemas.rule → schemas/rule.schema.yml
+```
+
+Resolution reference:
+- @.shared/knowledge/backbone-resolution.md

.claude/skills/add-changelog-entry/SKILL.md

@@ -7,7 +7,7 @@ description: Add a changelog entry to UNRELEASED.md
 
 Automatically add a changelog entry to PROJECT_ROOT/UNRELEASED.md.
 
-## Instructions
+## Process
 
 1. Check git diff or recent file modifications
 2. Determine the area from the file path:

.claude/skills/bootstrap/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: bootstrap
+description: Load project context — backbone, registry, and constraints — before any work
+---
+
+# /bootstrap
+
+Initialize session context by building a working mental model of the project — topology, navigation, operations, and constraints.
+
+## Usage
+
+```
+/bootstrap
+```
+
+## Workflow
+
+Follow: [@.shared/workflows/bootstrap.md](../../../.shared/workflows/bootstrap.md)
+
+### 1. Load backbone (project topology)
+
+Read `.reporails/backbone.yml`. This is the single source of truth for all paths in the project. After this step you MUST NOT use exploratory commands (find, ls, glob) to discover paths the backbone already provides.
+
+Extract and hold:
+- **Agents**: which agents exist, their config paths, their instruction file names
+- **Rule categories**: the category → directory mapping (e.g., `structure` → `core/structure/`)
+- **Schemas**: the schema name → path mapping (8 schemas)
+- **Registry**: capabilities, levels, coordinate map, tombstones paths
+
+### 2. Load registry (architecture)
+
+Read from backbone-resolved paths:
+
+| Backbone Key | Purpose |
+|---|---|
+| `registry.capabilities` | Capability taxonomy — what features each level requires |
+| `registry.levels` | Level definitions — L0 through L6 progression |
+
+Build understanding: levels are the horizontal axis (which rules apply), score is the vertical axis (pass-rate against applicable rules). Level is INPUT to rule selection, not output of scoring.
+
+### 3. Load coordinate map (rule index)
+
+Read `registry/coordinate-map.yml` (from `backbone.registry.coordinate_map`).
+
+Establish the resolution chain:
+```
+Coordinate (e.g., CORE:S:0001)
+  → coordinate-map → slug (e.g., root-instruction-file-exists)
+  → backbone.rules.categories.{cat} → base path (e.g., core/structure/)
+  → base path + slug + "/" → rule directory
+```
+
+Count rules per category for the report. Flag any coordinate-map entries whose directories don't exist.
+
+### 4. Load task-scoped constraints
+
+Read all files in `.claude/rules/`:
+
+| File | Constraint |
+|---|---|
+| `core-rules.md` | Coordinate map sync after rule changes |
+| `schemas.md` | Backbone schema sync after schema changes |
+| `skills.md` | Backbone path resolution for skills |
+
+These are active constraints — they apply to every operation in this session.
+
+### 5. Check project state
+
+Read `VERSION` and `UNRELEASED.md`:
+- Current version number and branch name
+- What changes are staged for next release, grouped by area
+- Whether unreleased changes overlap with any area the agent might touch
+
+### 6. Report understanding
+
+Produce a synthesized context report:
+
+```
+Bootstrap complete.
+
+Project: Reporails Framework v{version} (branch: {branch})
+Rules: {total} ({n} structure, {n} content, {n} context_quality, {n} efficiency, {n} governance, {n} maintenance, {n} agent)
+Levels: L0-L6, {n} capabilities
+Agents: {list from backbone.agents}
+
+Navigation:
+  Coordinate → path: coordinate-map → slug → backbone.rules.categories.{cat}/{slug}/
+  Schemas: backbone.schemas.{name}
+  Agent config: backbone.agents.{agent}.config
+
+Operations:
+  Create rule     → /generate-rule (skeleton + coordinate assignment)
+  Implement rule  → /implement-rule (checks, patterns, fixtures)
+  Test rules      → /test-rules (docker compose local harness, runs fixtures)
+  Validate rules  → /validate-rules (schema + contract validation)
+
+Constraints active:
+  - {constraint summary from each .claude/rules/ file}
+
+Unreleased: {count} changes ({areas touched})
+```
+
+## Examples
+
+```
+> /bootstrap
+
+Bootstrap complete.
+
+Project: Reporails Framework v0.4.1 (branch: 0.5.0)
+Rules: 101 (36 structure, 32 content, 7 context_quality, 5 efficiency, 9 governance, 1 maintenance, 16 agent)
+Levels: L0-L6, 12 capabilities
+Agents: claude, codex, copilot, generic
+
+Navigation:
+  Coordinate → path: coordinate-map → slug → backbone.rules.categories.{cat}/{slug}/
+  Schemas: backbone.schemas.{name}
+  Agent config: backbone.agents.{agent}.config
+
+Operations:
+  Create rule     → /generate-rule
+  Implement rule  → /implement-rule
+  Test rules      → /test-rules (docker local harness)
+  Validate rules  → /validate-rules (schema contracts)
+
+Constraints active:
+  - Coordinate map sync required after rule changes
+  - Backbone schema sync required after schema changes
+  - Skills must resolve paths from backbone
+
+Unreleased: 16 changes (schemas, agents, meta, docs)
+```
+
+## Reference
+
+- Backbone: `.reporails/backbone.yml` — project topology, all path resolution
+- Path resolution: `.shared/knowledge/backbone-resolution.md` — coordinate-to-path algorithm
+- Capabilities: `registry/capabilities.yml` — capability taxonomy per level
+- Levels: `registry/levels.yml` — L0-L6 progression definitions
+- Coordinate map: `registry/coordinate-map.yml` — slug-to-coordinate index
+
+## Quick Reference
+
+| Question | Answer |
+|---|---|
+| How do I find a rule by coordinate? | coordinate-map → slug → `backbone.rules.categories.{cat}/{slug}/` |
+| How do I test rules? | `/test-rules` — docker compose local harness, runs pass/fail fixtures |
+| How do I validate rules against schema? | `/validate-rules` — schema + contract checks |
+| What schemas exist? | `backbone.schemas` — 8 schemas (rule, capability, levels, agent, package, project, sources, user) |
+| What constraints apply? | `.claude/rules/` — core-rules.md, schemas.md, skills.md |

.claude/skills/generate-rule/SKILL.md

@@ -13,16 +13,16 @@ Generate a rule skeleton with coordinate-based ID, directory structure, and plac
 /generate-rule <coordinate> <scope> <title> [--agent <name>]
 ```
 
-- `<coordinate>`: Rule coordinate (e.g., CORE:S:0005, CLAUDE:S:0003)
+- `<coordinate>`: Rule coordinate (e.g., CORE:C:0001, CLAUDE:S:0001)
 - `<scope>`: `core` or agent name (e.g., `claude`)
 - `<title>`: Short title for the rule
 - `--agent <name>`: Agent for path resolution (default: `claude`)
 
 ## Examples
 
 ```
-/generate-rule CORE:S:0005 core "My New Rule"
-/generate-rule CLAUDE:S:0003 claude "Some Agent Rule"
+/generate-rule CORE:C:0006 core "My New Rule"
+/generate-rule CLAUDE:C:0002 claude "Some Agent Rule"
 ```
 
 ## Workflow
@@ -33,7 +33,7 @@ Generate a rule skeleton with coordinate-based ID, directory structure, and plac
 4. Resolve directory path from `backbone.rules.patterns` and `backbone.rules.categories`
 5. Create directory: `{category_path}/{slug}/`
 6. Generate `rule.md` with frontmatter (id, slug, title, category, type, level, targets, checks)
-7. Generate `rule.yml` with OpenGrep patterns (if deterministic/semantic)
+7. Generate `rule.yml` with regex patterns (if deterministic/semantic)
 8. Create `tests/pass/` and `tests/fail/` directories with `.gitkeep`
 9. Update `registry/coordinate-map.yml` with new slug→coordinate entry
 
@@ -48,7 +48,7 @@ Generate a rule skeleton with coordinate-based ID, directory structure, and plac
 | Decision | Result |
 |----------|--------|
 | Structural/file checks only | type: mechanical |
-| OpenGrep pattern matching | type: deterministic |
+| Regex pattern matching | type: deterministic |
 | LLM evaluation needed | type: semantic (prompt field on terminal check) |
 | Has backing sources | Add to backed_by with source IDs from docs/sources.yml |
 | No backing sources | Omit backed_by (optional field) |

.claude/skills/generate-rule/rule-authoring.md

@@ -11,7 +11,7 @@ title: {Title}                    # max 64 chars
 category: structure|content|efficiency|maintenance
 type: deterministic|semantic
 checks:
-  - id: "{RULE_ID}:check:{SLOT}"
+  - id: "{NAMESPACE}.{CATEGORY}.{SLOT}.{descriptive-name}"
     name: {Description}
     severity: critical|high|medium|low
 backed_by: []                     # empty by default
@@ -49,7 +49,7 @@ criteria:
 
 ```yaml
 rules:
-  - id: "{RULE_ID}.check.{SLOT}"
+  - id: "{NAMESPACE}.{CATEGORY}.{SLOT}.{descriptive-name}"
     message: "TODO: {description}"
     severity: WARNING
     languages: [generic]
@@ -63,12 +63,12 @@ rules:
 
 | Scope | Pattern | Example |
 |-------|---------|---------|
-| Core | `CORE:{CAT}:{SLOT}` | `CORE:S:0001`, `CORE:C:0010` |
+| Core | `CORE:{CAT}:{SLOT}` | `CORE:S:0001`, `CORE:C:0005` |
 | Agent | `{AGENT}:{CAT}:{SLOT}` | `CLAUDE:S:0001`, `CODEX:S:0003` |
 | Recommended | `RRAILS:{CAT}:{SLOT}` | `RRAILS:C:0008`, `RRAILS:E:0002` |
 | Recommended Agent | `RRAILS_{AGENT}:{CAT}:{SLOT}` | `RRAILS_CLAUDE:S:0001` |
 
-**Check IDs**: `{RULE_ID}:check:{SLOT}` in rule.md (colons), `{RULE_ID}.check.{SLOT}` in rule.yml (dots — colons invalid in OpenGrep).
+**Check IDs**: `{NAMESPACE}.{CATEGORY}.{SLOT}.{descriptive-name}` — dots and kebab-case name in both rule.md and rule.yml.
 
 ## Valid Values
 
@@ -94,7 +94,7 @@ rules:
 |---------|-----|
 | Using `{{rules_dir}}` in core rules | Core uses only `{{instruction_files}}` |
 | Missing .yml file | Always create both files |
-| Wrong check ID format | Must be `{RULE_ID}:check:{SLOT}` (colons in .md, dots in .yml) |
+| Wrong check ID format | Must be `NAMESPACE.CATEGORY.SLOT.descriptive-name` |
 | Semantic without question | Add question + criteria |
 | Deterministic with question | Remove question + criteria |
 | Hardcoded paths in .yml | Use `{{instruction_files}}` |

.claude/skills/generate-rule/workflow.md

@@ -5,7 +5,7 @@ flowchart TD
     START([/generate-rule coordinate scope title]) --> GATHER[Gather: what, why, type]
     GATHER --> TYPE{Detection method?}
     TYPE -->|Structural checks only| MECH[type: mechanical]
-    TYPE -->|OpenGrep fully decides| DET[type: deterministic]
+    TYPE -->|Regex fully decides| DET[type: deterministic]
     TYPE -->|Needs LLM judgment| SEM[type: semantic<br/>Add question + criteria]
     MECH --> GEN[Generate skeleton files]
     DET --> GEN
@@ -22,15 +22,15 @@ flowchart TD
 | File | Content |
 |------|---------|
 | `rule.md` | Frontmatter (id, slug, title, category, type, level, checks, backed_by) + prose |
-| `rule.yml` | OpenGrep patterns (deterministic/semantic) or `rules: []` (mechanical) |
+| `rule.yml` | Regex patterns (deterministic/semantic) or `rules: []` (mechanical) |
 | `tests/pass/` | Empty — populated by `/implement-rule` |
 | `tests/fail/` | Empty — populated by `/implement-rule` |
 
 ## Placeholder .yml (deterministic/semantic)
 
 ```yaml
 rules:
-  - id: NAMESPACE.CATEGORY.SLOT.check.0001
+  - id: NAMESPACE.CATEGORY.SLOT.descriptive-name
     message: "{description}"
     severity: WARNING
     languages: [generic]
@@ -40,7 +40,7 @@ rules:
         - "{{instruction_files}}"
 ```
 
-Mechanical rules get `rules: []` — no OpenGrep patterns needed.
+Mechanical rules get `rules: []` — no regex patterns needed.
 
 ## Edge Cases