@contentrain/rules 0.1.0

package/prompts/review-mode.md

@@ -0,0 +1,241 @@
+# Review Mode — Review Pending Content Changes
+
+> **Prerequisites:** Read `prompts/common.md` first. All shared rules apply.
+
+This mode is for reviewing content changes on pending `contentrain/*` branches before they are merged. You act as a content quality reviewer, applying all Contentrain rules systematically.
+
+---
+
+## Pipeline
+
+```
+Step 1: List open contentrain/* branches
+Step 2: Show diffs for selected branch
+Step 3: Apply review checklist
+Step 4: Recommend action
+```
+
+---
+
+## Step 1: List Pending Branches
+
+Call `contentrain_status` to see pending changes and open branches. Identify branches with the `contentrain/` prefix that are awaiting review.
+
+Branch naming convention:
+```
+contentrain/{operation}/{model}/{locale}/{timestamp}
+```
+
+Common branch types:
+- `contentrain/content/...` — content updates
+- `contentrain/model/...` — model changes
+- `contentrain/normalize/extract/...` — normalize extraction
+- `contentrain/normalize/reuse/...` — normalize reuse (source patching)
+- `contentrain/new/scaffold-...` — scaffold operations
+
+---
+
+## Step 2: Show Diffs
+
+Examine the changes on the selected branch. Focus on:
+
+- New or modified files in `.contentrain/content/`
+- New or modified files in `.contentrain/models/`
+- Modified source files (for reuse branches)
+- Changes to `.contentrain/context.json`
+
+---
+
+## Step 3: Apply Review Checklist
+
+Evaluate every change against the following categories. Each check has a severity level.
+
+### 3.1 Schema Compliance (severity: error)
+
+- All required fields present and populated with non-empty values
+- Field values match their declared type (string is string, number is number, etc.)
+- Field values satisfy constraints: `min`, `max`, `pattern`, `options`
+- `unique` fields have no duplicates within the model
+- Relation fields reference existing entries in the target model
+- Dictionary entries are flat key-value pairs (all values are strings)
+- Object-map entries use 12-char hex IDs as keys (collections)
+- Model definitions use valid kinds: `singleton`, `collection`, `document`, `dictionary`
+
+### 3.2 Content Quality (severity: warning)
+
+Reference: `rules/shared/content-quality.md`
+
+- Title length: 50-60 characters
+- Excerpt/description: 120-160 characters, complete sentence, ends with period
+- No placeholder text: no "Lorem ipsum", "TODO", "TBD", "[insert here]", "Sample text"
+- No duplicate content across entries (titles, descriptions, body text)
+- Content follows the correct content type pattern (blog post structure, landing page structure, etc.)
+- Tone matches `context.json > conventions.tone` consistently throughout
+- Vocabulary terms match `vocabulary.json` exactly
+- Active voice preferred over passive voice
+- Heading hierarchy is sequential (H1 > H2 > H3, no skips)
+- Exactly one H1 per page/entry
+
+### 3.3 SEO (severity: warning)
+
+Reference: `rules/shared/seo-rules.md`
+
+- Slug format: lowercase, hyphenated, 3-5 words, no special characters
+- Published slugs have not been changed (breaking change)
+- Slugs are identical across all locales
+- Meta description: 120-155 characters, complete sentence, unique
+- Primary keyword within first 30 characters of title
+- All images have alt text (or explicit empty string for decorative)
+- OG fields populated if model supports them
+
+### 3.4 Accessibility (severity: warning)
+
+Reference: `rules/shared/accessibility-rules.md`
+
+- Link text is descriptive and self-explanatory — no "click here", "read more", "learn more"
+- Heading levels reflect document hierarchy, no skipped levels
+- Alt text describes content and function, not appearance
+- Alt text does not start with "Image of" or "Photo of"
+- Alt text under 125 characters
+- No color-only references to convey meaning
+- Error messages identify the field, describe the error, and explain how to fix it
+- Reading level appropriate for content type (grade 8-10 general, grade 6-8 critical)
+
+### 3.5 Security (severity: error)
+
+Reference: `rules/shared/security-rules.md`
+
+- No `<script>` tags in richtext or markdown fields
+- No `javascript:` protocol in any attribute value
+- No event handler attributes (`onerror`, `onclick`, etc.)
+- No forbidden HTML tags (`<iframe>`, `<embed>`, `<object>`, `<form>`, etc.)
+- No secrets or credentials: API keys, tokens, private keys, connection strings
+- No PII in non-typed fields (emails in non-email fields, phones in non-phone fields)
+- All URLs use `https://` (exception: localhost for development)
+- No path traversal sequences (`../`, `..\\`)
+- No executable file extensions disguised as other types
+
+### 3.6 Internationalization (severity: error for completeness, warning for quality)
+
+Reference: `rules/shared/i18n-quality.md`
+
+- All supported locales have entries for every content item (error if missing)
+- All required fields populated in every locale (error if empty)
+- Translations are idiomatic, not word-for-word literal (warning)
+- Tone preserved across locales (warning)
+- Technical terms follow vocabulary or kept in original form (warning)
+- Brand terms match vocabulary per locale (warning)
+- Translated text fits within field `max` constraints (error)
+- Dictionary keys use semantic dot-notation, always in English (warning)
+- Plural forms use correct CLDR categories for each language (warning)
+
+### 3.7 Structural (severity: warning)
+
+- JSON files follow canonical serialization: sorted keys, 2-space indent, trailing newline
+- Collection files use object-map format with sorted entry IDs
+- No orphan references (relation targets that do not exist)
+- Model IDs are kebab-case
+- Field keys are snake_case
+- Dictionary keys use dot-notation
+- Naming conventions are consistent with existing content
+
+---
+
+## Step 4: Recommend Action
+
+Based on the review, recommend one of these actions:
+
+### Approve
+
+All checks pass. No errors, no critical warnings. Content is ready to merge.
+
+```
+Recommendation: APPROVE
+- Schema compliance: PASS
+- Content quality: PASS
+- SEO: PASS (or N/A if not public-facing)
+- Accessibility: PASS
+- Security: PASS
+- i18n: PASS (or N/A if single locale)
+- Structural: PASS
+```
+
+### Request Changes
+
+No blocking errors, but warnings that should be addressed before merge.
+
+```
+Recommendation: REQUEST CHANGES
+Findings:
+- [warning] Title "X" is 45 characters, below recommended 50-60 range
+- [warning] Missing alt text on hero image
+- [warning] German translation of "Settings" uses "Konfiguration" instead of vocabulary term "Einstellungen"
+```
+
+### Reject
+
+Blocking errors that must be fixed. Content cannot be merged in current state.
+
+```
+Recommendation: REJECT
+Findings:
+- [error] Required field "excerpt" is empty in entry "a1b2c3d4e5f6"
+- [error] Relation field "author" references non-existent entry "x9y8z7w6v5u4"
+- [error] Missing locale file: content/blog/blog-post/tr.json
+- [error] XSS pattern detected: <script> tag in richtext field "body"
+```
+
+---
+
+## Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| `error` | Must fix before merge. Content is invalid or unsafe. | REJECT until fixed |
+| `warning` | Should fix. Content is valid but does not meet quality standards. | REQUEST CHANGES or note in approval |
+| `info` | Optional improvement. Content is acceptable but could be better. | Note in approval, do not block |
+
+---
+
+## Review Report Format
+
+Structure your review as follows:
+
+```
+## Review: [branch-name]
+
+### Summary
+[1-2 sentence summary of what this branch changes]
+
+### Findings
+
+#### Errors (must fix)
+- [error] Description of issue → File: path, Field: name
+
+#### Warnings (should fix)
+- [warning] Description of issue → File: path, Field: name
+
+#### Info (optional)
+- [info] Suggestion for improvement → File: path, Field: name
+
+### Recommendation
+[APPROVE | REQUEST CHANGES | REJECT]
+
+### Notes
+[Any additional context, suggestions, or observations]
+```
+
+---
+
+## Checklist
+
+- [ ] All new/modified files examined
+- [ ] Schema compliance verified for every entry
+- [ ] Content quality checked against content-quality.md
+- [ ] SEO rules applied to public-facing content
+- [ ] Accessibility rules checked
+- [ ] Security scan performed (XSS, secrets, PII)
+- [ ] i18n completeness verified (all locales present)
+- [ ] Translation quality assessed (not just present, but correct)
+- [ ] Structural integrity confirmed (canonical JSON, naming conventions)
+- [ ] Clear recommendation provided with specific findings

package/shared/accessibility-rules.md

@@ -0,0 +1,155 @@
+# Accessibility Rules
+
+These rules are MANDATORY for all AI agents creating or editing content in Contentrain projects.
+Violations will be flagged during validation. No exceptions unless explicitly overridden by `context.json` configuration.
+
+---
+
+## Image Accessibility
+
+1. Every `image` type field MUST have a corresponding alt text value. If the model defines an `image_alt` field, populate it. If not, include alt text guidance in the image field's `description` metadata.
+
+2. Alt text MUST describe the image's **content and function**, not its appearance.
+   - GOOD: `"CEO Jane Doe speaking at the 2024 product launch"`
+   - BAD: `"A photo with blue tones and a person on stage"`
+
+3. Decorative images (visual separators, background textures) MUST have alt text set to an empty string `""`. Never leave alt text undefined or null — explicitly set it to `""`.
+
+4. Complex images (charts, infographics, diagrams) MUST have a short alt text summarizing the conclusion, plus a detailed description in an adjacent text field or in the body content.
+   - Example alt: `"Bar chart showing Q3 revenue grew 22% year-over-year"`
+   - Example adjacent text: full data table or written summary
+
+5. Alt text MUST NOT exceed **125 characters**. Screen readers may truncate longer text.
+
+6. Icon images used as interactive elements MUST have alt text describing the **action**, not the icon.
+   - GOOD: `"Search"`, `"Close menu"`, `"Open settings"`
+   - BAD: `"Magnifying glass icon"`, `"X icon"`
+
+7. Do not begin alt text with "Image of" or "Photo of" — the screen reader already announces it as an image.
+
+---
+
+## Language & Readability
+
+1. Target a **grade 8-10 reading level** (Flesch-Kincaid) for general content.
+
+2. Target **grade 6-8** for public-facing critical content: legal notices, safety information, error messages, onboarding flows.
+
+3. Use plain language. Prefer common words over formal synonyms:
+   - "use" not "utilize"
+   - "start" not "commence"
+   - "help" not "facilitate"
+   - "buy" not "purchase"
+   - "end" not "terminate"
+
+4. Define every acronym and abbreviation on first use: `"Content Management System (CMS)"`. After the first definition, use the acronym freely.
+
+5. Do not use jargon unless the content targets a technical audience. Check `context.json > tone` to determine the audience. When `tone` is `"technical"`, domain-specific terms are acceptable without definitions.
+
+6. Keep sentences short: **15-20 words average**. Break long sentences at natural clause boundaries.
+
+7. Keep paragraphs short: **3-5 sentences maximum**. Use line breaks between paragraphs.
+
+8. Use active voice. Passive voice is acceptable only when the actor is unknown or irrelevant.
+   - GOOD: `"The system saves your changes automatically."`
+   - BAD: `"Your changes are saved automatically by the system."`
+
+---
+
+## Link Text
+
+1. Link text MUST be descriptive and self-explanatory. It must make sense **out of context** because screen readers present links in an isolated list.
+   - GOOD: `"Download the 2024 Annual Report"`
+   - BAD: `"Click here"`
+
+2. NEVER use these as standalone link text: `"click here"`, `"read more"`, `"learn more"`, `"here"`, `"link"`, `"this"`.
+
+3. For file downloads, include the file type and size in the link text:
+   - `"Download the Q3 Budget (PDF, 2.4 MB)"`
+
+4. Do not use the raw URL as link text unless the content is specifically listing URLs.
+
+5. Keep link text concise — describe the destination or action in 2-8 words.
+
+---
+
+## Heading Semantics
+
+1. Headings MUST describe the content of their section. Never use headings purely for visual styling (font size, bold).
+
+2. Heading levels MUST reflect **document hierarchy**:
+   - `h2` for top-level sections within the page
+   - `h3` for subsections of an `h2`
+   - `h4` for subsections of an `h3`
+   - Never skip levels (e.g., `h2` directly to `h4`)
+
+3. Every distinct content section SHOULD have a heading.
+
+4. Headings MUST NOT be empty or contain only whitespace.
+
+5. Do not duplicate heading text within the same page unless sections are genuinely distinct (e.g., "Overview" under two different parent headings is acceptable).
+
+---
+
+## Content Structure
+
+1. Use **semantic markup** appropriate to the content type:
+   - Unordered lists (`ul`) for items without sequence
+   - Ordered lists (`ol`) for steps or ranked items
+   - Headings for section titles
+   - Paragraphs for body text
+   - Blockquotes for quoted material
+
+2. Tables MUST include a header row or header column. Keep table structure simple — avoid merged cells and nested tables.
+
+3. Provide a text alternative for every piece of non-text content (images, charts, embedded media).
+
+4. Sequential content (steps, instructions, timelines) MUST follow logical reading order. Do not rely on CSS or layout to reorder content.
+
+5. Lists MUST have at least two items. A single-item list should be rewritten as a paragraph or inline text.
+
+---
+
+## Color & Visual References
+
+1. NEVER use color alone to convey meaning.
+   - BAD: `"Required fields are highlighted in red."`
+   - GOOD: `"Required fields are marked with an asterisk (*)."`
+
+2. Do not reference visual position in content text.
+   - BAD: `"Click the button on the right."`
+   - GOOD: `"Click the Submit button."`
+
+3. Ensure all text content is meaningful without any visual context. Content must be understandable when read aloud or rendered in plain text.
+
+---
+
+## Error Messages & Forms
+
+1. Error messages MUST identify **which field** has the error.
+
+2. Error messages MUST describe **what the error is** and how to fix it.
+   - GOOD: `"Enter a valid email address (e.g., name@example.com)."`
+   - BAD: `"Invalid input."`
+
+3. Use **positive framing** — tell the user what to do, not what they did wrong.
+   - GOOD: `"Enter a date in YYYY-MM-DD format."`
+   - BAD: `"Wrong date format."`
+
+4. Group related form fields with descriptive labels. Every input field MUST have a label.
+
+5. Do not use placeholder text as a substitute for labels.
+
+---
+
+## Multimedia
+
+1. Video content MUST reference a transcript — either as inline content, a URL, or a relation to a document entry.
+
+2. Audio content MUST have a text transcript available.
+
+3. If content auto-plays, note this in metadata so the frontend can provide pause/stop controls. Auto-playing media with audio is strongly discouraged.
+
+4. Time-based media (video, audio, animations) MUST include duration information when the model supports it.
+
+5. Animated content (GIFs, auto-playing videos) should be flagged if longer than 5 seconds — provide a mechanism to pause.