diff --git a/.claude/rules/core-rules.md b/.claude/rules/core-rules.md index 225ecd6..b435d41 100644 --- a/.claude/rules/core-rules.md +++ b/.claude/rules/core-rules.md @@ -4,10 +4,10 @@ globs: - "agents/*/rules/**" --- -# Backbone Index Sync +# Coordinate Map Sync -After creating, deleting, or renaming a rule directory, update `rules.index` in `.reporails/backbone.yml` to keep the index complete. +After creating, deleting, or renaming a rule directory, update `registry/coordinate-map.yml` to keep the mapping complete. -Format: `{ID}: {slug}` (e.g., `M4: backbone-index-completeness`). +Format: `slug: "COORDINATE"` (e.g., `backbone-index-completeness: "CORE:M:0004"`). -See rule M4 for the completeness requirement. +See rule CORE:M:0004 for the completeness requirement. diff --git a/.claude/rules/skills.md b/.claude/rules/skills.md index 63c0410..ff5e4dd 100644 --- a/.claude/rules/skills.md +++ b/.claude/rules/skills.md @@ -3,8 +3,8 @@ globs: - ".claude/skills/**" --- -# Backbone Artifact References +# Backbone Path References -Skills resolve paths from `.reporails/backbone.yml`. When referencing a new artifact (schema, source file, etc.), verify the path exists in `backbone.artifacts` or `backbone.schemas`. +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`. See `.shared/knowledge/backbone-resolution.md` for the full resolution table. diff --git a/.claude/skills/add-changelog-entry/SKILL.md b/.claude/skills/add-changelog-entry/SKILL.md index f08ef79..201ca27 100644 --- a/.claude/skills/add-changelog-entry/SKILL.md +++ b/.claude/skills/add-changelog-entry/SKILL.md @@ -11,9 +11,11 @@ Automatically add a changelog entry to PROJECT_ROOT/UNRELEASED.md. 1. Check git diff or recent file modifications 2. Determine the area from the file path: - - rules/*.md → [RULES] - - capability-levels.md with L1-L6 changes → [L1]-[L6] - - README.md → [DOCS] + - core/**/rule.md → [RULES] + - registry/ → [REGISTRY] + - schemas/ → [SCHEMAS] + - agents/ → [AGENTS] + - docs/ → [DOCS] - CLAUDE.md, backbone.yml, .claude/, .reporails/ → [META] 3. Determine the category: - New files/content → Added @@ -39,20 +41,22 @@ Added, Changed, Deprecated, Removed, Fixed, Security ## Areas -- [RULES] – Rule definitions (S, C, M, G, E) -- [L1]-[L6] – Level-specific changes -- [DOCS] – README, general documentation +- [RULES] – Rule definitions (structure, content, efficiency, maintenance, governance) +- [REGISTRY] – Capabilities, levels, coordinate map, tombstones +- [SCHEMAS] – Schema definitions +- [AGENTS] – Agent configurations and agent-specific rules +- [DOCS] – Documentation - [META] – CLAUDE.md, backbone.yml, repo structure ## Example ```markdown ### Added -- [RULES]: S5 rule for heading depth validation -- [L4]: Added hooks requirement to level definition +- [RULES]: CORE:G:0001 rule for governance policy validation +- [REGISTRY]: Added new capability to L4 ### Changed -- [DOCS]: Updated README with CLI link +- [SCHEMAS]: Updated rule schema to v0.1.0 ``` -Do not ask for confirmation. Just do it. +Do not ask for confirmation. Just do it. \ No newline at end of file diff --git a/.claude/skills/generate-rule/SKILL.md b/.claude/skills/generate-rule/SKILL.md index f44c2f9..c141d1a 100644 --- a/.claude/skills/generate-rule/SKILL.md +++ b/.claude/skills/generate-rule/SKILL.md @@ -5,15 +5,15 @@ description: Generate a rule skeleton with proper schema and directory structure # /generate-rule -Generate a rule skeleton with proper directory structure, frontmatter, and placeholder files. +Generate a rule skeleton with coordinate-based ID, directory structure, and placeholder files. ## Usage ``` -/generate-rule [--agent <name>] +/generate-rule <coordinate> <scope> <title> [--agent <name>] ``` -- `<id>`: Rule ID (e.g., S5, C6, CLAUDE_S3) +- `<coordinate>`: Rule coordinate (e.g., CORE:S:0005, CLAUDE:S:0003) - `<scope>`: `core` or agent name (e.g., `claude`) - `<title>`: Short title for the rule - `--agent <name>`: Agent for path resolution (default: `claude`) @@ -21,28 +21,34 @@ Generate a rule skeleton with proper directory structure, frontmatter, and place ## Examples ``` -/generate-rule S5 core "My New Rule" -/generate-rule CLAUDE_S3 claude "Some Agent Rule" +/generate-rule CORE:S:0005 core "My New Rule" +/generate-rule CLAUDE:S:0003 claude "Some Agent Rule" ``` ## Workflow -Follow: [workflow.md](workflow.md) +1. Validate coordinate is not in `registry/tombstones.yml` +2. Validate coordinate slot is not already taken in `registry/coordinate-map.yml` +3. Determine category from coordinate letter (S/C/E/M/G) +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) +8. Create `tests/pass/` and `tests/fail/` directories with `.gitkeep` +9. Update `registry/coordinate-map.yml` with new slug→coordinate entry ## Reference -- [Rule authoring](rule-authoring.md) — Templates and validation - -## Path Resolution - -Resolve all rule and artifact paths from `.reporails/backbone.yml` instead of hardcoding. -See [@.shared/knowledge/backbone-resolution.md](../../../.shared/knowledge/backbone-resolution.md) for the resolution table and ID-to-path algorithm. +- Schema: `schemas/rule.schema.yml` — field definitions and validation rules +- Registry: `registry/coordinate-map.yml` — existing coordinates +- Registry: `registry/tombstones.yml` — dead slots ## Quick Reference | Decision | Result | |----------|--------| -| OpenGrep fully decides | type: deterministic | -| LLM needed | type: semantic (add question + criteria) | -| Has backing sources | Add to backed_by (optional) | -| No backing sources | `backed_by: []` (valid default) | +| Structural/file checks only | type: mechanical | +| OpenGrep 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) | \ No newline at end of file diff --git a/.claude/skills/generate-rule/rule-authoring.md b/.claude/skills/generate-rule/rule-authoring.md index 126844c..dc17f34 100644 --- a/.claude/skills/generate-rule/rule-authoring.md +++ b/.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: {ID}-{check-slug} + - id: "{RULE_ID}:check:{SLOT}" name: {Description} severity: critical|high|medium|low backed_by: [] # empty by default @@ -49,7 +49,7 @@ criteria: ```yaml rules: - - id: {ID}-{check-slug} + - id: "{RULE_ID}.check.{SLOT}" message: "TODO: {description}" severity: WARNING languages: [generic] @@ -63,8 +63,12 @@ rules: | Scope | Pattern | Example | |-------|---------|---------| -| Core | `^[SCEGM][0-9]+$` | S1, C5, E2 | -| Agent | `^[A-Z]+_[SCEGM][0-9]+$` | CLAUDE_S1 | +| Core | `CORE:{CAT}:{SLOT}` | `CORE:S:0001`, `CORE:C:0010` | +| 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). ## Valid Values @@ -90,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}-{suffix}` | +| Wrong check ID format | Must be `{RULE_ID}:check:{SLOT}` (colons in .md, dots in .yml) | | Semantic without question | Add question + criteria | | Deterministic with question | Remove question + criteria | | Hardcoded paths in .yml | Use `{{instruction_files}}` | diff --git a/.claude/skills/generate-rule/workflow.md b/.claude/skills/generate-rule/workflow.md index 26b9d7c..0991cb4 100644 --- a/.claude/skills/generate-rule/workflow.md +++ b/.claude/skills/generate-rule/workflow.md @@ -2,47 +2,51 @@ ```mermaid flowchart TD - START([/generate-rule id scope title]) --> GATHER[Gather: what, why, type] - GATHER --> TYPE{OpenGrep fully decides?} - TYPE -->|Yes| DET[type: deterministic] - TYPE -->|No| SEM[type: semantic<br/>Add question + criteria] - DET --> GEN[Generate skeleton files] + 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 -->|Needs LLM judgment| SEM[type: semantic<br/>Add question + criteria] + MECH --> GEN[Generate skeleton files] + DET --> GEN SEM --> GEN - GEN --> MD[Create .md with frontmatter<br/>+ Good/Bad examples] - MD --> YML[Create .yml with placeholder pattern] - YML --> TESTS[Create tests/pass.md + tests/fail.md] - TESTS --> INDEX[Update backbone rules.index] - INDEX --> CHANGELOG[/add-changelog-entry] + GEN --> MD[Create rule.md with frontmatter<br/>+ Pass/Fail examples] + MD --> YML[Create rule.yml<br/>patterns or empty rules list] + YML --> TESTS[Create tests/pass/ + tests/fail/] + TESTS --> COORDMAP[Update registry/coordinate-map.yml] + COORDMAP --> CHANGELOG[/add-changelog-entry] ``` ## What Gets Generated | File | Content | |------|---------| -| `{id}-{slug}.md` | Frontmatter + heading + Pattern section (Good/Bad) | -| `{id}-{slug}.yml` | Placeholder with TODO pattern | -| `tests/pass.md` | Empty file with TODO comment | -| `tests/fail.md` | Empty file with TODO comment | +| `rule.md` | Frontmatter (id, slug, title, category, type, level, checks, backed_by) + prose | +| `rule.yml` | OpenGrep patterns (deterministic/semantic) or `rules: []` (mechanical) | +| `tests/pass/` | Empty — populated by `/implement-rule` | +| `tests/fail/` | Empty — populated by `/implement-rule` | -## Placeholder .yml +## Placeholder .yml (deterministic/semantic) ```yaml rules: - - id: {ID}-{check-slug} - message: "TODO: {description}" + - id: NAMESPACE.CATEGORY.SLOT.check.0001 + message: "{description}" severity: WARNING languages: [generic] - pattern-regex: "TODO" # placeholder — to be filled by tooling or contributor + pattern-regex: "TODO" # placeholder — to be filled by /implement-rule paths: include: - "{{instruction_files}}" ``` +Mechanical rules get `rules: []` — no OpenGrep patterns needed. + ## Edge Cases **Core vs Agent rules:** - Core rules use only `{{instruction_files}}` - Agent rules can use `{{rules_dir}}`, `{{skills_dir}}`, etc. -**Path resolution:** Resolve rule paths from `.reporails/backbone.yml` using `rules.index`, `rules.categories`, and `rules.patterns`. -See [@.shared/knowledge/backbone-resolution.md](../../../.shared/knowledge/backbone-resolution.md) for the ID-to-path algorithm and directory structure. +**Path resolution:** Resolve rule paths from `.reporails/backbone.yml` using `rules.categories` and `rules.patterns`. +See [@.shared/knowledge/backbone-resolution.md](../../../.shared/knowledge/backbone-resolution.md) for the coordinate-to-path algorithm. \ No newline at end of file diff --git a/.claude/skills/implement-rule/SKILL.md b/.claude/skills/implement-rule/SKILL.md new file mode 100644 index 0000000..00a95ab --- /dev/null +++ b/.claude/skills/implement-rule/SKILL.md @@ -0,0 +1,253 @@ +--- +name: implement-rule +description: Implement checks, patterns, and fixtures for an existing rule skeleton +--- + +# /implement-rule + +Implement checks, OpenGrep patterns, and test fixtures for an existing rule that has a skeleton but empty `checks: []`. + +## Usage + +``` +/implement-rule <coordinate> [--agent <name>] [--dry-run] +``` + +- `<coordinate>`: Rule coordinate (e.g., CORE:S:0005, CLAUDE:S:0003) +- `--agent <name>`: Agent for template var resolution (default: `claude`) +- `--dry-run`: Show what would be generated without writing files + +## Examples + +``` +/implement-rule CORE:S:0002 +/implement-rule CORE:M:0003 --agent codex +/implement-rule CLAUDE:S:0001 --dry-run +``` + +## Workflow + +Follow: [@.shared/workflows/rule-implementation.md](../../../.shared/workflows/rule-implementation.md) + +### 1. Locate + +Resolve rule directory from coordinate: +1. Look up slug in `registry/coordinate-map.yml` (backbone key: `registry.coordinate_map`) +2. Determine category from coordinate letter: S=structure, C=content, E=efficiency, M=maintenance, G=governance +3. For core rules: `{categories.{category}}/{slug}/` +4. For agent rules: `{agent_rules.{agent}}/{slug}/` + +### 2. Read + +Parse `rule.md` frontmatter and body: +- Extract: `id`, `type`, `level`, `targets`, `question`, `criteria`, Pass/Fail examples from body +- **Abort if `checks:` is already non-empty** — rule is already implemented +- Identify the **violation class**: what structural or content pattern makes an instruction file FAIL this rule? The Pass/Fail examples are illustrations, not specifications. + +### 3. Analyze — Pattern Design + +This is the critical step. The goal is to design a check that catches the **class of violation**, not a regex that discriminates between two fixture files. + +#### How to use frontmatter fields + +| Field | Design role | +|-------|------------| +| `title` | Names the concern — what property should instruction files have? | +| `question` | Defines the evaluation question — what are we asking about the file? | +| `criteria` | Lists observable properties of a PASSING file — invert each to get violation indicators | +| Pass example | ONE illustration of a good file — extract the structural pattern that makes it good | +| Fail example | ONE illustration of a bad file — extract the structural pattern that makes it bad | + +**Think in terms of violation structure, not fixture discrimination.** + +#### Mechanical rules + +- Select check function(s) from the 10 available: `file_exists`, `directory_exists`, `directory_contains`, `git_tracked`, `frontmatter_key`, `file_count`, `line_count`, `byte_size`, `path_resolves`, `extract_imports` +- Derive `args` from rule description (e.g., `max: 300` for `line_count`) +- No OpenGrep patterns needed + +#### Deterministic rules — violation detection + +Design a pattern that matches the **structural signature of the violation**: + +1. Read the Fail example. Ask: what STRUCTURAL pattern makes this file bad? Not "what text does it contain?" but "what is the shape of the problem?" +2. Read the `criteria` (if present). Each criterion describes a PASSING property. Invert: what does a file look like when it LACKS this property? +3. Design a regex that matches the structural signature, not a specific keyword. + +**Two violation types:** + +| Type | Approach | Example | +|------|----------|---------| +| **Presence of bad content** | Pattern matches the violation directly | Secrets: `(?i)(api[_-]?key\|secret)\s*[=:]\s*['"]?[A-Za-z0-9]{8,}` | +| **Absence of good content** | Pattern matches the structural gap left by the missing content | Missing description: `^#\s+[^\n]+\n\s*\n##` (title followed immediately by section heading, no prose between) | + +**NEVER use presence-then-negate as the primary strategy.** A pattern with `negate: true` that looks for "does good content exist?" is fragile — any incidental keyword match satisfies it. Instead, find the structural shape of the violation itself. + +`negate: true` is acceptable ONLY when: +- The violation is purely about absence AND +- No structural signature exists (the bad file is structurally identical to the good file, just missing a keyword) AND +- You've confirmed there is no structural pattern to detect + +For core rules: use `{{instruction_files}}` in paths (not `**/*.md`). + +#### Semantic rules — candidate surfacing + +Semantic rules have two phases: deterministic pre-check → semantic evaluation. + +**Pre-check purpose**: Find text that EXHIBITS the violation pattern — content that needs human/LLM judgment to determine if it's actually a violation. + +**Pre-check design**: +1. Read the `question` field. What kind of content needs to be EVALUATED? +2. Read the `criteria` field. What observable text patterns MIGHT indicate a violation but need context to confirm? +3. Design a pattern that matches these ambiguous indicators — not content matching the rule's topic, but content matching the violation's surface appearance. + +Example: Rule "no-linter-enforceable-style" +- BAD pre-check: `(?i)(style|format|indent)` — matches the rule's topic, not violation indicators +- GOOD pre-check: `(?i)(indent|tab|space|bracket|semicolon|line.length|80.char|120.char)` — matches specific linter-enforceable patterns + +Terminal semantic check uses `prompt` derived from rule's `question`/`criteria` fields. + +### 4. Generate checks + +Write `checks:` array in `rule.md` frontmatter: +- IDs follow `{RULE_ID}:check:{SLOT}` format (e.g., `CORE:S:0005:check:0001`) +- Check types must not exceed rule type ceiling: + - `mechanical` rule → only `mechanical` checks + - `deterministic` rule → `mechanical` + `deterministic` checks + - `semantic` rule → any types, semantic must be last +- Severity from rule context: `critical` for L1, `high`/`medium` for L2+ + +### 5. Generate patterns + +For deterministic/semantic rules, write OpenGrep rules in `rule.yml`: +- `id` matches the check ID from frontmatter +- `languages: [generic]` for markdown targets +- `paths.include` uses template vars (`{{instruction_files}}`) +- Pattern captures the violation, not the desired state +- Severity mapping: critical→ERROR, high/medium/low→WARNING + +For mechanical-only rules: leave `rule.yml` as `rules: []`. + +### 6. Generate fixtures + +Fixtures simulate REAL instruction files, not minimal test content. + +**Pass fixture** (`tests/pass/`): +- A realistic instruction file (30-80 lines) that a real project might have +- Contains the structural patterns that satisfy the rule +- Include realistic sections, commands, and project context — not just the minimum to pass +- File names match resolved template vars (e.g., `CLAUDE.md` for claude agent) + +**Fail fixture** (`tests/fail/`): +- A realistic instruction file that exhibits the specific violation +- The violation should be the ONLY difference from a reasonable file — don't make the fail fixture obviously broken in multiple ways +- Must trigger the pattern's structural signature, not just be "bad in general" + +**Fixture quality check**: After generating fixtures, re-read them and ask: +- Does the pass fixture look like a real CLAUDE.md from a real project? +- Does the fail fixture look like a plausible mistake someone would make? +- Would the pattern catch the fail fixture for the RIGHT reason (structural violation match), not an incidental one? + +Remove `.gitkeep` from directories that now have real fixture content. + +### 7. Verify + +Run the test harness: +```bash +docker compose -f runtime/docker-compose.yml run --rm test --rule <coordinate> +``` +- All checks must pass for both pass and fail fixtures +- If test fails: re-examine the violation class analysis (step 3), not just the regex. The pattern may be structurally wrong, not just syntactically wrong. + +## Reference + +- Schema: `schemas/rule.schema.yml` — check field definitions, mechanical check names, severity enum +- Patterns: `docs/opengrep-guide.md` — pattern syntax, generic mode, combining patterns +- Runtime: `runtime/` — test runner, fixture format, mechanical check implementations +- Agent config: `agents/{agent}/config.yml` — template var values per agent +- Path resolution: `.shared/knowledge/backbone-resolution.md` + +## Quick Reference + +| Rule type | Modifies rule.md | Modifies rule.yml | Fixture content | +|-----------|-----------------|-------------------|-----------------| +| mechanical | checks with `check` + `args` | No change (`rules: []`) | Files/dirs matching check function expectations | +| deterministic | checks with `pattern` + `message` | OpenGrep patterns | Content triggering/not triggering pattern | +| semantic | pre-checks + terminal `prompt` | OpenGrep for pre-checks | Content producing/not producing candidates | + +## Severity Mapping + +| rule.md severity | rule.yml severity | +|------------------|-------------------| +| critical | ERROR | +| high | WARNING | +| medium | WARNING | +| low | WARNING | + +## Pattern Design Examples + +### Good: Structural violation detection + +Rule: "has-project-description" — file must open with a project description. + +**Violation structure**: Title exists, but next non-blank line is a section heading (no description prose between). + +```yaml +pattern-regex: "^#\\s+[^\\n]+\\n\\s*\\n##" +message: "Title followed immediately by section heading — no project description" +``` + +This catches the SHAPE of the problem: `# Title\n\n## Section` with nothing between. + +### Bad: Minimal fixture discrimination + +Same rule, but designed to discriminate fixtures: + +```yaml +pattern-regex: "\\A## " +message: "File opens with H2 instead of project description" +``` + +This only catches files starting with `##` — misses the primary failure mode (title present, description absent). + +### Good: Absence via structural gap + +Rule: "has-commands" — file must document executable commands. + +**Violation structure**: File has sections but none contain backtick-wrapped commands. + +```yaml +# Combined pattern: file has 2+ sections but zero backtick commands +patterns: + - pattern-regex: "^## " + - pattern-not-regex: "`[a-z]+ .+`" +``` + +This requires both conditions: structured file (has sections) AND no commands. A file with no structure at all fails a different rule. + +### Bad: Presence check with negate + +Same rule, but as a negated presence check: + +```yaml +pattern-regex: "`[a-z]+ .+`" +negate: true # fragile — any backtick content satisfies this +``` + +A file containing `` `see above` `` or `` `my-var` `` passes this check despite having no actual commands. + +## Common Mistakes + +| Mistake | Fix | +|---------|-----| +| Pattern discriminates fixtures instead of catching violation class | Re-analyze: what is the STRUCTURAL SHAPE of the violation? | +| Using `negate: true` as primary strategy | Find the structural gap pattern. Negate is last resort only. | +| Pre-check matches rule topic instead of violation indicators | Pre-check should find text that NEEDS judgment, not text about the topic | +| Fixture is minimal synthetic content | Write realistic 30-80 line instruction files | +| Fail fixture is broken in multiple ways | One specific violation in an otherwise reasonable file | +| Pattern matches desired state | Invert: pattern must match the violation | +| Using `**/*.md` in paths | Use `{{instruction_files}}` template var | +| Missing `cross_file: true` | Add when pattern operates across target set | +| Semantic rule without pre-checks | Always add deterministic pre-check before semantic | +| Fixture file named wrong | Must match resolved template var (e.g., `CLAUDE.md`) | +| Leaving `.gitkeep` alongside real fixtures | Remove `.gitkeep` when adding content | \ No newline at end of file diff --git a/.claude/skills/manage-agent-config/SKILL.md b/.claude/skills/manage-agent-config/SKILL.md index 6941101..aeeb7c6 100644 --- a/.claude/skills/manage-agent-config/SKILL.md +++ b/.claude/skills/manage-agent-config/SKILL.md @@ -14,9 +14,9 @@ Manage agent configuration files. Config paths resolved from `backbone.agents.{a ``` **Actions:** -- `validate` — Check config against schema and completeness +- `validate` — Check config against schema - `create` — Create new agent config interactively -- `audit` — Deep audit: which rules apply, which should be excluded/overridden +- `audit` — Audit: which vars are defined, which are missing - `sync` — Update config based on audit findings **Examples:** @@ -33,21 +33,21 @@ Manage agent configuration files. Config paths resolved from `backbone.agents.{a 1. Load agent config from `backbone.agents.{agent}.config` 2. Check against schema from `backbone.schemas.agent` -3. Verify universal variables exist +3. Verify required vars exist (main_instruction_file, instruction_files) 4. Report issues ### Create -1. Prompt for agent details (name, prefix, file patterns) +1. Prompt for agent details (name, file patterns) 2. Determine feature support (rules dir, skills, etc.) -3. Generate config with appropriate excludes +3. Generate config with appropriate vars and excludes 4. Validate and save ### Audit 1. Load agent config -2. For each core rule, check if agent supports the feature -3. Compare against current excludes/overrides +2. Check all vars resolve to existing paths +3. Verify excludes patterns are valid 4. Generate recommendations ### Sync @@ -60,12 +60,4 @@ Manage agent configuration files. Config paths resolved from `backbone.agents.{a Resolve agent config and schema paths from `.reporails/backbone.yml`: - Agent config: `backbone.agents.{agent}.config` -- Agent schema: `backbone.schemas.agent` - -See [@.shared/knowledge/backbone-resolution.md](../../../.shared/knowledge/backbone-resolution.md). - -## Reference Files - -- [validation-checks.md](validation-checks.md) — Schema and completeness checks -- [audit-process.md](audit-process.md) — How to audit systematically -- [feature-matrix.md](feature-matrix.md) — Agent feature support reference +- Agent schema: `backbone.schemas.agent` \ No newline at end of file diff --git a/.claude/skills/manage-agent-config/feature-matrix.md b/.claude/skills/manage-agent-config/feature-matrix.md index 22fe001..d6f1476 100644 --- a/.claude/skills/manage-agent-config/feature-matrix.md +++ b/.claude/skills/manage-agent-config/feature-matrix.md @@ -35,13 +35,13 @@ Core rules only. For recommended rule excludes, see reporails/recommended. ### Copilot ```yaml excludes: - - E2 # Import Count — no imports (single file) + - CORE:S:0007 # Decomposed instruction system — single file only ``` ### Codex ```yaml excludes: - - E2 # Import Count — no imports (single file) + - CORE:S:0007 # Decomposed instruction system — single file only ``` ### Cursor @@ -61,8 +61,7 @@ excludes: [] ### By Agent Type **Single-file agents (Copilot, Codex):** -- S1 severity may need adjustment (longer files acceptable) -- S2 progressive disclosure less relevant +- CORE:S:0005 severity may need adjustment (longer files acceptable without @imports) **Multi-file agents (Claude, Cursor):** - Default severities generally appropriate @@ -72,8 +71,7 @@ excludes: [] | Rule | Override consideration | |------|----------------------| -| S1-size-limits | Single-file agents may need higher limit | -| C5-has-version-date | Some teams version differently | +| CORE:S:0005 | Single-file agents may need higher line limit | ## Adding New Agents @@ -82,4 +80,4 @@ excludes: [] 3. Determine file patterns 4. Compile excludes based on unsupported features 5. Create config with `/manage-agent-config create {agent}` -6. Audit with `/manage-agent-config audit {agent}` +6. Audit with `/manage-agent-config audit {agent}` \ No newline at end of file diff --git a/.claude/skills/manage-agent-config/validation-checks.md b/.claude/skills/manage-agent-config/validation-checks.md index 9eba567..f161b58 100644 --- a/.claude/skills/manage-agent-config/validation-checks.md +++ b/.claude/skills/manage-agent-config/validation-checks.md @@ -31,9 +31,9 @@ For each core rule, verify agent supports the underlying feature: | Rule | Feature Required | Exclude if missing | |------|------------------|-------------------| -| E2 | Import references | ✓ | -| CLAUDE_S1 | Hierarchical memory | ✓ (Claude-specific) | -| CLAUDE_S2 | Path-scoped rules | ✓ (Claude-specific) | +| CORE:S:0007 | Multiple instruction files | ✓ (single-file agents) | +| CLAUDE:S:0001 | CLAUDE.md file placement | ✓ (non-Claude agents — auto-excluded by namespace) | +| CLAUDE:S:0003 | Rules directory structure | ✓ (non-Claude agents — auto-excluded by namespace) | ## Overrides Review @@ -52,10 +52,8 @@ Example: ```yaml # Agent supports the feature but with different expectations overrides: - S1-root-too-long: + CORE:S:0005: severity: medium # This agent allows longer files - E5-no-grep-guidance: - disabled: true # Agent handles this differently ``` ## Validation Command @@ -67,4 +65,4 @@ yq eval '.' agents/{agent}/config.yml # Check required fields yq eval '.vars.main_instruction_file' agents/{agent}/config.yml yq eval '.vars.instruction_files' agents/{agent}/config.yml -``` +``` \ No newline at end of file diff --git a/.claude/skills/manage-levels/SKILL.md b/.claude/skills/manage-levels/SKILL.md index 46df20d..a3f5cae 100644 --- a/.claude/skills/manage-levels/SKILL.md +++ b/.claude/skills/manage-levels/SKILL.md @@ -1,11 +1,11 @@ --- name: manage-levels -description: Sync, diff, and list level-rule mappings from capability matrix +description: Sync, diff, and list level-capability mappings from registry --- # /manage-levels -Manage `levels.yml` from the authoritative `docs/capability-levels.md` Capability Assessment Matrix. +Manage level definitions in `registry/levels.yml` against the capability taxonomy in `registry/capabilities.yml`. ## Usage @@ -17,17 +17,17 @@ Manage `levels.yml` from the authoritative `docs/capability-levels.md` Capabilit | Command | Description | |---------|-------------| -| `sync` | Parse matrix from capability-levels.md, regenerate levels.yml | -| `diff` | Show discrepancies between matrix and current levels.yml without writing | -| `list [level]` | List rules per level (all levels, or a specific one like `L2`) | +| `sync` | Regenerate levels.yml from capabilities.yml | +| `diff` | Show discrepancies between capabilities and levels without writing | +| `list [level]` | List capabilities per level (all levels, or a specific one like `L2`) | ## Examples ``` -/manage-levels sync # Regenerate levels.yml from matrix +/manage-levels sync # Regenerate levels.yml from capabilities /manage-levels diff # Show discrepancies only -/manage-levels list # List all levels and their rules -/manage-levels list L2 # List rules at L2 only +/manage-levels list # List all levels and their capabilities +/manage-levels list L2 # List capabilities at L2 only ``` ## Workflow @@ -36,8 +36,9 @@ Follow: [@.shared/workflows/level-sync.md](../../../.shared/workflows/level-sync ## Quick Reference -| Source of truth | `backbone.artifacts.capability_levels` | +| Source of truth | `registry/capabilities.yml` | |---|---| -| Derived artifact | `backbone.artifacts.levels` | -| Assignment logic | First `+` in a row = rule's introduction level | -| Level metadata | Name and description from Level Descriptions section | +| Derived file | `registry/levels.yml` | +| Assignment logic | Each capability declares its level | +| Level metadata | Names and descriptions in levels.yml | +| Schema | `schemas/levels.schema.yml` | \ No newline at end of file diff --git a/.claude/skills/validate-rules/SKILL.md b/.claude/skills/validate-rules/SKILL.md index c14a899..ff1d584 100644 --- a/.claude/skills/validate-rules/SKILL.md +++ b/.claude/skills/validate-rules/SKILL.md @@ -5,41 +5,41 @@ description: Validate rules against schema and contracts # /validate-rules -Validate rules against their schema and .md/.yml contracts. +Validate rules against their schema and rule.md/rule.yml contracts. ## Usage ``` -/validate-rules [id] [options] +/validate-rules [coordinate] [options] ``` **Options:** -- `--category <cat>`: Validate only rules in category +- `--category <cat>`: Validate only rules in category (structure, content, efficiency, maintenance, governance) ## Examples ``` /validate-rules # All rules -/validate-rules S1 # Single rule +/validate-rules CORE:S:0001 # Single rule /validate-rules --category structure # Category filter ``` ## Workflow -Follow: [workflow.md](workflow.md) - -## Reference - -- [Validation](validation.md) — Validation levels - -## Path Resolution - -Resolve all rule and artifact paths from `.reporails/backbone.yml` instead of hardcoding. -See [@.shared/knowledge/backbone-resolution.md](../../../.shared/knowledge/backbone-resolution.md) for the resolution table and ID-to-path algorithm. +1. Load rule schema from `backbone.schemas.rule` +2. Load coordinate map from `backbone.registry.coordinate_map` +3. Resolve rule directories via `backbone.rules.patterns` +4. For each rule: + - Validate rule.md frontmatter against schema + - Validate rule.yml patterns match check IDs in rule.md + - Verify coordinate exists in coordinate-map.yml + - Verify check types don't exceed declared rule type ceiling + - Verify supersedes target is at a strictly lower level ## Quick Reference | Level | Check | |-------|-------| -| 1 | Schema: fields, types, format | -| 2 | Contract: .md <-> .yml matching | +| 1 | Schema: fields, types, format, coordinate pattern | +| 2 | Contract: rule.md ↔ rule.yml check ID matching | +| 3 | Cross-reference: coordinate-map, tombstones, supersession | diff --git a/.claude/skills/validate-rules/validation.md b/.claude/skills/validate-rules/validation.md index 00d9582..dd646b8 100644 --- a/.claude/skills/validate-rules/validation.md +++ b/.claude/skills/validate-rules/validation.md @@ -12,25 +12,28 @@ Rule validation checks schema and contract compliance. ## Schema Validation Required fields: -- `id` matches pattern (core: `^[SCEGM][0-9]+$`, agent: `^[A-Z]+_[SCEGM][0-9]+$`) +- `id` matches coordinate pattern (`CORE:S:0001`, `CLAUDE:S:0001`, etc.) +- `slug` matches directory name - `title` <= 64 characters - `category` is valid -- `type` is deterministic or semantic +- `type` is mechanical, deterministic, or semantic +- `level` is L1-L6 - `checks[]` array exists and non-empty -- `checks[].id` starts with `{rule.id}-` +- `checks[].id` follows `NAMESPACE.CATEGORY.SLOT.check.NNNN` format Type-specific: -- Semantic: must have `question` + `criteria` -- Deterministic: must NOT have `question`/`criteria` +- Semantic: must have `question` + `criteria` (required — drives LLM evaluation) +- Mechanical/Deterministic: `question` + `criteria` optional (documentation only) ## Contract Validation Every rule .md file must have a matching .yml file: -- [ ] .yml file exists (same name, different extension) -- [ ] Every `checks[].id` in .md has matching `rules[].id` in .yml +- [ ] .yml file exists (named `rule.yml` in same directory) +- [ ] Every `checks[].id` in .md has matching `rules[].id` in .yml (deterministic/semantic) - [ ] Every `rules[].id` in .yml has matching `checks[].id` in .md - [ ] Severity mapping is consistent between .md and .yml +- [ ] Mechanical rules have `rules: []` in .yml ## Auto-fixable vs Manual Issues @@ -38,12 +41,12 @@ Every rule .md file must have a matching .yml file: |-------|--------------|--------| | Title > 64 chars | Yes | Truncate with "..." | | Missing .yml severity | Yes | Add based on mapping | -| Wrong check ID prefix | Yes | Rename to match rule ID | -| Type mismatch | No | Change deterministic <-> semantic | +| Wrong check ID prefix | Yes | Rename to match coordinate | +| Type mismatch | No | Change mechanical/deterministic/semantic | ## Output Format ``` -Rules: 18 | Schema errors: 0 | Contract errors: 0 -S1: ok S2: ok C1: ok ... -``` +Rules: 47 | Schema errors: 0 | Contract errors: 0 +CORE:S:0001: ok CORE:S:0002: ok CORE:C:0001: ok ... +``` \ No newline at end of file diff --git a/.claude/tasks/create-release.md b/.claude/tasks/create-release.md index 2a9dfd3..5a37e55 100644 --- a/.claude/tasks/create-release.md +++ b/.claude/tasks/create-release.md @@ -16,7 +16,7 @@ Prepare and tag a new release. - Use [Keep a Changelog](https://keepachangelog.com/) format - Sections: Added, Changed, Fixed, Removed - Lead with headline feature - - Include key metrics (trust score, rule count, etc.) + - Include key metrics (rule count, schema version, etc.) - [ ] Clear `UNRELEASED.md` (keep `# Unreleased` header only) - [ ] Update version in relevant files (if any) - [ ] Review diff before committing @@ -44,9 +44,8 @@ Prepare and tag a new release. - **{Theme}**: {Summary of what was fixed} ### Metrics -- Trust Score: {X}% -- Evidence Coverage: {Y}% core, {Z}% experimental - Rules: {N} total ({P} passing) +- Schema version: {X} ``` ## Result diff --git a/.claude/tasks/new-rule.md b/.claude/tasks/new-rule.md index 2c5ac56..d08d7b7 100644 --- a/.claude/tasks/new-rule.md +++ b/.claude/tasks/new-rule.md @@ -1,6 +1,6 @@ # New Rule: {ID} -Create a new rule with full evidence chain. +Create a new rule with backing claims. Workflow: `.shared/workflows/rule-creation.md` Knowledge: `.shared/knowledge/rule-authoring.md` @@ -21,13 +21,9 @@ Knowledge: `.shared/knowledge/rule-authoring.md` - [ ] `/generate-rule {ID} {scope} "{title}"` - [ ] Verify OpenGrep validates (exit 0 or 1) -### Parallel (run simultaneously) -- [ ] Update `docs/sources.yml` — add rule to claim.rules[] -- [ ] Update `CHANGELOG.md` - -### Sequential (after parallel) +### Sequential (after generation) - [ ] `/validate-rules` — new rule passes -- [ ] `/validate-rules --source-check` — no broken links +- [ ] Update `UNRELEASED.md` ## Result diff --git a/.claude/tasks/qa-rules.md b/.claude/tasks/qa-rules.md index 71a0ad0..f3318d0 100644 --- a/.claude/tasks/qa-rules.md +++ b/.claude/tasks/qa-rules.md @@ -18,7 +18,6 @@ Checklist: `.shared/knowledge/qa-checklist.md` ### Sequential (after parallel) - [ ] `/validate-rules` — confirm all pass -- [ ] `/validate-rules --source-check` — verify trust score ## Error Triage @@ -41,8 +40,6 @@ Checklist: `.shared/knowledge/qa-checklist.md` - Contract errors: ___ - OpenGrep errors: ___ -**Trust Score:** ___ - ## Run History | Run | Date | Result | Notes | diff --git a/.claude/tasks/release-prep.md b/.claude/tasks/release-prep.md index 52a8519..0762a11 100644 --- a/.claude/tasks/release-prep.md +++ b/.claude/tasks/release-prep.md @@ -8,7 +8,6 @@ Workflow: `.shared/workflows/rule-validation.md` ### Sequential - [ ] `/validate-rules` — all rules pass -- [ ] `/validate-rules --source-check` — evidence chain intact ### Sequential (after validation) - [ ] Update `CHANGELOG.md` with version @@ -20,7 +19,6 @@ Workflow: `.shared/workflows/rule-validation.md` **Status:** ☐ PASS ☐ FAIL **Run #:** ___ -**Trust Score:** ___ **Rules Passing:** ___/___ **Version:** ___ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..372a771 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,23 @@ +name: CI + +on: + push: + branches: + # Release branches: run QA on every push (e.g. 0.3.0) + - "[0-9]*.[0-9]*.[0-9]*" + +jobs: + qa: + name: QA gate + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build test image + run: docker build -t reporails-test runtime/ + + - name: Run test harness + run: | + docker run --rm \ + -v ${{ github.workspace }}:/rules:ro \ + reporails-test diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1cf3a02..f215058 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,52 +2,89 @@ name: Release on: push: - tags: - - '[0-9]*' - -permissions: - contents: write + branches: [main] jobs: - release: + check-release: + name: Check if release commit runs-on: ubuntu-latest + outputs: + is_release: ${{ steps.check.outputs.is_release }} + version: ${{ steps.check.outputs.version }} steps: - uses: actions/checkout@v4 - - name: Get version from tag - id: version - run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT + - name: Detect version branch merge + id: check + run: | + VERSION=$(grep '^\*\*Version:\*\*' README.md | head -1 | sed 's/.*\*\* *//') + MERGE_BRANCH=$(git log -1 --pretty=%s | grep -oP 'Merge.*from.*\K[0-9]+\.[0-9]+\.[0-9]+' || true) + if [ "$MERGE_BRANCH" = "$VERSION" ]; then + echo "is_release=true" >> "$GITHUB_OUTPUT" + echo "version=$VERSION" >> "$GITHUB_OUTPUT" + echo "Release detected: $VERSION" + else + echo "is_release=false" >> "$GITHUB_OUTPUT" + echo "Not a release merge (merge_branch=$MERGE_BRANCH, version=$VERSION)" + fi + + qa: + name: QA gate + needs: check-release + if: needs.check-release.outputs.is_release == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build test image + run: docker build -t reporails-test runtime/ + + - name: Run test harness + run: | + docker run --rm \ + -v ${{ github.workspace }}:/rules:ro \ + reporails-test - name: Validate schemas have versions - run: | - for schema in schemas/*.schema.yml; do - if ! grep -q '^version:' "$schema"; then - echo "ERROR: $schema missing version field" - exit 1 - fi - done + run: | + for schema in schemas/*.schema.yml; do + if ! grep -q '^version:' "$schema"; then + echo "ERROR: $schema missing version field" + exit 1 + fi + done + + publish: + name: Publish release + needs: [check-release, qa] + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 - name: Generate manifest - run: | - VERSION=${{ steps.version.outputs.VERSION }} - - echo "release: \"${VERSION}\"" > manifest.yml - echo "schemas:" >> manifest.yml - - for schema in schemas/*.schema.yml; do - name=$(basename "$schema" .schema.yml) - version=$(grep '^version:' "$schema" | head -1 | awk '{print $2}' | tr -d '"') - echo " ${name}: \"${version}\"" >> manifest.yml - done + run: | + VERSION="${{ needs.check-release.outputs.version }}" + + echo "release: \"${VERSION}\"" > manifest.yml + echo "schemas:" >> manifest.yml + + for schema in schemas/*.schema.yml; do + name=$(basename "$schema" .schema.yml) + version=$(grep '^version:' "$schema" | head -1 | awk '{print $2}' | tr -d '"') + echo " ${name}: \"${version}\"" >> manifest.yml + done - name: Create tarball - run: | - VERSION=${{ steps.version.outputs.VERSION }} - - # Create tarball with framework contents + run: | + VERSION="${{ needs.check-release.outputs.version }}" + tar -czvf reporails-rules-${VERSION}.tar.gz \ manifest.yml \ - levels.yml \ + registry/levels.yml \ + registry/capabilities.yml \ + registry/coordinate-map.yml \ core/ \ agents/ \ schemas/ \ @@ -57,10 +94,15 @@ jobs: sha256sum reporails-rules-${VERSION}.tar.gz > checksums.txt - - name: Create Release - uses: softprops/action-gh-release@v1 - with: - generate_release_notes: true - files: | - reporails-rules-*.tar.gz - checksums.txt \ No newline at end of file + - name: Create tag and GitHub release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + VERSION="${{ needs.check-release.outputs.version }}" + git tag "$VERSION" + git push origin "$VERSION" + gh release create "$VERSION" \ + --title "v$VERSION" \ + --generate-notes \ + reporails-rules-${VERSION}.tar.gz \ + checksums.txt diff --git a/.gitignore b/.gitignore index 0e2a6a5..48e1dca 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,2 @@ .idea -tmp -.reporails/trust-metrics.yml -.reporails/audit-report.md \ No newline at end of file +tmp \ No newline at end of file diff --git a/.reporails/backbone.yml b/.reporails/backbone.yml index 6009e64..1782585 100644 --- a/.reporails/backbone.yml +++ b/.reporails/backbone.yml @@ -1,4 +1,4 @@ -version: 2 +version: 3 generator: manual agents: @@ -14,56 +14,40 @@ rules: core: core/ agents: agents/ patterns: - rule_dir: "{category}/{id}-{slug}/" - definition: "{id}-{slug}.md" - opengrep: "{id}-{slug}.yml" - test_pass: "tests/pass.{ext}" - test_fail: "tests/fail.{ext}" - # {ext} matches the rule's target file type: md (default), yml, json + rule_dir: "{category}/{slug}/" + definition: "rule.md" + opengrep: "rule.yml" + test_pass: "tests/pass/" + test_fail: "tests/fail/" categories: structure: core/structure/ content: core/content/ efficiency: core/efficiency/ maintenance: core/maintenance/ + governance: core/governance/ agent_rules: claude: agents/claude/rules/ codex: agents/codex/rules/ - index: - # Core rules: ID → slug (resolve via: {category}/{id}-{slug}/) - S1: size-limits - S2: progressive-disclosure - S3: no-embedded-code-snippets - S4: clear-markdown-structure - C1: core-sections - C2: single-source-of-truth - C3: has-project-description - C4: links-are-valid - C5: has-version-date - E1: code-block-line-limit - E2: import-count - M1: version-control - M2: no-conflicting-rules - M3: map-staleness-prevention - M4: backbone-index-completeness - # Agent rules: ID → slug (resolve via: agents/{agent}/rules/{id}-{slug}/) - CLAUDE_M1: auto-generated-content-review - CLAUDE_S1: hierarchical-memory - CLAUDE_S2: path-scoped-rules - schemas: rule: schemas/rule.schema.yml + capability: schemas/capability.schema.yml + levels: schemas/levels.schema.yml agent: schemas/agent.schema.yml package: schemas/package.schema.yml project: schemas/project.schema.yml + sources: schemas/sources.schema.yml user: schemas/user.schema.yml - levels: schemas/levels.schema.yml -artifacts: - levels: levels.yml +registry: + capabilities: registry/capabilities.yml + levels: registry/levels.yml + coordinate_map: registry/coordinate-map.yml + tombstones: registry/tombstones.yml + +docs: sources: docs/sources.yml - capability_levels: docs/capability-levels.md - changelog: UNRELEASED.md + rule_template: docs/rule-template.md shared: knowledge: .shared/knowledge/ diff --git a/.reporails/config.yml b/.reporails/config.yml new file mode 100644 index 0000000..c9daa76 --- /dev/null +++ b/.reporails/config.yml @@ -0,0 +1,10 @@ +# Project-level configuration for rules/ repo +exclude_dirs: + - tests + +disabled_rules: + - "CLAUDE:S:0005" # Child Files Scoped — single-repo, only 1 CLAUDE.md + - "CLAUDE:S:0010" # Settings File Missing — rules/ is a framework repo, not a Claude Code project + - "CORE:S:0006" # Total Instruction Budget — framework repo with many skills (38KB > 32KB limit) + - "CORE:S:0010" # Cross-Agent Compatibility — excluded in agent config + - "CORE:S:0011" # MCP Servers Documented — no MCP server in this repo diff --git a/.shared/knowledge/backbone-resolution.md b/.shared/knowledge/backbone-resolution.md index caddca7..6458361 100644 --- a/.shared/knowledge/backbone-resolution.md +++ b/.shared/knowledge/backbone-resolution.md @@ -10,52 +10,47 @@ Read `.reporails/backbone.yml` before resolving any paths. All paths are relativ | Need | Backbone Key | Example Value | |------|-------------|---------------| -| Rule base dir (core) | `rules.core` | `core/` | -| Rule base dir (agent) | `rules.agent_rules.{agent}` | `agents/claude/rules/` | -| Rule category dir | `rules.categories.{category}` | `core/structure/` | -| Rule dir pattern | `rules.patterns.rule_dir` | `{category}/{id}-{slug}/` | -| Rule definition | `rules.patterns.definition` | `{id}-{slug}.md` | -| Rule OpenGrep | `rules.patterns.opengrep` | `{id}-{slug}.yml` | -| Test pass | `rules.patterns.test_pass` | `tests/pass.{ext}` | -| Test fail | `rules.patterns.test_fail` | `tests/fail.{ext}` | +| Core rules base | `rules.core` | `core/` | +| Agent rules base | `rules.agent_rules.{agent}` | `agents/claude/rules/` | +| Category dir | `rules.categories.{category}` | `core/structure/` | +| Rule dir pattern | `rules.patterns.rule_dir` | `{category}/{slug}/` | +| Rule definition | `rules.patterns.definition` | `rule.md` | +| Rule OpenGrep | `rules.patterns.opengrep` | `rule.yml` | +| Test pass dir | `rules.patterns.test_pass` | `tests/pass/` | +| Test fail dir | `rules.patterns.test_fail` | `tests/fail/` | | Schema files | `schemas.{name}` | `schemas/rule.schema.yml` | -| Sources file | `artifacts.sources` | `docs/sources.yml` | -| Levels file | `artifacts.levels` | `levels.yml` | -| Capability levels | `artifacts.capability_levels` | `docs/capability-levels.md` | -| Changelog | `artifacts.changelog` | `UNRELEASED.md` | +| Registry files | `registry.{name}` | `registry/coordinate-map.yml` | +| Source registry | `docs.sources` | `docs/sources.yml` | | Agent config | `agents.{agent}.config` | `agents/claude/config.yml` | | Agent skills | `agents.{agent}.skills` | `.claude/skills/` | | Shared knowledge | `shared.knowledge` | `.shared/knowledge/` | | Shared workflows | `shared.workflows` | `.shared/workflows/` | -## Test File Extension +## Coordinate-to-Path Algorithm -The `{ext}` variable in test patterns is determined by the rule's target file type: +To resolve a coordinate (e.g., `CORE:S:0001`) to its filesystem path: -| Rule's `languages` / target | `{ext}` | -|-----------------------------|---------| -| markdown / `{{instruction_files}}` | `md` (default) | -| yaml / `.reporails/backbone.yml` | `yml` | -| json / settings files | `json` | +1. Look up slug in `registry/coordinate-map.yml` (e.g., `instruction-file-exists: "CORE:S:0001"`) +2. Determine category from the coordinate map's YAML structure (the slug lives under `core.structure`, so category = `structure`) +3. For agent coordinates (`CLAUDE:*`, `CODEX:*`), use `rules.agent_rules.{agent}` as base +4. Combine: `{category_dir}/{slug}/rule.md` (and `rule.yml`) -The test file must be parseable by the OpenGrep language mode the rule uses. +**Example:** `CORE:S:0001` +- Coordinate map: `core.structure.instruction-file-exists: "CORE:S:0001"` +- Category dir: `rules.categories.structure` → `core/structure/` +- Path: `core/structure/instruction-file-exists/rule.md` -## ID-to-Path Algorithm - -To resolve a rule ID (e.g., `S1`) to its filesystem path: - -1. Look up slug in `rules.index` (e.g., `S1: size-limits`) -2. Determine category from ID prefix: `S`=structure, `C`=content, `E`=efficiency, `G`=governance, `M`=maintenance -3. For agent-prefixed IDs (e.g., `CLAUDE_S1`), use `rules.agent_rules.{agent}` as base -4. Combine: `{base}/{id}-{slug}/{id}-{slug}.md` (and `.yml`) - -**Example:** `S1` resolves to `core/structure/S1-size-limits/S1-size-limits.md` +**Agent example:** `CLAUDE:S:0001` +- Coordinate map: `agents.claude.claude-md-file-placement: "CLAUDE:S:0001"` +- Agent rules base: `rules.agent_rules.claude` → `agents/claude/rules/` +- Path: `agents/claude/rules/claude-md-file-placement/rule.md` ## When to Update backbone.yml -Update the backbone index when: -- **New rule created** — add entry to `rules.index` +Update the backbone when: - **New schema added** — add entry to `schemas` +- **New registry file added** — add entry to `registry` - **New agent configured** — add entry to `agents` -- **New artifact added** — add entry to `artifacts` -- **Rule renamed/deleted** — update or remove from `rules.index` +- **New doc artifact added** — add entry to `docs` + +Rule directories are NOT tracked in the backbone — they're tracked in `registry/coordinate-map.yml`. diff --git a/.shared/knowledge/changelog.md b/.shared/knowledge/changelog.md index 2dc83ae..a1cc577 100644 --- a/.shared/knowledge/changelog.md +++ b/.shared/knowledge/changelog.md @@ -49,15 +49,15 @@ Add to `UNRELEASED.md` as you work: **Good:** ```markdown - [STRUCTURE]: Introduced `.shared/` for agent-agnostic workflows and knowledge -- [REPORTING]: Trust Score with Evidence Coverage breakdown (81% official, 19% methodology) +- [REPORTING]: Schema validation with rule count breakdown ``` **Bad:** ```markdown - Added file .shared/workflows/rule-creation.md - Added file .shared/workflows/rule-validation.md -- Added file .shared/workflows/evidence-audit.md -- Changed evidence-chain.md +- Added file .shared/workflows/rule-update.md +- Changed qa-checklist.md ``` ## Creating a Release @@ -68,7 +68,7 @@ Use task: `.claude/tasks/create-release.md` 1. Review `UNRELEASED.md` 2. Group similar changes by theme 3. Write release summary for `CHANGELOG.md` -4. Include key metrics (trust score, rule count, etc.) +4. Include key metrics (rule count, schema version, etc.) 5. Clear `UNRELEASED.md` (keep header) 6. Commit, tag, push @@ -89,21 +89,23 @@ One-line summary of the release. - **Theme**: Summary ### Metrics -- Trust Score: X% -- Evidence Coverage: Y% official, Z% methodology - Rules: N total (P passing) +- Schema version: X ``` -## Tagging +## Releasing -```bash -git tag X.Y.Z -git push origin X.Y.Z -``` +Release is automated via GitHub Actions: + +1. Create a release branch named `X.Y.Z` (e.g., `0.3.0`) +2. Update version in `README.md` and finalize `UNRELEASED.md` +3. Merge to `main` — the release workflow detects the version-branch merge +4. CI runs the Docker test harness as a QA gate +5. On pass: tag is created, tarball is built, GitHub release is published -Tag format: [SemVer](https://semver.org/) (e.g., `0.2.0`) +Tag format: [SemVer](https://semver.org/) (e.g., `0.3.0`) -GitHub Actions (`.github/workflows/release.yml`) triggers on `[0-9]*` tags. +See `.github/workflows/release.yml` for the full pipeline. ## Version Numbering diff --git a/.shared/knowledge/qa-checklist.md b/.shared/knowledge/qa-checklist.md index 3089f67..cadc56a 100644 --- a/.shared/knowledge/qa-checklist.md +++ b/.shared/knowledge/qa-checklist.md @@ -10,18 +10,18 @@ After running rule creation workflow: | Check | Verification | Expected | |-------|--------------|----------| -| Directory exists | `ls -d core/*/SMOKE1-*` | Directory present | -| Files exist | `ls core/*/SMOKE1-*/*.{md,yml}` | Both .md and .yml present | -| Tests exist | `ls core/*/SMOKE1-*/tests/` | fail.md and pass.md present | -| Frontmatter valid | `head -30 core/*/SMOKE1-*/*.md` | id, title, category, type, checks, backed_by, pattern_confidence | -| Check ID format | Inspect .md | `checks[].id` starts with rule ID + hyphen | -| YML matches | Inspect .yml | `rules[].id` matches `checks[].id` from .md | -| OpenGrep validates | `opengrep scan --config core/*/SMOKE1-*/*.yml .` | Exit 0 or 1 | +| Directory exists | `ls core/{category}/{slug}/` | Directory present | +| Files exist | `ls core/{category}/{slug}/rule.{md,yml}` | Both rule.md and rule.yml present | +| Tests exist | `ls core/{category}/{slug}/tests/` | pass/ and fail/ directories present | +| Frontmatter valid | `head -30 core/{category}/{slug}/rule.md` | id, slug, title, category, type, level, checks, backed_by | +| Check ID format | Inspect rule.md | `checks[].id` follows `NAMESPACE.CATEGORY.SLOT.check.NNNN` | +| YML matches | Inspect rule.yml | `rules[].id` matches `checks[].id` from rule.md | +| OpenGrep validates | `opengrep scan --config core/{category}/{slug}/rule.yml .` | Exit 0 or 1 | **Fail indicators:** -- Missing .yml file +- Missing rule.yml file - Frontmatter missing required fields -- Check ID doesn't match pattern `{RULE_ID}-{suffix}` +- Check ID doesn't match coordinate pattern (e.g., `CORE.S.0001.check.0001`) - OpenGrep exit 2 (syntax error) or 7 (no positive pattern) --- @@ -45,43 +45,22 @@ After running validation workflow: --- -## audit-evidence-chain - -After running evidence audit workflow: - -| Check | Verification | Expected | -|-------|--------------|----------| -| Loads sources | Workflow reads | `docs/sources.yml` accessed | -| Bidirectional check | Output | Reports E4003/E4004 if mismatched | -| Confidence check | Output | Reports E4005-E4009 if misaligned | -| Trust score | Output | Numeric score calculated | -| Metrics file | `cat .reporails/trust-metrics.yml` | File exists with score | - -**Fail indicators:** -- Can't find sources.yml -- Score calculation errors -- Metrics file not created - ---- - ## update-rule After running rule update workflow: | Check | Verification | Expected | |-------|--------------|----------| -| Locates rule | Workflow finds | Correct .md and .yml | -| ID preserved | `grep "id:" core/*/SMOKE1-*/*.md` | ID unchanged | -| Directory preserved | `ls -d core/*/SMOKE1-*` | Same directory | -| Pattern updated | `cat core/*/SMOKE1-*/*.yml` | New pattern present | -| pattern_confidence reassessed | Inspect .md | pattern_confidence updated if patterns changed | -| OpenGrep validates | `opengrep scan --config core/*/SMOKE1-*/*.yml .` | Exit 0 or 1 | +| Locates rule | Workflow finds | Correct rule.md and rule.yml | +| ID preserved | `grep "id:" core/{category}/{slug}/rule.md` | Coordinate unchanged | +| Directory preserved | `ls -d core/{category}/{slug}/` | Same directory | +| Pattern updated | `cat core/{category}/{slug}/rule.yml` | New pattern present | +| OpenGrep validates | `opengrep scan --config core/{category}/{slug}/rule.yml .` | Exit 0 or 1 | **Fail indicators:** - Rule not found -- ID or filename changed +- Coordinate or slug changed - Pattern not added -- pattern_confidence not reassessed after pattern change - OpenGrep fails after update --- @@ -94,9 +73,9 @@ After running rule update workflow: | Hallucinated patterns | Knowledge not loaded | Verify .shared/knowledge/ links | | Exit code 2 | Invalid YAML | Check syntax, required fields | | Exit code 7 | No positive pattern | Add pattern-regex before pattern-not-regex | -| Wrong tier | backed_by doesn't match expected tier | Check sources.yml weights | -| Missing .yml | Workflow step skipped | Check contract step in workflow | -| ID changed on update | Constraint violated | Check rule-update workflow constraints | +| Wrong tier | backed_by doesn't match expected tier | Check docs/sources.yml weights | +| Missing rule.yml | Workflow step skipped | Check contract step in workflow | +| Coordinate changed on update | Constraint violated | Check rule-update workflow constraints | --- @@ -107,4 +86,4 @@ When adding a new skill: 1. Add section with skill name as heading 2. List checks as table: Check | Verification | Expected 3. List fail indicators -4. Update qa-smoke-test.md if skill should be in smoke test \ No newline at end of file +4. Update qa-smoke-test.md if skill should be in smoke test diff --git a/.shared/knowledge/rule-authoring.md b/.shared/knowledge/rule-authoring.md index 126844c..2264f2a 100644 --- a/.shared/knowledge/rule-authoring.md +++ b/.shared/knowledge/rule-authoring.md @@ -6,40 +6,40 @@ Templates and validation for creating rule skeletons. ```yaml --- -id: {ID} +id: "NAMESPACE:CATEGORY:SLOT" +slug: slug-name title: {Title} # max 64 chars -category: structure|content|efficiency|maintenance -type: deterministic|semantic +category: structure|content|efficiency|governance|maintenance +type: mechanical|deterministic|semantic +level: L1|L2|L3|L4|L5|L6 +targets: "{{instruction_files}}" checks: - - id: {ID}-{check-slug} + - id: NAMESPACE.CATEGORY.SLOT.check.NNNN name: {Description} severity: critical|high|medium|low -backed_by: [] # empty by default +backed_by: [] # source IDs from docs/sources.yml --- # {Title} One-sentence impact statement. -## Pattern +## Pass / Fail -**Good:** -``` -example -``` +**Pass:** example +**Fail:** example -**Bad:** -``` -example -``` +## Limitations + +{limitations} ``` -### Semantic Rule Additions +### Question and Criteria -For semantic rules, add to frontmatter: +All rules can include `question` and `criteria` as documentation of what the rule verifies. For semantic rules these fields are **required** (they drive LLM evaluation). For mechanical and deterministic rules they are **optional** (human-readable description only). ```yaml -question: "{What LLM evaluates}" +question: "{What the rule verifies}" criteria: - {First criterion} - {Second criterion} @@ -49,29 +49,32 @@ criteria: ```yaml rules: - - id: {ID}-{check-slug} - message: "TODO: {description}" + - id: NAMESPACE.CATEGORY.SLOT.check.NNNN + message: "{description}" severity: WARNING languages: [generic] - pattern-regex: "TODO" # placeholder + pattern-regex: "pattern" paths: include: - "{{instruction_files}}" ``` -## ID Patterns +Mechanical rules have `rules: []` — no OpenGrep patterns needed. + +## Coordinate Patterns | Scope | Pattern | Example | |-------|---------|---------| -| Core | `^[SCEGM][0-9]+$` | S1, C5, E2 | -| Agent | `^[A-Z]+_[SCEGM][0-9]+$` | CLAUDE_S1 | +| Core | `CORE:{S\|C\|E\|G\|M}:NNNN` | `CORE:S:0001` | +| Claude agent | `CLAUDE:S:NNNN` | `CLAUDE:S:0001` | +| Codex agent | `CODEX:S:NNNN` | `CODEX:S:0001` | ## Valid Values | Field | Values | |-------|--------| -| category | structure, content, efficiency, maintenance | -| type | deterministic, semantic | +| category | structure, content, efficiency, governance, maintenance | +| type | mechanical, deterministic, semantic | | severity (md) | critical, high, medium, low | | severity (yml) | ERROR, WARNING, INFO | @@ -90,9 +93,8 @@ 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}-{suffix}` | -| Semantic without question | Add question + criteria | -| Deterministic with question | Remove question + criteria | +| Wrong check ID format | Must be `NAMESPACE.CATEGORY.SLOT.check.NNNN` | +| Semantic without question | Add question + criteria (required for semantic) | | Hardcoded paths in .yml | Use `{{instruction_files}}` | | Title > 64 characters | Shorten or abbreviate | | Body > 40 lines | Extract to supporting docs | @@ -101,24 +103,26 @@ rules: ### Frontmatter -- [ ] `id` matches pattern (core/agent) +- [ ] `id` matches coordinate pattern +- [ ] `slug` matches directory name - [ ] `title` <= 64 characters - [ ] `category` is valid -- [ ] `type` is valid (deterministic/semantic) +- [ ] `type` is valid (mechanical/deterministic/semantic) +- [ ] `level` is valid (L1-L6) - [ ] `checks` array exists and non-empty -- [ ] `checks[].id` starts with rule ID + hyphen +- [ ] `checks[].id` follows `NAMESPACE.CATEGORY.SLOT.check.NNNN` format - [ ] `checks[].severity` is valid -- [ ] If semantic: `question` and `criteria` exist -- [ ] If deterministic: NO `question` or `criteria` +- [ ] If semantic: `question` and `criteria` exist (required) +- [ ] If mechanical/deterministic: `question` and `criteria` optional (documentation only) ### Contract - [ ] .yml file exists for every .md rule -- [ ] Every `checks[].id` in .md has matching `rules[].id` in .yml -- [ ] Every `rules[].id` in .yml has matching `checks[].id` in .md +- [ ] Every `checks[].id` in .md has matching `rules[].id` in .yml (deterministic/semantic only) +- [ ] Mechanical rules have `rules: []` in .yml ### Content - [ ] Body <= 40 lines - [ ] Has "# {Title}" heading matching frontmatter -- [ ] Has Pattern section with Good/Bad examples +- [ ] Has Pass/Fail section with examples diff --git a/.shared/knowledge/validation.md b/.shared/knowledge/validation.md index 00d9582..ec3222a 100644 --- a/.shared/knowledge/validation.md +++ b/.shared/knowledge/validation.md @@ -12,12 +12,14 @@ Rule validation checks schema and contract compliance. ## Schema Validation Required fields: -- `id` matches pattern (core: `^[SCEGM][0-9]+$`, agent: `^[A-Z]+_[SCEGM][0-9]+$`) +- `id` matches coordinate pattern (`CORE:S:0001`, `CLAUDE:S:0001`, etc.) +- `slug` matches directory name - `title` <= 64 characters - `category` is valid -- `type` is deterministic or semantic +- `type` is mechanical, deterministic, or semantic +- `level` is L1-L6 - `checks[]` array exists and non-empty -- `checks[].id` starts with `{rule.id}-` +- `checks[].id` follows `NAMESPACE.CATEGORY.SLOT.check.NNNN` format Type-specific: - Semantic: must have `question` + `criteria` @@ -27,10 +29,11 @@ Type-specific: Every rule .md file must have a matching .yml file: -- [ ] .yml file exists (same name, different extension) -- [ ] Every `checks[].id` in .md has matching `rules[].id` in .yml +- [ ] .yml file exists (named `rule.yml` in same directory) +- [ ] Every `checks[].id` in .md has matching `rules[].id` in .yml (deterministic/semantic) - [ ] Every `rules[].id` in .yml has matching `checks[].id` in .md - [ ] Severity mapping is consistent between .md and .yml +- [ ] Mechanical rules have `rules: []` in .yml ## Auto-fixable vs Manual Issues @@ -38,12 +41,12 @@ Every rule .md file must have a matching .yml file: |-------|--------------|--------| | Title > 64 chars | Yes | Truncate with "..." | | Missing .yml severity | Yes | Add based on mapping | -| Wrong check ID prefix | Yes | Rename to match rule ID | -| Type mismatch | No | Change deterministic <-> semantic | +| Wrong check ID prefix | Yes | Rename to match coordinate | +| Type mismatch | No | Change mechanical/deterministic/semantic | ## Output Format ``` -Rules: 18 | Schema errors: 0 | Contract errors: 0 -S1: ok S2: ok C1: ok ... +Rules: 47 | Schema errors: 0 | Contract errors: 0 +CORE:S:0001: ok CORE:S:0002: ok CORE:C:0001: ok ... ``` diff --git a/.shared/workflows/level-sync.md b/.shared/workflows/level-sync.md index c5c8243..4b06bb2 100644 --- a/.shared/workflows/level-sync.md +++ b/.shared/workflows/level-sync.md @@ -3,19 +3,19 @@ ```mermaid flowchart TD START([/manage-levels command]) --> PARSE[Parse Capability Assessment Matrix<br/>from docs/capability-levels.md] - PARSE --> EXTRACT[Extract rule-to-level assignments<br/>First + per row = introduction level] + PARSE --> EXTRACT[Extract capability-to-level assignments] EXTRACT --> MODE{command?} MODE -->|sync| READ_META[Read level names + descriptions<br/>from Level Descriptions section] READ_META --> GENERATE[Generate levels.yml content] - GENERATE --> WRITE[Write levels.yml] + GENERATE --> WRITE[Write registry/levels.yml] WRITE --> CHANGELOG[Add UNRELEASED.md entry] - CHANGELOG --> REPORT_SYNC[Report: rules per level, changes made] - MODE -->|diff| READ_CURRENT[Read current levels.yml] + CHANGELOG --> REPORT_SYNC[Report: capabilities per level, changes made] + MODE -->|diff| READ_CURRENT[Read current registry/levels.yml] READ_CURRENT --> COMPARE[Compare parsed vs current] - COMPARE --> REPORT_DIFF[Report discrepancies<br/>Added/removed/moved rules per level] + COMPARE --> REPORT_DIFF[Report discrepancies<br/>Added/removed/moved capabilities per level] MODE -->|list| FILTER{level specified?} - FILTER -->|yes| SHOW_ONE[Display rules for that level] - FILTER -->|no| SHOW_ALL[Display rules for all levels] + FILTER -->|yes| SHOW_ONE[Display capabilities for that level] + FILTER -->|no| SHOW_ALL[Display capabilities for all levels] ``` ## Parsing Contract @@ -23,50 +23,57 @@ flowchart TD The matrix in `docs/capability-levels.md` under "Capability Assessment Matrix": ```markdown -| Criteria | Rule | L1 | L2 | L3 | L4 | L5 | L6 | -|----------|------|----|----|----|----|----|----| -| Manually reviewed | CLAUDE_M1 | + | + | + | + | + | + | -| Size limits | S1 | - | + | + | + | + | + | +| Capability | Level | What It Detects | +|------------|-------|-----------------| +| instruction_file | L1 | Non-trivial, tracked instruction file exists | +| project_constraints | L2 | Project-specific substance | +| size_controlled | L2 | Instruction file is concise | ``` -- **Column 2** = Rule ID -- **Columns 3-8** = L1 through L6 (`+` = required, `-` = not expected) -- **Introduction level** = first column where `+` appears +- **Column 1** = Capability identifier (snake_case) +- **Column 2** = Level where capability is assigned (L1–L6) +- **Column 3** = Detection description ## Assignment Logic -Each rule is assigned to exactly one level: the **first** level where `+` appears. +Each capability is assigned to exactly one level. -Example: `S1` has `- | + | + | + | + | +` — first `+` is L2, so S1 belongs to L2. +Example: `project_constraints` is in the L2 row, so it belongs to L2. -`levels.yml` lists only introduction-level rules per level (not cumulative). +`registry/levels.yml` groups capabilities by level. ## Output Format (levels.yml) ```yaml -# Canonical level definitions for the Reporails framework. -# Source of truth: docs/capability-levels.md (Capability Assessment Matrix) -# -# CLI consumers should prefer this file over any bundled copy. +# Level definitions +version: 1 levels: L0: name: Absent - description: No instruction file - rules: [] + description: "No instruction file exists" + capabilities: [] L1: name: Basic - description: <from Level Descriptions> - rules: [RULE_A, RULE_B] + description: "A non-trivial, tracked instruction file exists" + capabilities: + - instruction_file + + L2: + name: Scoped + description: "Project-specific constraints defined, file is focused" + capabilities: + - project_constraints + - size_controlled ``` -- L0 is always present with empty rules -- Level names and descriptions come from the "Level Descriptions" section headings and content -- Rules are listed in matrix row order (top to bottom) +- L0 is always present with empty capabilities +- Level names and descriptions come from the "Level Descriptions" section +- Capabilities are listed in matrix row order ## Constraints -- **Source of truth**: `docs/capability-levels.md` — never edit `levels.yml` directly +- **Source of truth**: `docs/capability-levels.md` — never edit `registry/levels.yml` directly - **Idempotent**: Running `sync` twice produces identical output -- **No reordering**: Rules listed in the order they appear in the matrix +- **No reordering**: Capabilities listed in the order they appear in the matrix diff --git a/.shared/workflows/qa-smoke-test.md b/.shared/workflows/qa-smoke-test.md index 4e2efdc..71e9d97 100644 --- a/.shared/workflows/qa-smoke-test.md +++ b/.shared/workflows/qa-smoke-test.md @@ -4,22 +4,19 @@ Meta-workflow that validates all skill workflows after structural changes. ```mermaid flowchart TD - START([QA Smoke Test]) --> GEN[1. Rule Creation<br/>SMOKE1 core 'Smoke Test'] + START([QA Smoke Test]) --> GEN[1. Rule Creation<br/>generate test rule] GEN --> CHECK1{Checklist passed?} CHECK1 -->|No| FAIL1([FAIL: generate-rule]) CHECK1 -->|Yes| VAL[2. Rule Validation<br/>all rules] VAL --> CHECK2{Checklist passed?} CHECK2 -->|No| FAIL2([FAIL: validate-rules]) - CHECK2 -->|Yes| AUDIT[3. Evidence Audit<br/>all rules + sources] - AUDIT --> CHECK3{Checklist passed?} - CHECK3 -->|No| FAIL3([FAIL: audit-evidence-chain]) - CHECK3 -->|Yes| UPD[4. Rule Update<br/>SMOKE1 add pattern] - UPD --> CHECK4{Checklist passed?} - CHECK4 -->|No| FAIL4([FAIL: update-rule]) - CHECK4 -->|Yes| REVAL[5. Re-validate<br/>confirm SMOKE1 still valid] - REVAL --> CHECK5{Still passes?} - CHECK5 -->|No| FAIL5([FAIL: regression]) - CHECK5 -->|Yes| CLEANUP[6. Cleanup<br/>rm -rf core/*/SMOKE1-*] + CHECK2 -->|Yes| UPD[3. Rule Update<br/>add pattern to test rule] + UPD --> CHECK3{Checklist passed?} + CHECK3 -->|No| FAIL3([FAIL: update-rule]) + CHECK3 -->|Yes| REVAL[4. Re-validate<br/>confirm test rule still valid] + REVAL --> CHECK4{Still passes?} + CHECK4 -->|No| FAIL4([FAIL: regression]) + CHECK4 -->|Yes| CLEANUP[5. Cleanup<br/>remove test rule directory] CLEANUP --> PASS([PASS]) ``` @@ -27,12 +24,11 @@ flowchart TD | Step | Workflow | Input | Verify With | |------|----------|-------|-------------| -| 1 | rule-creation | `SMOKE1 core "Smoke Test"` | qa-checklist.md#generate-rule | +| 1 | rule-creation | `/generate-rule CORE:S:9999 structure "Smoke Test"` | qa-checklist.md#generate-rule | | 2 | rule-validation | all rules | qa-checklist.md#validate-rules | -| 3 | evidence-audit | all rules + sources | qa-checklist.md#audit-evidence-chain | -| 4 | rule-update | `SMOKE1 "Add test pattern"` | qa-checklist.md#update-rule | -| 5 | rule-validation | all rules | SMOKE1 still passes | -| 6 | cleanup | `rm -rf core/*/SMOKE1-*` | directory deleted | +| 3 | rule-update | `/update-rule CORE:S:9999 "Add test pattern"` | qa-checklist.md#update-rule | +| 4 | rule-validation | all rules | Test rule still passes | +| 5 | cleanup | `rm -rf core/structure/smoke-test/` | directory deleted | ## When to Run @@ -48,12 +44,12 @@ flowchart TD - Check `.shared/knowledge/` files exist - Check skill imports resolve -**Step 4 fails (update):** +**Step 3 fails (update):** - Check rule-update workflow handles existing files -- Verify SMOKE1 was created correctly in step 1 +- Verify test rule was created correctly in step 1 -**Step 5 fails (regression):** -- Update broke something — compare .yml before/after +**Step 4 fails (regression):** +- Update broke something — compare rule.yml before/after - Check OpenGrep validation output ## Cleanup on Failure @@ -61,7 +57,7 @@ flowchart TD If any step fails, still run cleanup: ```bash -rm -rf core/*/SMOKE1-* +rm -rf core/structure/smoke-test/ ``` -Don't leave test artifacts in the repo. \ No newline at end of file +Don't leave test artifacts in the repo. diff --git a/.shared/workflows/rule-creation.md b/.shared/workflows/rule-creation.md index bb0e2d0..3e6253c 100644 --- a/.shared/workflows/rule-creation.md +++ b/.shared/workflows/rule-creation.md @@ -2,39 +2,33 @@ ```mermaid flowchart TD - START([/generate-rule id scope title]) --> GATHER[Gather: what, why, type, patterns, sources] + START([/generate-rule coordinate scope title]) --> GATHER[Gather: what, why, type, patterns] GATHER --> TYPE{OpenGrep fully decides?} TYPE -->|Yes| DET[type: deterministic] - TYPE -->|No| SEM[type: semantic<br/>Add question + criteria] - DET --> SOURCES[Find backing claims in sources.yml] + TYPE -->|No - needs judgment| SEM[type: semantic<br/>Add question + criteria] + TYPE -->|No - structural only| MECH[type: mechanical] + DET --> SOURCES[Find backing sources in docs/sources.yml] SEM --> SOURCES - SOURCES --> CONF{Confidence decision tree} - CONF -->|max weight >= 0.8| CORE[tier: core] - CONF -->|max weight < 0.8 or none| EXPERIMENTAL[tier: experimental] - CONFIRMED --> GEN[Generate .md + .yml from templates] - HIGH --> GEN - MEDIUM --> GEN - LOW --> GEN + MECH --> SOURCES + SOURCES --> GEN[Generate rule.md + rule.yml + tests/pass/ + tests/fail/] GEN --> RESOLVE[Resolve templates for validation] RESOLVE --> VALID{OpenGrep exit code?} - VALID -->|0 or 1| ASSESS[Assess pattern_confidence per check] - ASSESS --> SAVE[Save files with templates intact] + VALID -->|0 or 1| SAVE[Save files with templates intact] VALID -->|2| FIX2[Fix syntax error] --> RESOLVE VALID -->|7| FIX7[Add positive pattern] --> RESOLVE - SAVE --> BIDIR[Update claim.rules bidirectionally] - BIDIR --> REFS[Update see_also, capability-levels if needed] + SAVE --> REFS[Update coordinate-map, capability-levels if needed] REFS --> CHANGELOG[/add-changelog-entry] ``` ## Edge Cases -**No existing claim backs the rule:** -- Run `/extract-claims <url>` first to create claim -- Then reference in rule's `backed_by` +**No existing source backs the rule:** +- Add a new source entry to `docs/sources.yml` with the URL, type, and weight +- Then reference its ID in the rule's `backed_by` list **Core vs Agent rules:** - Core rules use only `{{instruction_files}}` - Agent rules can use `{{rules_dir}}`, `{{skills_dir}}`, etc. -**Path resolution:** Resolve rule paths from `.reporails/backbone.yml` using `rules.index`, `rules.categories`, and `rules.patterns`. -See [@.shared/knowledge/backbone-resolution.md](../knowledge/backbone-resolution.md) for the ID-to-path algorithm and directory structure. +**Path resolution:** Resolve rule paths from `.reporails/backbone.yml` using `rules.categories`, `rules.agent_rules`, and `rules.patterns`. +See [@.shared/knowledge/backbone-resolution.md](../knowledge/backbone-resolution.md) for the coordinate-to-path algorithm and directory structure. diff --git a/.shared/workflows/rule-implementation.md b/.shared/workflows/rule-implementation.md new file mode 100644 index 0000000..2483dce --- /dev/null +++ b/.shared/workflows/rule-implementation.md @@ -0,0 +1,76 @@ +# Rule Implementation Workflow + +```mermaid +flowchart TD + START([/implement-rule coordinate]) --> LOCATE[Resolve directory from coordinate-map + backbone] + LOCATE --> READ[Parse rule.md frontmatter + body] + READ --> GUARD{checks non-empty?} + GUARD -->|Yes| ABORT[Already implemented — abort] + GUARD -->|No| VIOLATION[Identify violation class from title + criteria + Pass/Fail] + VIOLATION --> ANALYZE{Rule type?} + ANALYZE -->|mechanical| MECH[Select check functions + args] + ANALYZE -->|deterministic| DET[Design structural violation pattern] + ANALYZE -->|semantic| SEM[Design candidate-surfacing pre-check + semantic prompt] + MECH --> CHECKS[Write checks array in rule.md] + DET --> CHECKS + SEM --> CHECKS + DET --> PATTERNS[Write OpenGrep rules in rule.yml] + SEM --> PATTERNS + CHECKS --> FIXTURES[Generate realistic pass/ and fail/ fixtures] + PATTERNS --> FIXTURES + FIXTURES --> QUALITY{Fixture quality check} + QUALITY -->|realistic + single violation| VERIFY[Run test harness] + QUALITY -->|synthetic or multi-fault| REGEN[Regenerate fixtures] --> QUALITY + VERIFY -->|pass| DONE([Report success]) + VERIFY -->|fail| REANALYZE[Re-examine violation class] --> DET +``` + +## Key Decision: Violation Class Identification + +Before designing any pattern, answer these questions: + +1. **What structural or content pattern makes an instruction file FAIL this rule?** + - The Pass/Fail examples in rule.md are illustrations, not specifications + - Think about the CLASS of violation, not the specific example + +2. **Is this a presence-of-bad-content or absence-of-good-content violation?** + - Presence: pattern matches the violation directly + - Absence: pattern matches the structural gap left by the missing content + - NEVER use negate-based presence checks as the primary strategy + +3. **For semantic rules: what text NEEDS human judgment?** + - Pre-checks surface content that EXHIBITS the violation pattern + - Not content that MATCHES the rule's topic + +## Edge Cases + +**Rule already has checks:** +Abort with message — do not overwrite existing implementation. + +**Semantic rules with existing `question`/`criteria`:** +Use those fields directly for the terminal semantic check `prompt`. Invert `criteria` items to derive pre-check violation indicators. Do not invent new evaluation criteria. + +**Agent-specific rules (CLAUDE:\*, CODEX:\*):** +Use agent-specific template vars in paths (e.g., `{{rules_dir}}`, `{{skills_dir}}`). Resolve from `agents/{agent}/config.yml`. + +**Cross-file rules:** +Set `cross_file: true` on the deterministic check. Fixture must contain multiple files in `tests/pass/` and `tests/fail/` to exercise cross-file behavior. + +**Mechanical-only rules:** +Leave `rule.yml` as `rules: []` — no OpenGrep patterns needed. Fixtures must exercise the mechanical check function (e.g., file presence/absence for `file_exists`). + +**Deterministic rules with mechanical pre-checks:** +Allowed — `deterministic` type ceiling permits both `mechanical` and `deterministic` checks. Order them so mechanical runs first if it narrows the target set. + +**Absence-type violations with no structural signature:** +When the violation is purely "keyword X is missing" and no structural gap pattern exists, `negate: true` is acceptable as a last resort. Document why in the check's `message` field. Use OpenGrep's `patterns` (combined `pattern-regex` + `pattern-not-regex`) over frontmatter `negate` where possible — it keeps the logic in the pattern engine rather than the test runner. + +## Fixture Quality Criteria + +| Criterion | Pass fixture | Fail fixture | +|-----------|-------------|-------------| +| Length | 30-80 lines (realistic) | 30-80 lines (realistic) | +| Content | Looks like a real CLAUDE.md | Looks like a plausible mistake | +| Violations | Zero for this rule | Exactly one specific violation | +| Structure | Has sections, commands, context | Same structure, one thing wrong | +| Realism | Could be from a real project | Someone would actually write this | diff --git a/.shared/workflows/rule-update.md b/.shared/workflows/rule-update.md index fe85c9c..4b11c25 100644 --- a/.shared/workflows/rule-update.md +++ b/.shared/workflows/rule-update.md @@ -2,7 +2,7 @@ ```mermaid flowchart TD - START([/update-rule id instruction]) --> LOCATE[Locate rule .md + .yml] + START([/update-rule coordinate instruction]) --> LOCATE[Locate rule.md + rule.yml] LOCATE --> READ[Read current state<br/>frontmatter, patterns] READ --> APPLY[Apply instruction to patterns] APPLY --> RESOLVE[Resolve templates for validation] @@ -11,8 +11,8 @@ flowchart TD VALID -->|2| FIX2[Fix syntax error] --> RESOLVE VALID -->|7| FIX7[Add positive pattern] --> RESOLVE CONFLICT --> SAVE[Save with templates intact] - SAVE --> SYNC{.md needs update?} - SYNC -->|yes| UPDATEMD[Update .md if checks changed] + SAVE --> SYNC{rule.md needs update?} + SYNC -->|yes| UPDATEMD[Update rule.md if checks changed] SYNC -->|no| REPORT UPDATEMD --> REPORT[Report changes] ``` @@ -20,18 +20,15 @@ flowchart TD ## Constraints **NEVER change:** -- Rule ID (e.g., S4 stays S4) -- Filenames (e.g., S4-yaml-backbone.yml stays S4-yaml-backbone.yml) +- Rule coordinate (e.g., `CORE:S:0005` stays `CORE:S:0005`) +- Directory slug (e.g., `instruction-file-size-limit/` stays `instruction-file-size-limit/`) - Category or type -**Re-assess when patterns change:** -- Re-evaluate `pattern_confidence` for any check whose pattern was modified - **Save with templates:** - Write `{{instruction_files}}` not resolved values - Resolution is only for validation ## Path Resolution -Resolve rule paths from `.reporails/backbone.yml` using `rules.index`, `rules.categories`, and `rules.patterns`. -See [@.shared/knowledge/backbone-resolution.md](../knowledge/backbone-resolution.md) for the ID-to-path algorithm and directory structure. +Resolve rule paths from `.reporails/backbone.yml` using `rules.categories` and `rules.patterns`. +See [@.shared/knowledge/backbone-resolution.md](../knowledge/backbone-resolution.md) for the coordinate-to-path algorithm. diff --git a/.shared/workflows/rule-validation.md b/.shared/workflows/rule-validation.md index df700e0..c93033a 100644 --- a/.shared/workflows/rule-validation.md +++ b/.shared/workflows/rule-validation.md @@ -11,10 +11,7 @@ flowchart TD CONTRACT -->|pass| RESOLVE[Resolve template variables] RESOLVE --> OPENGREP[3. OpenGrep validation<br/>Pattern syntax] OPENGREP -->|exit 2 or 7| REPORT - OPENGREP -->|exit 0 or 1| SOURCE{--source-check?} - SOURCE -->|yes| EVIDENCE[4. Evidence chain validation<br/>backed_by integrity] - SOURCE -->|no| REPORT - EVIDENCE --> REPORT[Report results] + OPENGREP -->|exit 0 or 1| REPORT[Report results] REPORT --> NEXT{More rules?} NEXT -->|yes| LOOP NEXT -->|no| SUMMARY[Summary output] diff --git a/CHANGELOG.md b/CHANGELOG.md index 5edb182..70cff84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,63 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.3.0] - 2026-02-10 + +### Added +- [SKILLS]: `/implement-rule` skill — implement checks, patterns, and fixtures for rule skeletons +- [RUNTIME]: Contributor test harness — Docker-based runner for validating rules against fixtures +- [RUNTIME]: 15 mechanical check functions (file_exists, directory_exists, line_count, byte_size, file_count, git_tracked, frontmatter_field, aggregate_byte_size, import_depth, directory_file_types, frontmatter_valid_glob, content_absent, and more) +- [RUNTIME]: OpenGrep integration for deterministic pattern testing +- [RUNTIME]: `--package` flag for testing additional rule packages (e.g., `--package /recommended`) +- [RUNTIME]: Docker compose mounts recommended/ at `/recommended:ro` for package testing +- [CORE]: All 47 core rules fully implemented — checks, patterns, and fixtures wired (47/47 passing) +- [REGISTRY]: Capabilities, levels, coordinate map, tombstones +- [REGISTRY]: 9 tombstone entries for coordinates moved to recommended package +- [SCHEMAS]: Capability schema v0.1.0 + +### Changed +- [SKILLS]: `/implement-rule` rewritten — violation class identification, structural pattern design, anti-negate strategy, realistic fixture criteria +- [WORKFLOWS]: `rule-implementation.md` rewritten — violation class step, fixture quality gate, reanalysis loop +- [FIXTURES]: Migrated test fixtures from stub files (tests/pass.md, tests/fail.md) to directories (tests/pass/, tests/fail/) +- [BACKBONE]: Updated test_pass/test_fail patterns for directory-based fixtures +- [SCHEMAS]: Rule schema rewrite — coordinate IDs, gate checks, governance category +- [SCHEMAS]: Agent schema — prefix/name/overrides restored as optional after config audit +- [SCHEMAS]: Levels schema rewrite — cross-reference validation only +- [SCHEMAS]: Package schema — AILS→RRAILS prefix, coordinate format +- [SCHEMAS]: Project and user schemas — semver schema_version +- [BACKBONE]: v3 — slug-based patterns, registry section, removed index/artifacts +- [META]: CLAUDE.md and rules updated for coordinate format +- [SKILLS]: All 5 skills updated for coordinate and registry paths +- [SKILLS]: `/generate-rule` updated — fixture step now creates `tests/pass/` and `tests/fail/` directories with `.gitkeep` + +### Fixed +- [CORE:S:0004]: Replaced Stripe-format fake API key in test fixture with generic value to avoid GitHub Push Protection rejection +- [CORE:S:0003]: Use `.git_marker` as trackable alternative to `.git` in test fixtures — git cannot track paths named `.git`, causing CI failures +- [SCHEMAS]: Agent schema — restored `prefix`, `name` as optional fields; `overrides` as optional object; `main_instruction_file`/`instruction_files` accept string or list +- [AGENTS]: Claude and Codex configs — added required `version: "0.1.0"` field +- [AGENTS]: Codex config — removed stale v0.2 overrides (E4-, E2-, E5- identifiers) +- [CORE:S:0010]: Changed `type: deterministic` → `type: mechanical` (all checks are mechanical) +- [CORE:S:0009]: Updated prose to match check behavior (file existence, not git tracking) +- [OPENGREP]: Fixed 6 negated-rule messages from absence-language to presence-language (CORE:C:0002, C:0003, C:0004, C:0005, C:0015, CORE:S:0011) +- [BACKBONE]: Added missing `sources` schema to backbone registry +- [META]: CLAUDE.md — replaced hardcoded structure tree with backbone reference +- [META]: CLAUDE.md — added constraint: resolve paths from backbone before exploratory commands + +### Removed +- [CORE:C]: Removed 7 rules reclassified as recommended (0008, 0013, 0014, 0018, 0020, 0021, 0024) +- [CLAUDE:S]: Removed 2 rules reclassified as recommended (0006, 0007) + +### Migration +- [CORE]: Migrated 15 rules from short-ID format (`S1-size-limits/`) to coordinate-based (`size-limits/rule.md`) +- [CORE]: Removed old short-ID rule directories (superseded by coordinate-based layout) +- [CORE]: Removed root `levels.yml` (superseded by `registry/levels.yml`) +- [CORE]: M1 (version-control) reclassified from `deterministic` to `mechanical` +- [CORE]: C2 (single-source-of-truth) now `supersedes: CORE:C:0001` +- [CORE]: Level assignments — L1: M1, C3 | L2: S1, S3, S4, C1, C5, E1 | L3: S2, C2, C4, E2, M2 | L5: M3, M4 +- [CORE]: Fixed M4 frontmatter bug (had `id: M2`, now `id: CORE:M:0004`) +- [CORE]: All `backed_by` converted to source ID format (references `docs/sources.yml`) +- [CORE]: All `checks[].id` now follow `{rule_id}:check:{slot}` coordinate pattern + ## [0.2.2] - 2026-02-04 ### Changed @@ -52,7 +109,6 @@ Trust Architecture — tier-derived rule classification, schema breaking changes - **M6 Rule**: Backbone index completeness — ensures filesystem rule directories are registered in `backbone.yml` - **Codex Agent**: `agents/codex/` with config.yml for OpenAI Codex AGENTS.md files; `codex-agent-loop` source - **Backbone**: `.claude/rules/` path-scoped reminders; `.shared/knowledge/backbone-resolution.md` central resolution reference -- **Metrics**: `.reporails/trust-metrics.yml` generated by evidence audit ### Changed - **BREAKING — Rule Schema v5**: Added `pattern_confidence` to `checks[]` items; removed `confidence` field (v4); tiers now derived from `backed_by` source weights diff --git a/CLAUDE.md b/CLAUDE.md index 665e62a..7ccfe8c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,5 @@ # Reporails Framework -<!-- Last updated: 2026-01-31 --> +<!-- Last updated: 2026-02-06 --> Framework for evaluating and maintaining AI agent instruction files. @@ -10,42 +10,58 @@ Framework for evaluating and maintaining AI agent instruction files. - OpenGrep patterns for detection - No application code — framework only -## Session Start +## Initialization -1. Read `.reporails/backbone.yml` for project structure -2. Read `docs/capability-levels.md` for architecture decisions +Read these files before searching or modifying anything: + +1. Read `.reporails/backbone.yml` for project structure and path resolution +2. Read `registry/capabilities.yml` and `registry/levels.yml` for architecture +3. Read `.claude/rules/` for context-specific constraints on the current task ## Structure -``` -levels.yml # Canonical level→rule mappings -core/{structure,content,efficiency,maintenance}/ # Generic rules (18) - {rule-id}/ # Each rule in own directory - {rule-id}.md # Rule definition - {rule-id}.yml # OpenGrep patterns - tests/ # Test cases - fail.md # Should trigger - pass.md # Should not trigger -agents/{claude,codex}/{config.yml,rules/} # Agent-specific (same structure) -schemas/{rule,agent,package,project,user,levels}.schema.yml # Schemas -docs/ # Documentation -.claude/{skills/,rules/} # Claude config -.shared/{workflows/,knowledge/} # Agent-agnostic shared content -``` +Defined in `.reporails/backbone.yml` — the single source of truth for project topology, paths, schemas, and registry locations. + +**BEFORE** running `find`, `grep`, `ls`, or glob to locate project files, you **MUST** read `.reporails/backbone.yml` first. All schema paths, registry paths, rule directories, agent configs, and doc locations are mapped there. You **MUST NOT** use exploratory commands to discover paths that the backbone already provides. ## Commands -- Check rule lengths: `wc -l core/**/*/*.md agents/**/rules/*/*.md` -- List all rules: `find core agents -type d -name "[A-Z]*" | grep -v tests` -- List rule files: `find core agents -path "*/tests" -prune -o -name "*.md" -print | grep -v README` +- Check rule lengths: `wc -l core/**/*/rule.md agents/**/rules/*/rule.md` +- List all rules: `find core agents -name "rule.md" | grep -v tests` +- List rule directories: `find core agents -name "rule.yml" -exec dirname {} \;` + +### Test Harness + +```bash +# Build test image +docker compose -f runtime/docker-compose.yml build + +# Run all rules +docker compose -f runtime/docker-compose.yml run test + +# Run one rule +docker compose -f runtime/docker-compose.yml run test --rule CORE:S:0001 + +# Run one category +docker compose -f runtime/docker-compose.yml run test core/structure/ + +# Use codex agent vars +docker compose -f runtime/docker-compose.yml run test --agent codex + +# Include recommended package +docker compose -f runtime/docker-compose.yml run test --package /recommended + +# Verbose (show OpenGrep output) +docker compose -f runtime/docker-compose.yml run test --verbose +``` ## Navigation Key paths: -- @docs/capability-levels.md — Level definitions -- @core/ — Generic rules (S1-S4, C1-C5, E1-E2, M1-M4) -- @agents/ — Agent-specific config and rules (Claude, Codex) -- @schemas/ — Machine-readable contracts +- @registry/ — Capabilities, levels, coordinate map, tombstones +- @core/ — Core rules (12 structure, 18 content) +- @agents/ — Agent-specific config and rules (10 Claude, 7 Codex) +- @schemas/ — Machine-readable contracts (8 schemas) - @docs/ — Contributor guides and source registry Additional rules available in [reporails/recommended](https://github.com/reporails/recommended). @@ -63,8 +79,11 @@ Additional rules available in [reporails/recommended](https://github.com/reporai - NEVER hardcode agent paths in core rules — use `{{instruction_files}}` - NEVER read CHANGELOG.md — use UNRELEASED.md instead - ALWAYS update UNRELEASED.md when modifying rules -- ALWAYS create both .md and .yml for each rule -- ALWAYS create tests/fail.md and tests/pass.md for each rule +- ALWAYS create both rule.md and rule.yml for each rule +- ALWAYS create tests/pass/ and tests/fail/ fixture directories for each rule +- ALWAYS update registry/coordinate-map.yml when adding or removing rules +- NEVER execute destructive or irreversible operations without explicit user confirmation +- ALWAYS resolve paths from `.reporails/backbone.yml` before using exploratory commands ## Shared Resources @@ -78,3 +97,12 @@ Skills in `.claude/skills/` are entry points that reference shared content. ## Skills Skills in `.claude/skills/` — each has a SKILL.md linking to shared workflows. + +| Skill | Purpose | +|-------|---------| +| `/generate-rule` | Create rule skeleton with coordinate, directory, and placeholder files | +| `/implement-rule` | Implement checks, patterns, and fixtures for an existing rule skeleton | +| `/validate-rules` | Validate rules against schema and contracts | +| `/manage-levels` | Sync level definitions with capability model | +| `/manage-agent-config` | Create, update, and validate agent configurations | +| `/add-changelog-entry` | Add changelog entry to UNRELEASED.md | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c72af2c..57e8881 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,65 +1,118 @@ # Contributing -Reporails validates AI agent instruction files (CLAUDE.md, .cursorrules, copilot-instructions.md). Rules define what to check — this repo is where those rules live. +Rules define what Reporails checks in AI instruction files (CLAUDE.md, AGENTS.md, .cursorrules). This repo is where those rules live. -## Setup +## Prerequisites -1. Clone this repo -2. Open in Claude Code — slash commands handle the rest +- **Docker** — for running the test harness +- **A coding agent** — rules are created and validated through agent skills -## Create a rule +Currently supported: **Claude Code**. Codex and Copilot support is planned. + +## Rule anatomy + +Each rule lives in its own directory with three parts: ``` -/generate-rule S5 core "My New Rule" +core/structure/instruction-file-size-limit/ + rule.md # Definition: frontmatter (id, type, level, checks) + prose + rule.yml # OpenGrep patterns (or empty `rules: []` for mechanical) + tests/ + pass/ # Fixture that should pass the rule + fail/ # Fixture that should fail the rule ``` -The skill walks you through it: what the rule checks, whether detection is deterministic or semantic, and generates the .md, .yml, and test files. +## Coordinates + +Every rule has a coordinate like `CORE:S:0005` — three parts: + +| Part | Meaning | Values | +|------|---------|--------| +| Namespace | Who owns it | `CORE`, `CLAUDE`, `CODEX` | +| Category | What it checks | `S` (structure), `C` (content) | +| Slot | Sequence number | `0001`–`9999` | + +Check `registry/coordinate-map.yml` to see which slots are taken before picking a new one. -## Validate +## Rule types + +| Type | How it detects | Example | +|------|---------------|---------| +| **mechanical** | Python structural checks (file exists, line count, byte size) | CORE:S:0001 — instruction file exists | +| **deterministic** | OpenGrep pattern matching on file content | CORE:C:0006 — specificity over vagueness | +| **semantic** | OpenGrep pre-filter + LLM evaluation | CORE:C:0017 — repo-specific content | + +Mechanical rules have `rules: []` in their rule.yml. Deterministic and semantic rules have OpenGrep patterns. + +## Creating a rule ``` -/validate-rules +/generate-rule CORE:C:0026 core "My New Rule" ``` -Checks schema compliance, .md/.yml consistency, and OpenGrep pattern validity. Run before submitting. +The skill creates the directory, rule.md, rule.yml, and test fixtures. It walks you through choosing the type, writing patterns, and finding backing sources. -## Log changes +To implement checks and wire up an existing skeleton: ``` -/add-changelog-entry +/implement-rule CORE:C:0026 ``` -Run after any rule change. +## Testing + +Build and run the Docker test harness: + +```bash +# Build the test image (first time, or after runtime/ changes) +docker compose -f runtime/docker-compose.yml build + +# Run all rules +docker compose -f runtime/docker-compose.yml run test + +# Run one rule +docker compose -f runtime/docker-compose.yml run test --rule CORE:S:0001 + +# Run one category +docker compose -f runtime/docker-compose.yml run test core/structure/ + +# Verbose output (shows OpenGrep matches) +docker compose -f runtime/docker-compose.yml run test --verbose +``` + +All tests must pass before submitting. + +## Submitting changes + +1. Create a branch from `main` +2. Make your changes +3. Run the test harness — all rules must pass +4. Open a pull request ## Rule layout ``` core/ - structure/ # S1-S4 - content/ # C1-C5 - efficiency/ # E1-E2 - maintenance/ # M1-M4 + structure/ # 12 rules — file existence, size, format + content/ # 18 rules — what instruction files should contain agents/ - claude/rules/ # CLAUDE_M1, CLAUDE_S1, CLAUDE_S2 - codex/rules/ # (no rules yet) + claude/rules/ # 10 rules — CLAUDE.md-specific patterns + codex/rules/ # 7 rules — AGENTS.md-specific patterns ``` -Opinionated rules (governance, process, style) live in [reporails/recommended](https://github.com/reporails/recommended) with the `AILS_` prefix. - -Schemas live in `schemas/` — single source of truth, never duplicated across repos. +Opinionated rules (governance, style) live in [reporails/recommended](https://github.com/reporails/recommended) with the `RRAILS_` namespace. -## Quick reference +## Skills -| Task | Command | -|------|---------| -| New rule | `/generate-rule <id> <scope> <title>` | -| Validate all | `/validate-rules` | -| Validate one | `/validate-rules <id>` | -| Level mappings | `/manage-levels <sync\|diff\|list> [level]` | -| Agent config | `/manage-agent-config <create\|audit> <agent>` | -| Log change | `/add-changelog-entry` | +| Task | Skill | Example | +|------|-------|---------| +| Create a rule | `/generate-rule` | `/generate-rule CORE:C:0026 core "My Rule"` | +| Implement checks | `/implement-rule` | `/implement-rule CORE:C:0026` | +| Validate all rules | `/validate-rules` | `/validate-rules` | +| Validate one rule | `/validate-rules` | `/validate-rules CORE:C:0026` | +| Level mappings | `/manage-levels` | `/manage-levels diff` | +| Log a change | `/add-changelog-entry` | `/add-changelog-entry` | ## Questions? -Open an issue. +[Open an issue](https://github.com/reporails/rules/issues). diff --git a/LICENSE b/LICENSE index 2a6eac5..aa7fb19 100644 --- a/LICENSE +++ b/LICENSE @@ -1,13 +1,23 @@ -Creative Commons Attribution 4.0 International (CC BY 4.0) +Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) -https://creativecommons.org/licenses/by/4.0/ +https://creativecommons.org/licenses/by-sa/4.0/ You are free to: - Share — copy and redistribute the material in any medium or format -- Adapt — remix, transform, and build upon the material for any purpose, even commercially + for any purpose, including commercially. +- Adapt — remix, transform, and build upon the material for any purpose, + including commercially. Under the following terms: -- Attribution — You must give appropriate credit, provide a link to the license, - and indicate if changes were made. +- Attribution — You must give appropriate credit, provide a link to the + license, and indicate if changes were made. You may do so in any + reasonable manner, but not in any way that suggests the licensor + endorses you or your use. +- ShareAlike — If you remix, transform, or build upon the material, you + must distribute your contributions under the same license as the + original. +- No additional restrictions — You may not apply legal terms or + technological measures that legally restrict others from doing + anything the license permits. -Copyright 2025-2026 Reporails Contributors \ No newline at end of file +Copyright 2025-2026 Reporails Contributors diff --git a/README.md b/README.md index a608066..c7dc771 100644 --- a/README.md +++ b/README.md @@ -26,24 +26,19 @@ npx @reporails/cli check ## What's here ``` core/ - structure/ # S1-S4: File organization, size limits - content/ # C1-C5: Clarity, completeness - efficiency/ # E1-E2: Code blocks, imports - maintenance/ # M1-M4: Versioning, review + structure/ # 12 rules: File organization, size limits, modularity + content/ # 18 rules: Clarity, completeness, specificity agents/ - claude/ # Claude Code specific rules (CLAUDE_M1, CLAUDE_S1-S2) - codex/ # OpenAI Codex (no rules yet) + claude/ # 10 rules: Claude Code specific + codex/ # 7 rules: OpenAI Codex specific (CODEX:S:0001-0007) -schemas/ # Rule and config schemas - -docs/ # Detailed documentation - capability-levels.md - methodology-thresholds.md - sources.yml +schemas/ # Rule, agent, and config schemas +registry/ # Capabilities, levels, coordinate map +docs/ # Capability levels, sources ``` -18 core rules. For 26 additional recommended rules, see [reporails/recommended](https://github.com/reporails/recommended). +47 core rules. For additional recommended rules, see [reporails/recommended](https://github.com/reporails/recommended). ## Contributing @@ -56,4 +51,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) ## License -[CC BY 4.0](LICENSE) +[CC BY-SA 4.0](LICENSE) diff --git a/UNRELEASED.md b/UNRELEASED.md index 79e701b..1e3761d 100644 --- a/UNRELEASED.md +++ b/UNRELEASED.md @@ -1 +1 @@ -# Unreleased +# Unreleased \ No newline at end of file diff --git a/agents/claude/config.yml b/agents/claude/config.yml index a597154..f07b250 100644 --- a/agents/claude/config.yml +++ b/agents/claude/config.yml @@ -2,6 +2,7 @@ # Schema: schemas/agent.schema.yml agent: claude +version: "0.1.0" prefix: CLAUDE name: Claude Code @@ -17,11 +18,15 @@ vars: supplementary_files: - ".claude/rules/**/*.md" rules_dir: ".claude/rules" + settings_file: ".claude/settings.json" + memory_dir: ".claude/memory" skills_dir: ".claude/skills" local_file: "CLAUDE.local.md" managed_settings_linux: "/etc/claude-code/managed-settings.json" managed_settings_macos: "/Library/Application Support/ClaudeCode/managed-settings.json" managed_settings_windows: "C:/Program Files/ClaudeCode/managed-settings.json" -# No core rules excluded — Claude supports all features +excludes: + - CORE:S:0010 # Cross-agent compatibility — AGENTS.md is not a Claude surface + # No severity overrides — all moved to reporails/recommended diff --git a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/CLAUDE_M1-auto-generated-content-review.md b/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/CLAUDE_M1-auto-generated-content-review.md deleted file mode 100644 index 09ce8b7..0000000 --- a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/CLAUDE_M1-auto-generated-content-review.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: CLAUDE_M1 -title: Auto-Generated Content Review -category: maintenance -type: deterministic -backed_by: - - source: using-claude-md-files - claim: customized-content -checks: - - id: CLAUDE_M1-init-boilerplate - name: Unmodified /init boilerplate detected - severity: high - pattern_confidence: medium -sources: - - "https://claude.com/blog/using-claude-md-files" -see_also: [C1, C3] ---- - -# Auto-Generated Content Review - -No unmodified /init boilerplate signatures. - -## Pattern - -**Good:** Customized CLAUDE.md with project-specific content -**Bad:** Default /init output with generic placeholders diff --git a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/CLAUDE_M1-auto-generated-content-review.yml b/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/CLAUDE_M1-auto-generated-content-review.yml deleted file mode 100644 index cf25802..0000000 --- a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/CLAUDE_M1-auto-generated-content-review.yml +++ /dev/null @@ -1,10 +0,0 @@ -rules: - - id: CLAUDE_M1-init-boilerplate - message: "Unmodified /init boilerplate detected" - severity: WARNING - languages: [generic] - pattern-regex: "(?i)(auto-?generated|generated by|do not edit|placeholder|TODO:.*fill)" - paths: - include: - - "CLAUDE.md" - - "**/CLAUDE.md" diff --git a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/tests/fail.md b/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/tests/fail.md deleted file mode 100644 index 3cdb86b..0000000 --- a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/tests/fail.md +++ /dev/null @@ -1,7 +0,0 @@ -# Project Name - -Auto-generated by /init command. - -TODO: Fill in project details. - -Do not edit this section directly. diff --git a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/tests/pass.md b/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/tests/pass.md deleted file mode 100644 index 7463f0a..0000000 --- a/agents/claude/rules/CLAUDE_M1-auto-generated-content-review/tests/pass.md +++ /dev/null @@ -1,9 +0,0 @@ -# Project Name - -A web application for task management. - -## Tech Stack - -- React -- TypeScript -- Node.js diff --git a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/CLAUDE_S1-hierarchical-memory.md b/agents/claude/rules/CLAUDE_S1-hierarchical-memory/CLAUDE_S1-hierarchical-memory.md deleted file mode 100644 index 7c68512..0000000 --- a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/CLAUDE_S1-hierarchical-memory.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -id: CLAUDE_S1 -title: Hierarchical Memory -category: structure -type: deterministic -backed_by: - - source: claude-code-memory - claim: memory-hierarchy - - source: claude-code-memory - claim: rules-directory - - source: agents-md-spec - claim: nested-monorepo - - source: claude-code-settings - claim: rules-dir-config - - source: rules-directory-mechanics - claim: rules-mechanics -checks: - - id: CLAUDE_S1-rules-dir-missing - name: .claude/rules/ directory does not exist - severity: high - pattern_confidence: medium -sources: - - "https://code.claude.com/docs/en/memory" - - "https://code.claude.com/docs/en/settings" -see_also: [CLAUDE_S2, S2] ---- - -# Hierarchical Memory - -L4+ projects require `.claude/rules/` directory for modular rules. - -## Pattern - -**Good:** `.claude/rules/` with path-scoped rule files -**Bad:** All rules in root CLAUDE.md diff --git a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/CLAUDE_S1-hierarchical-memory.yml b/agents/claude/rules/CLAUDE_S1-hierarchical-memory/CLAUDE_S1-hierarchical-memory.yml deleted file mode 100644 index 9ace8c8..0000000 --- a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/CLAUDE_S1-hierarchical-memory.yml +++ /dev/null @@ -1,15 +0,0 @@ -rules: - # NOTE: OpenGrep cannot detect missing directories. This pattern gates on - # the main instruction file: if it mentions .claude/rules/ but no rule files - # exist, the rule should be flagged by runtime validation. - # This pattern checks for instruction files that lack any .claude/rules reference. - - id: CLAUDE_S1-rules-dir-missing - message: "Instruction file does not reference .claude/rules/" - severity: WARNING - languages: [generic] - patterns: - - pattern-regex: "(?si)\\A(?=[\\s\\S]*(?:command|constraint|rule|style|convention))[\\s\\S]+" - - pattern-not-regex: "\\.claude/rules" - paths: - include: - - "{{main_instruction_file}}" diff --git a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/tests/fail.md b/agents/claude/rules/CLAUDE_S1-hierarchical-memory/tests/fail.md deleted file mode 100644 index 96cd69d..0000000 --- a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/tests/fail.md +++ /dev/null @@ -1,10 +0,0 @@ -# Project Instructions - -## Commands - -- npm install -- npm test - -## Constraints - -NEVER commit directly to main. diff --git a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/tests/pass.md b/agents/claude/rules/CLAUDE_S1-hierarchical-memory/tests/pass.md deleted file mode 100644 index fab6c04..0000000 --- a/agents/claude/rules/CLAUDE_S1-hierarchical-memory/tests/pass.md +++ /dev/null @@ -1,12 +0,0 @@ -# Project Instructions - -## Commands - -- npm install -- npm test - -## Constraints - -NEVER commit directly to main. - -Rules are organized in .claude/rules/ for path-scoped loading. diff --git a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/CLAUDE_S2-path-scoped-rules.md b/agents/claude/rules/CLAUDE_S2-path-scoped-rules/CLAUDE_S2-path-scoped-rules.md deleted file mode 100644 index d6e8cb6..0000000 --- a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/CLAUDE_S2-path-scoped-rules.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -id: CLAUDE_S2 -title: Path-Scoped Rules -category: structure -type: deterministic -backed_by: - - source: claude-code-memory - claim: path-scoped-rules - - source: claude-code-memory - claim: rules-directory - - source: claude-code-settings - claim: rules-dir-config - - source: agents-md-spec - claim: nearest-precedence - - source: rules-directory-mechanics - claim: rules-mechanics - - source: rules-directory-mechanics - claim: loading-behavior -checks: - - id: CLAUDE_S2-no-paths-frontmatter - name: Rule file missing paths key in frontmatter - severity: medium - pattern_confidence: high -sources: - - "https://code.claude.com/docs/en/settings" - - "https://claudefa.st/blog/guide/mechanics/rules-directory" -see_also: [CLAUDE_S1, S2] ---- - -# Path-Scoped Rules - -Rule files use YAML frontmatter with `paths:` for scoped loading. - -## Pattern - -**Good:** Frontmatter with `paths: ["src/api/**"]` -**Bad:** Rule file with no path scoping diff --git a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/CLAUDE_S2-path-scoped-rules.yml b/agents/claude/rules/CLAUDE_S2-path-scoped-rules/CLAUDE_S2-path-scoped-rules.yml deleted file mode 100644 index 150213e..0000000 --- a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/CLAUDE_S2-path-scoped-rules.yml +++ /dev/null @@ -1,11 +0,0 @@ -rules: - - id: CLAUDE_S2-no-paths-frontmatter - message: "Rule file missing paths key in frontmatter" - severity: WARNING - languages: [generic] - patterns: - - pattern-regex: "(?s)\\A---[\\s\\S]*?---" - - pattern-not-regex: "paths:" - paths: - include: - - "{{rules_dir}}/*.md" diff --git a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/tests/fail.md b/agents/claude/rules/CLAUDE_S2-path-scoped-rules/tests/fail.md deleted file mode 100644 index 3c85bd9..0000000 --- a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/tests/fail.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: General rules without path scoping ---- - -# General Rules - -All rules in one file without path scoping. diff --git a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/tests/pass.md b/agents/claude/rules/CLAUDE_S2-path-scoped-rules/tests/pass.md deleted file mode 100644 index 458cd23..0000000 --- a/agents/claude/rules/CLAUDE_S2-path-scoped-rules/tests/pass.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: API rules -paths: - - "src/api/**" ---- - -# API Rules - -Path-scoped rules for src/api/. - -These rules only apply to API code. diff --git a/agents/claude/rules/child-files-scoped/rule.md b/agents/claude/rules/child-files-scoped/rule.md new file mode 100644 index 0000000..6271056 --- /dev/null +++ b/agents/claude/rules/child-files-scoped/rule.md @@ -0,0 +1,53 @@ +--- +id: "CLAUDE:S:0005" +slug: child-files-scoped +title: Child CLAUDE.md Files Are Properly Scoped +category: structure +type: semantic +level: L3 +backed_by: +- claude-code-memory +- monorepo-claude-md-organization +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0005:check:0001" + type: mechanical + check: file_count + args: + pattern: "**/CLAUDE.md" + min: 2 + severity: medium +- id: "CLAUDE:S:0005:check:0002" + type: semantic + prompt: "Do child CLAUDE.md files contain only directory-specific content without duplicating parent CLAUDE.md content?" + severity: medium +question: "Do child CLAUDE.md files contain only directory-specific content without + duplicating parent file content?" +criteria: +- Child CLAUDE.md files exist in subdirectories (project has hierarchical + instruction structure) +- Each child file addresses concerns specific to its directory scope +- No substantial content overlap between child and parent CLAUDE.md files +- Project-wide conventions, tech stack, and descriptions appear only in the root + file +--- + +# Child CLAUDE.md Files Are Properly Scoped + +Child CLAUDE.md files must contain only directory-specific content and must not duplicate content from parent CLAUDE.md files. + +## Pass / Fail + +**Pass:** Root CLAUDE.md defines the project description, tech stack, and global coding conventions. +services/api/CLAUDE.md contains only API-specific testing instructions, endpoint conventions, +and middleware configuration details not covered by the root file. +**Fail:** Root CLAUDE.md describes the project as a TypeScript monorepo with ESLint and Prettier. +services/api/CLAUDE.md repeats the same project description, tech stack, and linting rules +already present in the root file, adding only a single line about API routes. + +## Limitations + +Detecting content duplication between parent and child files requires semantic comparison. +Mechanical checks can verify file existence and basic structure but cannot assess whether +content is genuinely scoped or redundantly repeated. Minor paraphrasing of parent content +may not be detected as duplication. diff --git a/agents/claude/rules/child-files-scoped/rule.yml b/agents/claude/rules/child-files-scoped/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/child-files-scoped/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/child-files-scoped/tests/fail/CLAUDE.md b/agents/claude/rules/child-files-scoped/tests/fail/CLAUDE.md new file mode 100644 index 0000000..dcd12d6 --- /dev/null +++ b/agents/claude/rules/child-files-scoped/tests/fail/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Single instruction file with no child files. + +## Commands + +- `npm test` — run tests diff --git a/agents/claude/rules/child-files-scoped/tests/pass/CLAUDE.md b/agents/claude/rules/child-files-scoped/tests/pass/CLAUDE.md new file mode 100644 index 0000000..c024a00 --- /dev/null +++ b/agents/claude/rules/child-files-scoped/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Monorepo with properly scoped child files. + +## Commands + +- `npm test` — run tests diff --git a/agents/claude/rules/child-files-scoped/tests/pass/services/api/CLAUDE.md b/agents/claude/rules/child-files-scoped/tests/pass/services/api/CLAUDE.md new file mode 100644 index 0000000..5e1dbdd --- /dev/null +++ b/agents/claude/rules/child-files-scoped/tests/pass/services/api/CLAUDE.md @@ -0,0 +1,7 @@ +# API Service + +Express REST API with JWT authentication. + +## Testing + +Run `npm test -- --filter=api` for API-specific tests. diff --git a/agents/claude/rules/claude-md-file-placement/rule.md b/agents/claude/rules/claude-md-file-placement/rule.md new file mode 100644 index 0000000..f2c855c --- /dev/null +++ b/agents/claude/rules/claude-md-file-placement/rule.md @@ -0,0 +1,43 @@ +--- +id: "CLAUDE:S:0001" +slug: claude-md-file-placement +title: CLAUDE.md File Placement +category: structure +type: mechanical +level: L1 +backed_by: +- claude-code-memory +- claude-code-settings +- claude-md-guide +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0001:check:0001" + type: mechanical + check: file_exists + args: + path: "CLAUDE.md" + severity: critical +question: "Does a case-sensitive CLAUDE.md file exist at a recognized project-level + location?" +criteria: +- A file named exactly CLAUDE.md exists at ./CLAUDE.md or ./.claude/CLAUDE.md +- The filename uses uppercase CLAUDE and lowercase .md extension +- At least one of the two recognized locations contains the file +--- + +# CLAUDE.md File Placement + +A CLAUDE.md file must exist at the project root or in the .claude/ subdirectory with exact case-sensitive naming. + +## Pass / Fail + +**Pass:** A repository contains ./CLAUDE.md (uppercase CLAUDE, lowercase .md) at the project root. +Alternatively, the file exists at ./.claude/CLAUDE.md. Either location satisfies the rule. +**Fail:** A repository has no CLAUDE.md at either ./CLAUDE.md or ./.claude/CLAUDE.md. Variants such +as claude.md, Claude.md, CLAUDE.MD, or README-claude.md do not satisfy the requirement. + +## Limitations + +This check verifies file existence and exact filename casing only. It does not validate the +content of the CLAUDE.md file, nor does it check whether the file contains meaningful +instructions. An empty CLAUDE.md passes this rule. diff --git a/agents/claude/rules/claude-md-file-placement/rule.yml b/agents/claude/rules/claude-md-file-placement/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/claude-md-file-placement/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/claude-md-file-placement/tests/fail/README.md b/agents/claude/rules/claude-md-file-placement/tests/fail/README.md new file mode 100644 index 0000000..7c2f654 --- /dev/null +++ b/agents/claude/rules/claude-md-file-placement/tests/fail/README.md @@ -0,0 +1,3 @@ +# MyApp + +This project has no CLAUDE.md file. diff --git a/agents/claude/rules/claude-md-file-placement/tests/pass/CLAUDE.md b/agents/claude/rules/claude-md-file-placement/tests/pass/CLAUDE.md new file mode 100644 index 0000000..846dfda --- /dev/null +++ b/agents/claude/rules/claude-md-file-placement/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Web application built with React. + +## Commands + +- `npm test` — run tests diff --git a/agents/claude/rules/import-depth-within-limit/rule.md b/agents/claude/rules/import-depth-within-limit/rule.md new file mode 100644 index 0000000..2ca0a49 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/rule.md @@ -0,0 +1,47 @@ +--- +id: "CLAUDE:S:0002" +slug: import-depth-within-limit +title: Import Depth Within Limit +category: structure +type: mechanical +level: L3 +backed_by: +- claude-code-memory +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0002:check:0001" + type: mechanical + check: import_depth + args: + max: 5 + severity: medium +question: "Do all @import chains from CLAUDE.md files stay within the 5-hop recursion + limit?" +criteria: +- Every @import reference outside of code blocks is followed recursively +- The maximum chain depth from any root CLAUDE.md to any leaf import does not + exceed 5 +- Relative paths are resolved from the importing file's directory, not the + project root +- "@import references inside markdown code spans and code blocks are excluded from + traversal" +--- + +# Import Depth Within Limit + +@import chains in CLAUDE.md files must not exceed 5 levels of recursion. + +## Pass / Fail + +**Pass:** CLAUDE.md imports @.claude/rules/style.md, which imports @.claude/rules/shared/naming.md. +The chain depth is 2 hops, well within the 5-hop limit. +**Fail:** CLAUDE.md -> @imports/a.md -> @imports/b.md -> @imports/c.md -> @imports/d.md -> @imports/e.md +-> @imports/f.md. The chain is 6 hops deep. The content of imports/f.md is silently dropped +by Claude Code. + +## Limitations + +This check follows @import references statically and counts maximum depth. It does not +evaluate whether imports inside code blocks are correctly ignored at runtime. Circular +import detection is a separate concern not covered by this rule. The check cannot verify +runtime behavior if Claude Code changes its import resolution algorithm. diff --git a/agents/claude/rules/import-depth-within-limit/rule.yml b/agents/claude/rules/import-depth-within-limit/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/CLAUDE.md b/agents/claude/rules/import-depth-within-limit/tests/fail/CLAUDE.md new file mode 100644 index 0000000..51c5510 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/CLAUDE.md @@ -0,0 +1,10 @@ +# MyApp + +Platform built with Django. + +See @docs/architecture.md for architecture details. + +## Commands + +- `python manage.py test` — run tests +- `python manage.py runserver` — start dev server diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/architecture.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/architecture.md new file mode 100644 index 0000000..e402f54 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/architecture.md @@ -0,0 +1,3 @@ +# Architecture + +See @layers/layer1.md for layer details. diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/layer2.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/layer2.md new file mode 100644 index 0000000..91e5193 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/layer2.md @@ -0,0 +1,3 @@ +# Layer 2 + +See @sub/layer3.md for sub details. diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/deeper/bottom/layer6.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/deeper/bottom/layer6.md new file mode 100644 index 0000000..f367f52 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/deeper/bottom/layer6.md @@ -0,0 +1,3 @@ +# Layer 6 + +This is the bottom of the import chain. Depth = 7, exceeding the limit of 5. diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/deeper/layer5.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/deeper/layer5.md new file mode 100644 index 0000000..7816683 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/deeper/layer5.md @@ -0,0 +1,3 @@ +# Layer 5 + +See @bottom/layer6.md for the bottom. diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/layer4.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/layer4.md new file mode 100644 index 0000000..6302ca5 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/deep/layer4.md @@ -0,0 +1,3 @@ +# Layer 4 + +See @deeper/layer5.md for even deeper details. diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/layer3.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/layer3.md new file mode 100644 index 0000000..451c474 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/detail/sub/layer3.md @@ -0,0 +1,3 @@ +# Layer 3 + +See @deep/layer4.md for deep details. diff --git a/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/layer1.md b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/layer1.md new file mode 100644 index 0000000..49f5b4d --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/fail/docs/layers/layer1.md @@ -0,0 +1,3 @@ +# Layer 1 + +See @detail/layer2.md for more detail. diff --git a/agents/claude/rules/import-depth-within-limit/tests/pass/CLAUDE.md b/agents/claude/rules/import-depth-within-limit/tests/pass/CLAUDE.md new file mode 100644 index 0000000..a840004 --- /dev/null +++ b/agents/claude/rules/import-depth-within-limit/tests/pass/CLAUDE.md @@ -0,0 +1,10 @@ +# MyApp + +Platform built with Django. + +See @docs/testing.md for testing conventions. +See @docs/style.md for code style. + +## Commands + +- `python manage.py test` — run tests diff --git a/agents/claude/rules/memory-file-within-200-lines/rule.md b/agents/claude/rules/memory-file-within-200-lines/rule.md new file mode 100644 index 0000000..759c3ca --- /dev/null +++ b/agents/claude/rules/memory-file-within-200-lines/rule.md @@ -0,0 +1,45 @@ +--- +id: "CLAUDE:S:0012" +slug: memory-file-within-200-lines +title: MEMORY.md Within 200-Line Limit +category: structure +type: mechanical +level: L6 +backed_by: +- claude-code-memory +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0012:check:0001" + type: mechanical + check: line_count + args: + path: ".claude/memory/MEMORY.md" + max: 200 + severity: medium +question: "Does the MEMORY.md file stay within the 200-line auto-load limit?" +criteria: +- The total line count of MEMORY.md does not exceed 200 lines +- The check applies to all MEMORY.md files at any scope (user, project) +- Blank lines and comment lines are included in the line count +--- + +# MEMORY.md Within 200-Line Limit + +MEMORY.md files must not exceed 200 lines, as content beyond that limit is not loaded into the system prompt. + +## Pass / Fail + +**Pass:** ~/.claude/MEMORY.md contains 147 lines of key architectural decisions, common mistakes, +and project conventions. All content is within the 200-line limit and fully loaded at +session start. +**Fail:** ~/.claude/MEMORY.md contains 283 lines. The first 200 lines cover general conventions, +but lines 201-283 contain critical security constraints and deployment procedures that +are silently dropped and never seen by the agent. + +## Limitations + +This check counts physical lines including blank lines and comments. If Claude Code's +line-counting behavior differs (e.g., ignoring trailing blank lines), the check may +report false positives near the boundary. The check does not evaluate whether the most +important content is placed within the first 200 lines — only that the file does not +exceed the limit. diff --git a/agents/claude/rules/memory-file-within-200-lines/rule.yml b/agents/claude/rules/memory-file-within-200-lines/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/memory-file-within-200-lines/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/memory-file-within-200-lines/tests/fail/.claude/memory/MEMORY.md b/agents/claude/rules/memory-file-within-200-lines/tests/fail/.claude/memory/MEMORY.md new file mode 100644 index 0000000..e226115 --- /dev/null +++ b/agents/claude/rules/memory-file-within-200-lines/tests/fail/.claude/memory/MEMORY.md @@ -0,0 +1,215 @@ +# Project Memory + +## Key Decisions + +- Decision 1: Use pattern X for concern Y with detailed notes about implementation +- Decision 2: Use pattern X for concern Y with detailed notes about implementation +- Decision 3: Use pattern X for concern Y with detailed notes about implementation +- Decision 4: Use pattern X for concern Y with detailed notes about implementation +- Decision 5: Use pattern X for concern Y with detailed notes about implementation +- Decision 6: Use pattern X for concern Y with detailed notes about implementation +- Decision 7: Use pattern X for concern Y with detailed notes about implementation +- Decision 8: Use pattern X for concern Y with detailed notes about implementation +- Decision 9: Use pattern X for concern Y with detailed notes about implementation +- Decision 10: Use pattern X for concern Y with detailed notes about implementation +- Decision 11: Use pattern X for concern Y with detailed notes about implementation +- Decision 12: Use pattern X for concern Y with detailed notes about implementation +- Decision 13: Use pattern X for concern Y with detailed notes about implementation +- Decision 14: Use pattern X for concern Y with detailed notes about implementation +- Decision 15: Use pattern X for concern Y with detailed notes about implementation +- Decision 16: Use pattern X for concern Y with detailed notes about implementation +- Decision 17: Use pattern X for concern Y with detailed notes about implementation +- Decision 18: Use pattern X for concern Y with detailed notes about implementation +- Decision 19: Use pattern X for concern Y with detailed notes about implementation +- Decision 20: Use pattern X for concern Y with detailed notes about implementation +- Decision 21: Use pattern X for concern Y with detailed notes about implementation +- Decision 22: Use pattern X for concern Y with detailed notes about implementation +- Decision 23: Use pattern X for concern Y with detailed notes about implementation +- Decision 24: Use pattern X for concern Y with detailed notes about implementation +- Decision 25: Use pattern X for concern Y with detailed notes about implementation +- Decision 26: Use pattern X for concern Y with detailed notes about implementation +- Decision 27: Use pattern X for concern Y with detailed notes about implementation +- Decision 28: Use pattern X for concern Y with detailed notes about implementation +- Decision 29: Use pattern X for concern Y with detailed notes about implementation +- Decision 30: Use pattern X for concern Y with detailed notes about implementation +- Decision 31: Use pattern X for concern Y with detailed notes about implementation +- Decision 32: Use pattern X for concern Y with detailed notes about implementation +- Decision 33: Use pattern X for concern Y with detailed notes about implementation +- Decision 34: Use pattern X for concern Y with detailed notes about implementation +- Decision 35: Use pattern X for concern Y with detailed notes about implementation +- Decision 36: Use pattern X for concern Y with detailed notes about implementation +- Decision 37: Use pattern X for concern Y with detailed notes about implementation +- Decision 38: Use pattern X for concern Y with detailed notes about implementation +- Decision 39: Use pattern X for concern Y with detailed notes about implementation +- Decision 40: Use pattern X for concern Y with detailed notes about implementation +- Decision 41: Use pattern X for concern Y with detailed notes about implementation +- Decision 42: Use pattern X for concern Y with detailed notes about implementation +- Decision 43: Use pattern X for concern Y with detailed notes about implementation +- Decision 44: Use pattern X for concern Y with detailed notes about implementation +- Decision 45: Use pattern X for concern Y with detailed notes about implementation +- Decision 46: Use pattern X for concern Y with detailed notes about implementation +- Decision 47: Use pattern X for concern Y with detailed notes about implementation +- Decision 48: Use pattern X for concern Y with detailed notes about implementation +- Decision 49: Use pattern X for concern Y with detailed notes about implementation +- Decision 50: Use pattern X for concern Y with detailed notes about implementation +- Decision 51: Use pattern X for concern Y with detailed notes about implementation +- Decision 52: Use pattern X for concern Y with detailed notes about implementation +- Decision 53: Use pattern X for concern Y with detailed notes about implementation +- Decision 54: Use pattern X for concern Y with detailed notes about implementation +- Decision 55: Use pattern X for concern Y with detailed notes about implementation +- Decision 56: Use pattern X for concern Y with detailed notes about implementation +- Decision 57: Use pattern X for concern Y with detailed notes about implementation +- Decision 58: Use pattern X for concern Y with detailed notes about implementation +- Decision 59: Use pattern X for concern Y with detailed notes about implementation +- Decision 60: Use pattern X for concern Y with detailed notes about implementation +- Decision 61: Use pattern X for concern Y with detailed notes about implementation +- Decision 62: Use pattern X for concern Y with detailed notes about implementation +- Decision 63: Use pattern X for concern Y with detailed notes about implementation +- Decision 64: Use pattern X for concern Y with detailed notes about implementation +- Decision 65: Use pattern X for concern Y with detailed notes about implementation +- Decision 66: Use pattern X for concern Y with detailed notes about implementation +- Decision 67: Use pattern X for concern Y with detailed notes about implementation +- Decision 68: Use pattern X for concern Y with detailed notes about implementation +- Decision 69: Use pattern X for concern Y with detailed notes about implementation +- Decision 70: Use pattern X for concern Y with detailed notes about implementation +- Decision 71: Use pattern X for concern Y with detailed notes about implementation +- Decision 72: Use pattern X for concern Y with detailed notes about implementation +- Decision 73: Use pattern X for concern Y with detailed notes about implementation +- Decision 74: Use pattern X for concern Y with detailed notes about implementation +- Decision 75: Use pattern X for concern Y with detailed notes about implementation +- Decision 76: Use pattern X for concern Y with detailed notes about implementation +- Decision 77: Use pattern X for concern Y with detailed notes about implementation +- Decision 78: Use pattern X for concern Y with detailed notes about implementation +- Decision 79: Use pattern X for concern Y with detailed notes about implementation +- Decision 80: Use pattern X for concern Y with detailed notes about implementation +- Decision 81: Use pattern X for concern Y with detailed notes about implementation +- Decision 82: Use pattern X for concern Y with detailed notes about implementation +- Decision 83: Use pattern X for concern Y with detailed notes about implementation +- Decision 84: Use pattern X for concern Y with detailed notes about implementation +- Decision 85: Use pattern X for concern Y with detailed notes about implementation +- Decision 86: Use pattern X for concern Y with detailed notes about implementation +- Decision 87: Use pattern X for concern Y with detailed notes about implementation +- Decision 88: Use pattern X for concern Y with detailed notes about implementation +- Decision 89: Use pattern X for concern Y with detailed notes about implementation +- Decision 90: Use pattern X for concern Y with detailed notes about implementation +- Decision 91: Use pattern X for concern Y with detailed notes about implementation +- Decision 92: Use pattern X for concern Y with detailed notes about implementation +- Decision 93: Use pattern X for concern Y with detailed notes about implementation +- Decision 94: Use pattern X for concern Y with detailed notes about implementation +- Decision 95: Use pattern X for concern Y with detailed notes about implementation +- Decision 96: Use pattern X for concern Y with detailed notes about implementation +- Decision 97: Use pattern X for concern Y with detailed notes about implementation +- Decision 98: Use pattern X for concern Y with detailed notes about implementation +- Decision 99: Use pattern X for concern Y with detailed notes about implementation +- Decision 100: Use pattern X for concern Y with detailed notes about implementation +- Decision 101: Use pattern X for concern Y with detailed notes about implementation +- Decision 102: Use pattern X for concern Y with detailed notes about implementation +- Decision 103: Use pattern X for concern Y with detailed notes about implementation +- Decision 104: Use pattern X for concern Y with detailed notes about implementation +- Decision 105: Use pattern X for concern Y with detailed notes about implementation +- Decision 106: Use pattern X for concern Y with detailed notes about implementation +- Decision 107: Use pattern X for concern Y with detailed notes about implementation +- Decision 108: Use pattern X for concern Y with detailed notes about implementation +- Decision 109: Use pattern X for concern Y with detailed notes about implementation +- Decision 110: Use pattern X for concern Y with detailed notes about implementation +- Decision 111: Use pattern X for concern Y with detailed notes about implementation +- Decision 112: Use pattern X for concern Y with detailed notes about implementation +- Decision 113: Use pattern X for concern Y with detailed notes about implementation +- Decision 114: Use pattern X for concern Y with detailed notes about implementation +- Decision 115: Use pattern X for concern Y with detailed notes about implementation +- Decision 116: Use pattern X for concern Y with detailed notes about implementation +- Decision 117: Use pattern X for concern Y with detailed notes about implementation +- Decision 118: Use pattern X for concern Y with detailed notes about implementation +- Decision 119: Use pattern X for concern Y with detailed notes about implementation +- Decision 120: Use pattern X for concern Y with detailed notes about implementation +- Decision 121: Use pattern X for concern Y with detailed notes about implementation +- Decision 122: Use pattern X for concern Y with detailed notes about implementation +- Decision 123: Use pattern X for concern Y with detailed notes about implementation +- Decision 124: Use pattern X for concern Y with detailed notes about implementation +- Decision 125: Use pattern X for concern Y with detailed notes about implementation +- Decision 126: Use pattern X for concern Y with detailed notes about implementation +- Decision 127: Use pattern X for concern Y with detailed notes about implementation +- Decision 128: Use pattern X for concern Y with detailed notes about implementation +- Decision 129: Use pattern X for concern Y with detailed notes about implementation + +## Architecture Notes + +- Note 1: Important architectural consideration that takes a full line +- Note 2: Important architectural consideration that takes a full line +- Note 3: Important architectural consideration that takes a full line +- Note 4: Important architectural consideration that takes a full line +- Note 5: Important architectural consideration that takes a full line +- Note 6: Important architectural consideration that takes a full line +- Note 7: Important architectural consideration that takes a full line +- Note 8: Important architectural consideration that takes a full line +- Note 9: Important architectural consideration that takes a full line +- Note 10: Important architectural consideration that takes a full line +- Note 11: Important architectural consideration that takes a full line +- Note 12: Important architectural consideration that takes a full line +- Note 13: Important architectural consideration that takes a full line +- Note 14: Important architectural consideration that takes a full line +- Note 15: Important architectural consideration that takes a full line +- Note 16: Important architectural consideration that takes a full line +- Note 17: Important architectural consideration that takes a full line +- Note 18: Important architectural consideration that takes a full line +- Note 19: Important architectural consideration that takes a full line +- Note 20: Important architectural consideration that takes a full line +- Note 21: Important architectural consideration that takes a full line +- Note 22: Important architectural consideration that takes a full line +- Note 23: Important architectural consideration that takes a full line +- Note 24: Important architectural consideration that takes a full line +- Note 25: Important architectural consideration that takes a full line +- Note 26: Important architectural consideration that takes a full line +- Note 27: Important architectural consideration that takes a full line +- Note 28: Important architectural consideration that takes a full line +- Note 29: Important architectural consideration that takes a full line +- Note 30: Important architectural consideration that takes a full line +- Note 31: Important architectural consideration that takes a full line +- Note 32: Important architectural consideration that takes a full line +- Note 33: Important architectural consideration that takes a full line +- Note 34: Important architectural consideration that takes a full line +- Note 35: Important architectural consideration that takes a full line +- Note 36: Important architectural consideration that takes a full line +- Note 37: Important architectural consideration that takes a full line +- Note 38: Important architectural consideration that takes a full line +- Note 39: Important architectural consideration that takes a full line +- Note 40: Important architectural consideration that takes a full line +- Note 41: Important architectural consideration that takes a full line +- Note 42: Important architectural consideration that takes a full line +- Note 43: Important architectural consideration that takes a full line +- Note 44: Important architectural consideration that takes a full line +- Note 45: Important architectural consideration that takes a full line +- Note 46: Important architectural consideration that takes a full line +- Note 47: Important architectural consideration that takes a full line +- Note 48: Important architectural consideration that takes a full line +- Note 49: Important architectural consideration that takes a full line +- Note 50: Important architectural consideration that takes a full line +- Note 51: Important architectural consideration that takes a full line +- Note 52: Important architectural consideration that takes a full line +- Note 53: Important architectural consideration that takes a full line +- Note 54: Important architectural consideration that takes a full line +- Note 55: Important architectural consideration that takes a full line +- Note 56: Important architectural consideration that takes a full line +- Note 57: Important architectural consideration that takes a full line +- Note 58: Important architectural consideration that takes a full line +- Note 59: Important architectural consideration that takes a full line +- Note 60: Important architectural consideration that takes a full line +- Note 61: Important architectural consideration that takes a full line +- Note 62: Important architectural consideration that takes a full line +- Note 63: Important architectural consideration that takes a full line +- Note 64: Important architectural consideration that takes a full line +- Note 65: Important architectural consideration that takes a full line +- Note 66: Important architectural consideration that takes a full line +- Note 67: Important architectural consideration that takes a full line +- Note 68: Important architectural consideration that takes a full line +- Note 69: Important architectural consideration that takes a full line +- Note 70: Important architectural consideration that takes a full line +- Note 71: Important architectural consideration that takes a full line +- Note 72: Important architectural consideration that takes a full line +- Note 73: Important architectural consideration that takes a full line +- Note 74: Important architectural consideration that takes a full line +- Note 75: Important architectural consideration that takes a full line +- Note 76: Important architectural consideration that takes a full line +- Note 77: Important architectural consideration that takes a full line +- Note 78: Important architectural consideration that takes a full line +- Note 79: Important architectural consideration that takes a full line diff --git a/agents/claude/rules/memory-file-within-200-lines/tests/fail/CLAUDE.md b/agents/claude/rules/memory-file-within-200-lines/tests/fail/CLAUDE.md new file mode 100644 index 0000000..2e9b6aa --- /dev/null +++ b/agents/claude/rules/memory-file-within-200-lines/tests/fail/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with oversized memory file. diff --git a/agents/claude/rules/memory-file-within-200-lines/tests/pass/.claude/memory/MEMORY.md b/agents/claude/rules/memory-file-within-200-lines/tests/pass/.claude/memory/MEMORY.md new file mode 100644 index 0000000..16a8105 --- /dev/null +++ b/agents/claude/rules/memory-file-within-200-lines/tests/pass/.claude/memory/MEMORY.md @@ -0,0 +1,105 @@ +# Project Memory + +## Key Decisions + +- Decision 1: Use pattern X for concern Y +- Decision 2: Use pattern X for concern Y +- Decision 3: Use pattern X for concern Y +- Decision 4: Use pattern X for concern Y +- Decision 5: Use pattern X for concern Y +- Decision 6: Use pattern X for concern Y +- Decision 7: Use pattern X for concern Y +- Decision 8: Use pattern X for concern Y +- Decision 9: Use pattern X for concern Y +- Decision 10: Use pattern X for concern Y +- Decision 11: Use pattern X for concern Y +- Decision 12: Use pattern X for concern Y +- Decision 13: Use pattern X for concern Y +- Decision 14: Use pattern X for concern Y +- Decision 15: Use pattern X for concern Y +- Decision 16: Use pattern X for concern Y +- Decision 17: Use pattern X for concern Y +- Decision 18: Use pattern X for concern Y +- Decision 19: Use pattern X for concern Y +- Decision 20: Use pattern X for concern Y +- Decision 21: Use pattern X for concern Y +- Decision 22: Use pattern X for concern Y +- Decision 23: Use pattern X for concern Y +- Decision 24: Use pattern X for concern Y +- Decision 25: Use pattern X for concern Y +- Decision 26: Use pattern X for concern Y +- Decision 27: Use pattern X for concern Y +- Decision 28: Use pattern X for concern Y +- Decision 29: Use pattern X for concern Y +- Decision 30: Use pattern X for concern Y +- Decision 31: Use pattern X for concern Y +- Decision 32: Use pattern X for concern Y +- Decision 33: Use pattern X for concern Y +- Decision 34: Use pattern X for concern Y +- Decision 35: Use pattern X for concern Y +- Decision 36: Use pattern X for concern Y +- Decision 37: Use pattern X for concern Y +- Decision 38: Use pattern X for concern Y +- Decision 39: Use pattern X for concern Y +- Decision 40: Use pattern X for concern Y +- Decision 41: Use pattern X for concern Y +- Decision 42: Use pattern X for concern Y +- Decision 43: Use pattern X for concern Y +- Decision 44: Use pattern X for concern Y +- Decision 45: Use pattern X for concern Y +- Decision 46: Use pattern X for concern Y +- Decision 47: Use pattern X for concern Y +- Decision 48: Use pattern X for concern Y +- Decision 49: Use pattern X for concern Y + +## Patterns + +- Pattern 1: description +- Pattern 2: description +- Pattern 3: description +- Pattern 4: description +- Pattern 5: description +- Pattern 6: description +- Pattern 7: description +- Pattern 8: description +- Pattern 9: description +- Pattern 10: description +- Pattern 11: description +- Pattern 12: description +- Pattern 13: description +- Pattern 14: description +- Pattern 15: description +- Pattern 16: description +- Pattern 17: description +- Pattern 18: description +- Pattern 19: description +- Pattern 20: description +- Pattern 21: description +- Pattern 22: description +- Pattern 23: description +- Pattern 24: description +- Pattern 25: description +- Pattern 26: description +- Pattern 27: description +- Pattern 28: description +- Pattern 29: description +- Pattern 30: description +- Pattern 31: description +- Pattern 32: description +- Pattern 33: description +- Pattern 34: description +- Pattern 35: description +- Pattern 36: description +- Pattern 37: description +- Pattern 38: description +- Pattern 39: description +- Pattern 40: description +- Pattern 41: description +- Pattern 42: description +- Pattern 43: description +- Pattern 44: description +- Pattern 45: description +- Pattern 46: description +- Pattern 47: description +- Pattern 48: description +- Pattern 49: description diff --git a/agents/claude/rules/memory-file-within-200-lines/tests/pass/CLAUDE.md b/agents/claude/rules/memory-file-within-200-lines/tests/pass/CLAUDE.md new file mode 100644 index 0000000..83e4a89 --- /dev/null +++ b/agents/claude/rules/memory-file-within-200-lines/tests/pass/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with concise memory file. diff --git a/agents/claude/rules/path-targeting-syntax/rule.md b/agents/claude/rules/path-targeting-syntax/rule.md new file mode 100644 index 0000000..dd2cced --- /dev/null +++ b/agents/claude/rules/path-targeting-syntax/rule.md @@ -0,0 +1,56 @@ +--- +id: "CLAUDE:S:0004" +slug: path-targeting-syntax +title: Path Targeting Syntax +category: structure +type: mechanical +level: L4 +backed_by: +- claude-code-memory +- rules-directory-mechanics +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0004:check:0001" + type: mechanical + check: frontmatter_valid_glob + args: + path: "{{rules_dir}}" + severity: medium +question: "Do all path-targeted rules have valid YAML frontmatter with syntactically + correct glob patterns?" +criteria: +- The file begins with a valid YAML frontmatter block delimited by --- lines +- The frontmatter contains a paths key with a list value +- Each paths entry is a syntactically valid glob pattern +- Brace expansion expressions are properly closed and contain at least two + alternatives +- No other unexpected keys appear in the frontmatter block +--- + +# Path Targeting Syntax + +Rules with path targeting must use valid YAML frontmatter with a paths key containing valid glob patterns. + +## Pass / Fail + +**Pass:** A rule file .claude/rules/api-conventions.md begins with: +--- +paths: + - src/api/**/*.ts + - src/api/**/*.{js,jsx} +--- +The frontmatter is valid YAML and both patterns use correct glob syntax with brace expansion. +**Fail:** A rule file .claude/rules/api-conventions.md begins with: +--- +paths: + - src/api/**/*.{ts, +--- +The brace expansion is unclosed, making the glob pattern syntactically invalid. Claude Code +may ignore this rule or apply it incorrectly. + +## Limitations + +This check validates syntactic correctness of glob patterns but cannot verify semantic +correctness (i.e., whether the pattern actually matches the intended files). It also cannot +detect patterns that are valid but overly broad (e.g., **/*). Brace expansion validation +covers nesting up to one level; deeply nested braces may not be fully validated. diff --git a/agents/claude/rules/path-targeting-syntax/rule.yml b/agents/claude/rules/path-targeting-syntax/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/path-targeting-syntax/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/path-targeting-syntax/tests/fail/.claude/rules/api.md b/agents/claude/rules/path-targeting-syntax/tests/fail/.claude/rules/api.md new file mode 100644 index 0000000..9fbf1fb --- /dev/null +++ b/agents/claude/rules/path-targeting-syntax/tests/fail/.claude/rules/api.md @@ -0,0 +1,6 @@ +--- +paths: + - "src/api/**/*.ts[x" +--- + +Use Express middleware pattern for all API routes. diff --git a/agents/claude/rules/path-targeting-syntax/tests/fail/CLAUDE.md b/agents/claude/rules/path-targeting-syntax/tests/fail/CLAUDE.md new file mode 100644 index 0000000..c638c80 --- /dev/null +++ b/agents/claude/rules/path-targeting-syntax/tests/fail/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with untargeted rules. diff --git a/agents/claude/rules/path-targeting-syntax/tests/pass/.claude/rules/api.md b/agents/claude/rules/path-targeting-syntax/tests/pass/.claude/rules/api.md new file mode 100644 index 0000000..4f41b7d --- /dev/null +++ b/agents/claude/rules/path-targeting-syntax/tests/pass/.claude/rules/api.md @@ -0,0 +1,6 @@ +--- +paths: + - "src/api/**/*.ts" +--- + +Use Express middleware pattern for all API routes. diff --git a/agents/claude/rules/path-targeting-syntax/tests/pass/CLAUDE.md b/agents/claude/rules/path-targeting-syntax/tests/pass/CLAUDE.md new file mode 100644 index 0000000..3a747cc --- /dev/null +++ b/agents/claude/rules/path-targeting-syntax/tests/pass/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with path-targeted rules. diff --git a/agents/claude/rules/project-rules-override-user/rule.md b/agents/claude/rules/project-rules-override-user/rule.md new file mode 100644 index 0000000..b494b8c --- /dev/null +++ b/agents/claude/rules/project-rules-override-user/rule.md @@ -0,0 +1,51 @@ +--- +id: "CLAUDE:S:0009" +slug: project-rules-override-user +title: Project Rules Do Not Depend on User Settings +category: structure +type: mechanical +level: L4 +backed_by: +- claude-code-memory +- claude-code-settings +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0009:check:0001" + type: mechanical + check: content_absent + args: + pattern: "~/\\.claude" + severity: medium +question: "Are project-level instruction files self-contained without dependencies + on user-level configuration?" +criteria: +- No project-level files reference ~/.claude/ or $HOME/.claude/ paths as + operational dependencies +- No project-level files reference user-level settings.json keys as required + configuration +- Project CLAUDE.md does not instruct collaborators to modify their user-level + settings +- All necessary configuration is defined at project or local scope +--- + +# Project Rules Do Not Depend on User Settings + +Project-level instruction files must not depend on user-level settings or instructions that may not be present for all collaborators. + +## Pass / Fail + +**Pass:** .claude/settings.json defines all necessary project permissions. CLAUDE.md contains all +project conventions without referencing ~/.claude/CLAUDE.md or user-level settings. The +project works identically for any collaborator regardless of their personal Claude Code +configuration. +**Fail:** CLAUDE.md contains "See ~/.claude/CLAUDE.md for API key configuration" or references +user-level settings with "Ensure your user settings have allowedTools: ['bash']". New +collaborators without this user-level setup receive incomplete or broken instructions. + +## Limitations + +This check scans for explicit references to user-level paths (~/, $HOME/.claude/) and +user-level setting keys. Implicit dependencies (e.g., assuming a user-level MCP server +is configured without referencing it by path) cannot be detected mechanically. The check +also cannot distinguish between documentation mentioning user settings (acceptable) and +operational dependencies on them (violation). diff --git a/agents/claude/rules/project-rules-override-user/rule.yml b/agents/claude/rules/project-rules-override-user/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/project-rules-override-user/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/project-rules-override-user/tests/fail/CLAUDE.md b/agents/claude/rules/project-rules-override-user/tests/fail/CLAUDE.md new file mode 100644 index 0000000..74a4e0c --- /dev/null +++ b/agents/claude/rules/project-rules-override-user/tests/fail/CLAUDE.md @@ -0,0 +1,11 @@ +# MyApp + +Project that depends on user-level settings. + +Developers must configure their ~/.claude/settings.json with the project API key +before starting work. Without the user-level setting, tests will fail. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build diff --git a/agents/claude/rules/project-rules-override-user/tests/pass/.claude/settings.json b/agents/claude/rules/project-rules-override-user/tests/pass/.claude/settings.json new file mode 100644 index 0000000..07f8d69 --- /dev/null +++ b/agents/claude/rules/project-rules-override-user/tests/pass/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "permissions": { + "deny": ["Read(.env)", "Bash(rm -rf)"] + } +} \ No newline at end of file diff --git a/agents/claude/rules/project-rules-override-user/tests/pass/CLAUDE.md b/agents/claude/rules/project-rules-override-user/tests/pass/CLAUDE.md new file mode 100644 index 0000000..a35f81d --- /dev/null +++ b/agents/claude/rules/project-rules-override-user/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Project with explicit project-level rules. + +## Commands + +- `npm test` — run tests diff --git a/agents/claude/rules/rules-directory-structure/rule.md b/agents/claude/rules/rules-directory-structure/rule.md new file mode 100644 index 0000000..b5ffadd --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/rule.md @@ -0,0 +1,48 @@ +--- +id: "CLAUDE:S:0003" +slug: rules-directory-structure +title: Rules Directory Structure +category: structure +type: mechanical +level: L4 +backed_by: +- claude-code-memory +- rules-directory-mechanics +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0003:check:0001" + type: mechanical + check: directory_file_types + args: + path: "{{rules_dir}}" + extensions: [".md"] + severity: medium +question: "Does the .claude/rules/ directory follow single-concern and scoping conventions?" +criteria: +- The .claude/rules/ directory contains only .md files (no other formats) +- Each .md file addresses a focused, single concern +- Files without a paths frontmatter key contain only universally applicable + guidance +- Subdirectory organization is permitted for grouping related rules +--- + +# Rules Directory Structure + +If .claude/rules/ exists, every .md file in it must address a single concern and files without paths frontmatter must contain only universally applicable rules. + +## Pass / Fail + +**Pass:** .claude/rules/testing.md has paths frontmatter scoped to tests/**/*.py and contains only +testing conventions. .claude/rules/commit-style.md has no paths frontmatter and contains +a universal commit message format that applies to all files. Each file addresses one concern. +**Fail:** .claude/rules/everything.md has no paths frontmatter and contains testing conventions, +deployment procedures, and database migration rules all in one file. The testing conventions +are irrelevant when editing frontend code, but they load unconditionally. + +## Limitations + +Determining whether a file addresses "a single concern" is subjective at the mechanical +level. This check uses heuristics: multiple H2 headings on unrelated topics, excessive file +length, or mixed domain keywords. It cannot perfectly judge concern boundaries. The universal +applicability check for unscoped files relies on keyword heuristics rather than semantic +understanding. diff --git a/agents/claude/rules/rules-directory-structure/rule.yml b/agents/claude/rules/rules-directory-structure/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/rules-directory-structure/tests/fail/.claude/rules/config.json b/agents/claude/rules/rules-directory-structure/tests/fail/.claude/rules/config.json new file mode 100644 index 0000000..87c5cc6 --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/tests/fail/.claude/rules/config.json @@ -0,0 +1,4 @@ +{ + "rules": ["security"], + "enabled": true +} \ No newline at end of file diff --git a/agents/claude/rules/rules-directory-structure/tests/fail/.claude/rules/security.md b/agents/claude/rules/rules-directory-structure/tests/fail/.claude/rules/security.md new file mode 100644 index 0000000..1ca9ae6 --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/tests/fail/.claude/rules/security.md @@ -0,0 +1,3 @@ +# Security Rules + +Never commit credentials or API keys to the repository. \ No newline at end of file diff --git a/agents/claude/rules/rules-directory-structure/tests/fail/CLAUDE.md b/agents/claude/rules/rules-directory-structure/tests/fail/CLAUDE.md new file mode 100644 index 0000000..4daaa5d --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/tests/fail/CLAUDE.md @@ -0,0 +1,16 @@ +# MyApp + +Project with rules directory containing non-markdown files. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +``` +src/ # Application code +tests/ # Test suite +.claude/ # Agent configuration +``` diff --git a/agents/claude/rules/rules-directory-structure/tests/pass/.claude/rules/security.md b/agents/claude/rules/rules-directory-structure/tests/pass/.claude/rules/security.md new file mode 100644 index 0000000..05c1c36 --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/tests/pass/.claude/rules/security.md @@ -0,0 +1,3 @@ +# Security Rules + +Never commit credentials. diff --git a/agents/claude/rules/rules-directory-structure/tests/pass/CLAUDE.md b/agents/claude/rules/rules-directory-structure/tests/pass/CLAUDE.md new file mode 100644 index 0000000..33e0803 --- /dev/null +++ b/agents/claude/rules/rules-directory-structure/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Project with rules directory. + +## Commands + +- `npm test` — run tests diff --git a/agents/claude/rules/sensitive-files-denied/rule.md b/agents/claude/rules/sensitive-files-denied/rule.md new file mode 100644 index 0000000..46470c0 --- /dev/null +++ b/agents/claude/rules/sensitive-files-denied/rule.md @@ -0,0 +1,47 @@ +--- +id: "CLAUDE:S:0011" +slug: sensitive-files-denied +title: Sensitive Files Denied in Permissions +category: structure +type: deterministic +level: L2 +backed_by: +- claude-code-settings +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0011:check:0001" + type: deterministic + negate: true + severity: high +question: "Are all sensitive files in the project covered by permissions.deny in Claude + Code settings?" +criteria: +- All .env files (including .env.local, .env.production) are matched by a deny + pattern +- Private key files (*.pem, *.key) are matched by a deny pattern if present +- Credential files (credentials.json, secrets.yml) are matched by a deny pattern + if present +- The permissions.deny configuration exists in .claude/settings.json or + .claude/settings.local.json +--- + +# Sensitive Files Denied in Permissions + +If sensitive files exist in the project (.env, credentials), they must be listed in permissions.deny in the Claude Code settings. + +## Pass / Fail + +**Pass:** The project contains .env and config/secrets.yml. The file .claude/settings.json includes +permissions.deny entries matching .env and config/secrets.yml. Claude Code cannot access +these files. +**Fail:** The project contains .env.production with database credentials. Neither .claude/settings.json +nor .claude/settings.local.json includes a permissions.deny entry covering .env* files. +Claude Code can freely read and reference the credentials. + +## Limitations + +This check scans for common sensitive file patterns (.env*, *.pem, *credentials*, *secret*) +and verifies deny coverage. Custom sensitive files with non-standard names (e.g., my-keys.txt) +are not detected. The check also cannot verify that deny patterns are syntactically correct +in the settings file, only that plausible deny entries exist for discovered sensitive files. diff --git a/agents/claude/rules/sensitive-files-denied/rule.yml b/agents/claude/rules/sensitive-files-denied/rule.yml new file mode 100644 index 0000000..5249484 --- /dev/null +++ b/agents/claude/rules/sensitive-files-denied/rule.yml @@ -0,0 +1,10 @@ +rules: + - id: "CLAUDE.S.0011.check.0001" + message: "Deny pattern for sensitive files found in settings" + severity: WARNING + languages: [json] + pattern-regex: "(?i)(deny|block).*(\\.env|\\.pem|\\.key|credentials|secrets)" + paths: + include: + - ".claude/settings.json" + - ".claude/settings.local.json" diff --git a/agents/claude/rules/sensitive-files-denied/tests/fail/CLAUDE.md b/agents/claude/rules/sensitive-files-denied/tests/fail/CLAUDE.md new file mode 100644 index 0000000..d1af9ed --- /dev/null +++ b/agents/claude/rules/sensitive-files-denied/tests/fail/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with no deny rules. diff --git a/agents/claude/rules/sensitive-files-denied/tests/pass/.claude/settings.json b/agents/claude/rules/sensitive-files-denied/tests/pass/.claude/settings.json new file mode 100644 index 0000000..4b9829e --- /dev/null +++ b/agents/claude/rules/sensitive-files-denied/tests/pass/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "permissions": { + "deny": ["Read(.env)", "Read(credentials/**)", "Read(*.key)"] + } +} diff --git a/agents/claude/rules/sensitive-files-denied/tests/pass/CLAUDE.md b/agents/claude/rules/sensitive-files-denied/tests/pass/CLAUDE.md new file mode 100644 index 0000000..57d00c0 --- /dev/null +++ b/agents/claude/rules/sensitive-files-denied/tests/pass/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with deny rules for sensitive files. diff --git a/agents/claude/rules/settings-files-at-correct-locations/rule.md b/agents/claude/rules/settings-files-at-correct-locations/rule.md new file mode 100644 index 0000000..52536c1 --- /dev/null +++ b/agents/claude/rules/settings-files-at-correct-locations/rule.md @@ -0,0 +1,47 @@ +--- +id: "CLAUDE:S:0010" +slug: settings-files-at-correct-locations +title: Settings Files at Correct Locations +category: structure +type: mechanical +level: L4 +backed_by: +- claude-code-settings +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0010:check:0001" + type: mechanical + check: file_exists + args: + path: ".claude/settings.json" + severity: medium +question: "Are all Claude Code configuration files placed at their documented discovery + locations?" +criteria: +- settings.json for project scope exists at .claude/settings.json, not at the + project root +- settings.local.json exists at .claude/settings.local.json if present +- .mcp.json exists at the project root if MCP configuration is used +- No Claude Code configuration files exist at non-standard locations where they + would be ignored +--- + +# Settings Files at Correct Locations + +Claude Code configuration files (.claude/settings.json, .mcp.json) must be at their documented locations. + +## Pass / Fail + +**Pass:** Project settings are at ./.claude/settings.json. MCP configuration is at ./.mcp.json in +the project root. Local overrides are at ./.claude/settings.local.json. All files are at +their documented discovery paths. +**Fail:** A file named settings.json exists at the project root (./) instead of ./.claude/settings.json. +Claude Code does not discover it, so the project's permission allowlist and tool configuration +are not applied. Alternatively, .mcp.json exists inside .claude/ instead of the project root. + +## Limitations + +This check verifies that configuration files found in the repository are at recognized +paths. It does not validate the content or schema of those files. It also cannot detect +the absence of configuration files that should exist — only misplacement of files that +do exist. Custom configuration file locations set via environment variables are not covered. diff --git a/agents/claude/rules/settings-files-at-correct-locations/rule.yml b/agents/claude/rules/settings-files-at-correct-locations/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/claude/rules/settings-files-at-correct-locations/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/claude/rules/settings-files-at-correct-locations/tests/fail/CLAUDE.md b/agents/claude/rules/settings-files-at-correct-locations/tests/fail/CLAUDE.md new file mode 100644 index 0000000..a4935ac --- /dev/null +++ b/agents/claude/rules/settings-files-at-correct-locations/tests/fail/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with no settings file. diff --git a/agents/claude/rules/settings-files-at-correct-locations/tests/fail/settings.json b/agents/claude/rules/settings-files-at-correct-locations/tests/fail/settings.json new file mode 100644 index 0000000..2ca1798 --- /dev/null +++ b/agents/claude/rules/settings-files-at-correct-locations/tests/fail/settings.json @@ -0,0 +1 @@ +{"permissions": {"allow": ["Bash"]}} diff --git a/agents/claude/rules/settings-files-at-correct-locations/tests/pass/.claude/settings.json b/agents/claude/rules/settings-files-at-correct-locations/tests/pass/.claude/settings.json new file mode 100644 index 0000000..10e810a --- /dev/null +++ b/agents/claude/rules/settings-files-at-correct-locations/tests/pass/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "permissions": { + "allow": ["Bash(npm test)"] + } +} diff --git a/agents/claude/rules/settings-files-at-correct-locations/tests/pass/CLAUDE.md b/agents/claude/rules/settings-files-at-correct-locations/tests/pass/CLAUDE.md new file mode 100644 index 0000000..316c84b --- /dev/null +++ b/agents/claude/rules/settings-files-at-correct-locations/tests/pass/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +Project with settings file. diff --git a/agents/claude/rules/skills-and-subagents-documented/rule.md b/agents/claude/rules/skills-and-subagents-documented/rule.md new file mode 100644 index 0000000..4284e14 --- /dev/null +++ b/agents/claude/rules/skills-and-subagents-documented/rule.md @@ -0,0 +1,50 @@ +--- +id: "CLAUDE:S:0008" +slug: skills-and-subagents-documented +title: Skills and Subagents Are Documented +category: structure +type: deterministic +level: L6 +backed_by: +- claude-code-settings +- osmani-ai-coding-workflow +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CLAUDE:S:0008:check:0001" + type: deterministic + negate: true + severity: medium +question: "Do all skill and subagent files include documentation of their purpose + and usage?" +criteria: +- Every SKILL.md file in .claude/skills/ contains a title and description + section +- Every subagent .md file in .claude/agents/ has YAML frontmatter with role + metadata +- Skill files describe expected inputs or parameters if applicable +- Subagent files explain when and how the subagent should be invoked +- No skill or subagent file is empty or contains only a single undescriptive + line +--- + +# Skills and Subagents Are Documented + +If .claude/skills/ or .claude/agents/ directories exist, the instruction files must document their purpose and usage. + +## Pass / Fail + +**Pass:** .claude/skills/deploy/SKILL.md contains a title, a description of what the skill does, +expected inputs, step-by-step workflow, and example invocation. .claude/agents/reviewer.md +has YAML frontmatter with role description and a markdown body explaining when and how +to use the reviewer subagent. +**Fail:** .claude/skills/deploy/SKILL.md contains only "Deploy the app" with no description of +inputs, steps, or expected behavior. .claude/agents/reviewer.md exists but is empty. +Neither provides enough information for another developer or agent to use them correctly. + +## Limitations + +The check verifies presence of documentation elements (title, description, usage) using +pattern matching but cannot evaluate documentation quality or accuracy. A skill file that +contains boilerplate documentation with no real content will pass the structural check. +The minimum documentation threshold is a heuristic, not a guarantee of usefulness. diff --git a/agents/claude/rules/skills-and-subagents-documented/rule.yml b/agents/claude/rules/skills-and-subagents-documented/rule.yml new file mode 100644 index 0000000..382ee93 --- /dev/null +++ b/agents/claude/rules/skills-and-subagents-documented/rule.yml @@ -0,0 +1,12 @@ +rules: + - id: "CLAUDE.S.0008.check.0001" + message: "Skills or subagent documentation found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)(## skills|SKILL\\.md)" + - pattern-regex: "(?i)(skill|subagent)" + - pattern-regex: "/[a-z]+-[a-z]+" + paths: + include: + - "{{instruction_files}}" diff --git a/agents/claude/rules/skills-and-subagents-documented/tests/fail/CLAUDE.md b/agents/claude/rules/skills-and-subagents-documented/tests/fail/CLAUDE.md new file mode 100644 index 0000000..6b3fe6f --- /dev/null +++ b/agents/claude/rules/skills-and-subagents-documented/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Project with undocumented capabilities. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +Code is in src/ directory. Tests in tests/. diff --git a/agents/claude/rules/skills-and-subagents-documented/tests/pass/CLAUDE.md b/agents/claude/rules/skills-and-subagents-documented/tests/pass/CLAUDE.md new file mode 100644 index 0000000..dfd9ba3 --- /dev/null +++ b/agents/claude/rules/skills-and-subagents-documented/tests/pass/CLAUDE.md @@ -0,0 +1,15 @@ +# MyApp + +Project with documented skills. + +## Skills + +- `/deploy-staging` — deploy current branch to staging environment +- `/run-migrations` — execute pending database migrations +- `/generate-api` — scaffold new API endpoint from template + +See .claude/skills/ for SKILL.md definitions. + +## Commands + +- `npm test` — run tests diff --git a/agents/codex/config.yml b/agents/codex/config.yml index a5ae0b7..442fcc7 100644 --- a/agents/codex/config.yml +++ b/agents/codex/config.yml @@ -2,6 +2,7 @@ # Schema: schemas/agent.schema.yml agent: codex +version: "0.1.0" prefix: CODEX name: OpenAI Codex @@ -17,16 +18,5 @@ vars: override_file: "AGENTS.override.md" size_limit_kb: 32 -# Severity adjustments for Codex-specific behavior -overrides: - # Codex has automatic context compaction - memory instruction less critical - E4-no-memory-instruction: - severity: low - # L6 ritual pattern - Codex handles context automatically - E2-no-ritual-section: - severity: low - # Codex grep behavior may differ from Claude - E5-no-grep-guidance: - severity: low - +# No severity overrides — all moved to reporails/recommended # No core rules excluded — Codex supports generic patterns diff --git a/agents/codex/rules/agents-md-file-placement/rule.md b/agents/codex/rules/agents-md-file-placement/rule.md new file mode 100644 index 0000000..e595358 --- /dev/null +++ b/agents/codex/rules/agents-md-file-placement/rule.md @@ -0,0 +1,45 @@ +--- +id: "CODEX:S:0001" +slug: agents-md-file-placement +title: AGENTS.md File Placement +category: structure +type: mechanical +level: L1 +backed_by: +- agents-md-spec +- codex-agent-loop +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0001:check:0001" + type: mechanical + check: file_exists + args: + path: "AGENTS.md" + severity: critical +question: "Does an AGENTS.md file with exact case-sensitive naming exist at the project + root?" +criteria: +- A file named exactly AGENTS.md exists at the Git/project root +- The filename uses uppercase AGENTS and lowercase .md extension +- The file is not empty (Codex skips empty instruction files) +--- + +# AGENTS.md File Placement + +An AGENTS.md file must exist at the project root with exact case-sensitive naming. + +## Pass / Fail + +**Pass:** The repository root contains a file named exactly AGENTS.md (uppercase AGENTS, uppercase +.MD extension not required — standard .md). Codex discovers it during the instruction walk +from Git root. +**Fail:** The repository has no AGENTS.md at the root. Variants such as agents.md, Agents.md, or +AGENTS.txt are not recognized by Codex's instruction discovery. The agent receives zero +project-level guidance. + +## Limitations + +This check verifies file existence and exact filename only. It does not validate the content +of the AGENTS.md file. An empty AGENTS.md is detected by Codex and skipped, but this rule +only checks for file presence, not content. The check does not verify Git root detection — +it assumes the project root is the Git root. diff --git a/agents/codex/rules/agents-md-file-placement/rule.yml b/agents/codex/rules/agents-md-file-placement/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/agents-md-file-placement/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/agents-md-file-placement/tests/fail/README.md b/agents/codex/rules/agents-md-file-placement/tests/fail/README.md new file mode 100644 index 0000000..35ae285 --- /dev/null +++ b/agents/codex/rules/agents-md-file-placement/tests/fail/README.md @@ -0,0 +1,3 @@ +# MyApp + +No AGENTS.md in this repository. diff --git a/agents/codex/rules/agents-md-file-placement/tests/pass/AGENTS.md b/agents/codex/rules/agents-md-file-placement/tests/pass/AGENTS.md new file mode 100644 index 0000000..5b6f846 --- /dev/null +++ b/agents/codex/rules/agents-md-file-placement/tests/pass/AGENTS.md @@ -0,0 +1,7 @@ +# MyApp + +Web application built with Python. + +## Commands + +- `pytest tests/` — run tests diff --git a/agents/codex/rules/agents-md-override-mechanics/rule.md b/agents/codex/rules/agents-md-override-mechanics/rule.md new file mode 100644 index 0000000..82f5d94 --- /dev/null +++ b/agents/codex/rules/agents-md-override-mechanics/rule.md @@ -0,0 +1,49 @@ +--- +id: "CODEX:S:0002" +slug: agents-md-override-mechanics +title: AGENTS.md Override Mechanics +category: structure +type: mechanical +level: L3 +backed_by: +- codex-agent-loop +- codex-agents-md +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0002:check:0001" + type: mechanical + check: file_count + args: + pattern: "**/AGENTS.override.md" + max: 0 + severity: medium +question: "Do any directories contain both AGENTS.md and AGENTS.override.md, risking + content shadowing?" +criteria: +- No directory in the repository contains both AGENTS.md and AGENTS.override.md + simultaneously +- If both files exist, AGENTS.override.md fully subsumes the content of + AGENTS.md +- The override relationship is intentional and documented, not accidental +--- + +# AGENTS.md Override Mechanics + +Directories containing both AGENTS.md and AGENTS.override.md must not have conflicting content, as only one is loaded. + +## Pass / Fail + +**Pass:** A directory contains only AGENTS.md with project conventions. No AGENTS.override.md exists, +so there is no ambiguity about which file is loaded. Alternatively, AGENTS.override.md +exists alone and fully replaces the guidance that would have been in AGENTS.md. +**Fail:** A directory contains both AGENTS.md (with coding standards) and AGENTS.override.md (with +deployment overrides). The developer expects both to load, but Codex loads only +AGENTS.override.md. The coding standards in AGENTS.md are silently ignored. + +## Limitations + +This check detects coexistence of both files but cannot determine developer intent. In +some workflows, AGENTS.override.md intentionally replaces AGENTS.md (e.g., for CI +environments). The check flags all coexistence as a warning; the developer must confirm +whether the override is intentional and complete. Content comparison between the two files +is not performed. diff --git a/agents/codex/rules/agents-md-override-mechanics/rule.yml b/agents/codex/rules/agents-md-override-mechanics/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/agents-md-override-mechanics/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/agents-md-override-mechanics/tests/fail/AGENTS.md b/agents/codex/rules/agents-md-override-mechanics/tests/fail/AGENTS.md new file mode 100644 index 0000000..10e688f --- /dev/null +++ b/agents/codex/rules/agents-md-override-mechanics/tests/fail/AGENTS.md @@ -0,0 +1,15 @@ +# Project Instructions + +This is a Python web application using FastAPI and PostgreSQL. + +## Commands + +- `pytest tests/` — run all tests +- `uvicorn app.main:app --reload` — start dev server +- `alembic upgrade head` — run database migrations + +## Style + +- Use type hints on all function signatures +- Follow PEP 8 naming conventions +- Keep functions under 50 lines diff --git a/agents/codex/rules/agents-md-override-mechanics/tests/fail/AGENTS.override.md b/agents/codex/rules/agents-md-override-mechanics/tests/fail/AGENTS.override.md new file mode 100644 index 0000000..4c3a0e0 --- /dev/null +++ b/agents/codex/rules/agents-md-override-mechanics/tests/fail/AGENTS.override.md @@ -0,0 +1,14 @@ +# Project Instructions (Override) + +This is a Python web application using FastAPI and PostgreSQL. + +## Commands + +- `pytest tests/ -x --tb=short` — run tests with fail-fast +- `uvicorn app.main:app --reload --port 8080` — start dev server on 8080 + +## Style + +- Use type hints on all function signatures +- Follow PEP 8 naming conventions +- Maximum function length: 30 lines (stricter than base) diff --git a/agents/codex/rules/agents-md-override-mechanics/tests/fail/README.md b/agents/codex/rules/agents-md-override-mechanics/tests/fail/README.md new file mode 100644 index 0000000..19ef5f2 --- /dev/null +++ b/agents/codex/rules/agents-md-override-mechanics/tests/fail/README.md @@ -0,0 +1,3 @@ +# MyApp + +No proper AGENTS.md file. diff --git a/agents/codex/rules/agents-md-override-mechanics/tests/pass/AGENTS.md b/agents/codex/rules/agents-md-override-mechanics/tests/pass/AGENTS.md new file mode 100644 index 0000000..e7c14a8 --- /dev/null +++ b/agents/codex/rules/agents-md-override-mechanics/tests/pass/AGENTS.md @@ -0,0 +1,7 @@ +# MyApp + +Base instruction file. + +## Commands + +- `npm test` — run tests diff --git a/agents/codex/rules/global-agents-md-exists/rule.md b/agents/codex/rules/global-agents-md-exists/rule.md new file mode 100644 index 0000000..ab38be3 --- /dev/null +++ b/agents/codex/rules/global-agents-md-exists/rule.md @@ -0,0 +1,46 @@ +--- +id: "CODEX:S:0006" +slug: global-agents-md-exists +title: Global AGENTS.md Exists +category: structure +type: mechanical +level: L5 +backed_by: +- codex-agent-loop +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0006:check:0001" + type: mechanical + check: file_exists + args: + path: "AGENTS.md" + severity: medium +question: "Does a global AGENTS.md exist in $CODEX_HOME for user-level instruction + defaults?" +criteria: +- An AGENTS.md or AGENTS.override.md file exists in $CODEX_HOME +- The file is not empty (contains meaningful user-level defaults) +- The $CODEX_HOME path resolves to an existing directory +--- + +# Global AGENTS.md Exists + +A global AGENTS.md should exist in $CODEX_HOME for user-level defaults. + +## Pass / Fail + +**Pass:** $CODEX_HOME/AGENTS.md exists and contains user-level conventions: preferred coding style, +organization security policies, and default review expectations. These load as baseline +instructions before any project-specific AGENTS.md. +**Fail:** $CODEX_HOME contains no AGENTS.md or AGENTS.override.md. Codex starts every project +with zero user-level defaults. The developer relies entirely on per-project AGENTS.md +files, missing an opportunity to enforce personal or organizational standards globally. + +## Limitations + +This check verifies file existence at $CODEX_HOME but cannot determine the correct value +of $CODEX_HOME across environments (it defaults to ~/.codex but may be overridden). The +check cannot validate the content quality of the global file. A global AGENTS.md is a +recommendation (L5), not a hard requirement — some workflows intentionally omit it to +avoid interference with project-level instructions. Note that developer_instructions from +config.toml outranks AGENTS.md, which may make the global file redundant in some setups. diff --git a/agents/codex/rules/global-agents-md-exists/rule.yml b/agents/codex/rules/global-agents-md-exists/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/global-agents-md-exists/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/global-agents-md-exists/tests/fail/README.md b/agents/codex/rules/global-agents-md-exists/tests/fail/README.md new file mode 100644 index 0000000..0c4f4fc --- /dev/null +++ b/agents/codex/rules/global-agents-md-exists/tests/fail/README.md @@ -0,0 +1,3 @@ +# Home Directory + +No global AGENTS.md file configured. diff --git a/agents/codex/rules/global-agents-md-exists/tests/pass/AGENTS.md b/agents/codex/rules/global-agents-md-exists/tests/pass/AGENTS.md new file mode 100644 index 0000000..d1ccee8 --- /dev/null +++ b/agents/codex/rules/global-agents-md-exists/tests/pass/AGENTS.md @@ -0,0 +1,7 @@ +# Global User Defaults + +Personal conventions and preferences. + +## Style + +Use 2-space indentation for all projects. diff --git a/agents/codex/rules/instruction-size-within-32kib/rule.md b/agents/codex/rules/instruction-size-within-32kib/rule.md new file mode 100644 index 0000000..a9ac748 --- /dev/null +++ b/agents/codex/rules/instruction-size-within-32kib/rule.md @@ -0,0 +1,51 @@ +--- +id: "CODEX:S:0003" +slug: instruction-size-within-32kib +title: Instruction Size Within 32 KiB +category: structure +type: mechanical +level: L2 +backed_by: +- codex-agent-loop +- codex-agents-md +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0003:check:0001" + type: mechanical + check: aggregate_byte_size + args: + pattern: "**/AGENTS.md" + max: 32768 + severity: high +question: "Does the combined size of AGENTS.md files in any directory chain stay within + 32 KiB?" +criteria: +- The sum of byte sizes for all AGENTS.md files from root to any leaf directory + is at most 32768 bytes +- Empty AGENTS.md files are excluded from the size calculation +- The check evaluates all possible directory paths, not just the current working + directory +- Override files (AGENTS.override.md) replace their AGENTS.md counterpart in the + size calculation +--- + +# Instruction Size Within 32 KiB + +The combined size of all AGENTS.md files in the directory chain must not exceed 32 KiB. + +## Pass / Fail + +**Pass:** The repository has AGENTS.md at the root (8 KiB), packages/AGENTS.md (4 KiB), and +packages/api/AGENTS.md (6 KiB). Combined size is 18 KiB, well under the 32 KiB limit. +All files are fully loaded by Codex. +**Fail:** The repository has AGENTS.md at the root (20 KiB) and packages/api/AGENTS.md (15 KiB). +Combined size is 35 KiB, exceeding the 32 KiB budget. The api-specific AGENTS.md is +partially loaded or skipped, losing the most contextually relevant instructions. + +## Limitations + +This check computes the worst-case directory chain (root to deepest leaf with an AGENTS.md). +Actual budget consumption depends on the specific working directory path at runtime, which +varies per task. The check flags any chain that could exceed the budget. The 32 KiB default +can be changed via configuration, but this rule uses the default value. Empty files are +excluded from the size calculation per Codex behavior. diff --git a/agents/codex/rules/instruction-size-within-32kib/rule.yml b/agents/codex/rules/instruction-size-within-32kib/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/instruction-size-within-32kib/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/instruction-size-within-32kib/tests/fail/AGENTS.md b/agents/codex/rules/instruction-size-within-32kib/tests/fail/AGENTS.md new file mode 100644 index 0000000..2ca6959 --- /dev/null +++ b/agents/codex/rules/instruction-size-within-32kib/tests/fail/AGENTS.md @@ -0,0 +1,2004 @@ +# MyApp + +Overly verbose instruction file exceeding 32 KiB budget. + +## Section 0 + +This is detailed documentation for section 0 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 1 + +This is detailed documentation for section 1 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 2 + +This is detailed documentation for section 2 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 3 + +This is detailed documentation for section 3 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 4 + +This is detailed documentation for section 4 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 5 + +This is detailed documentation for section 5 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 6 + +This is detailed documentation for section 6 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 7 + +This is detailed documentation for section 7 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 8 + +This is detailed documentation for section 8 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 9 + +This is detailed documentation for section 9 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 10 + +This is detailed documentation for section 10 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 11 + +This is detailed documentation for section 11 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 12 + +This is detailed documentation for section 12 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 13 + +This is detailed documentation for section 13 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 14 + +This is detailed documentation for section 14 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 15 + +This is detailed documentation for section 15 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 16 + +This is detailed documentation for section 16 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 17 + +This is detailed documentation for section 17 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 18 + +This is detailed documentation for section 18 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 19 + +This is detailed documentation for section 19 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 20 + +This is detailed documentation for section 20 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 21 + +This is detailed documentation for section 21 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 22 + +This is detailed documentation for section 22 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 23 + +This is detailed documentation for section 23 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 24 + +This is detailed documentation for section 24 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 25 + +This is detailed documentation for section 25 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 26 + +This is detailed documentation for section 26 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 27 + +This is detailed documentation for section 27 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 28 + +This is detailed documentation for section 28 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 29 + +This is detailed documentation for section 29 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 30 + +This is detailed documentation for section 30 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 31 + +This is detailed documentation for section 31 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 32 + +This is detailed documentation for section 32 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 33 + +This is detailed documentation for section 33 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 34 + +This is detailed documentation for section 34 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 35 + +This is detailed documentation for section 35 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 36 + +This is detailed documentation for section 36 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 37 + +This is detailed documentation for section 37 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 38 + +This is detailed documentation for section 38 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 39 + +This is detailed documentation for section 39 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 40 + +This is detailed documentation for section 40 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 41 + +This is detailed documentation for section 41 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 42 + +This is detailed documentation for section 42 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 43 + +This is detailed documentation for section 43 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 44 + +This is detailed documentation for section 44 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 45 + +This is detailed documentation for section 45 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 46 + +This is detailed documentation for section 46 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 47 + +This is detailed documentation for section 47 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 48 + +This is detailed documentation for section 48 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 49 + +This is detailed documentation for section 49 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 50 + +This is detailed documentation for section 50 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 51 + +This is detailed documentation for section 51 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 52 + +This is detailed documentation for section 52 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 53 + +This is detailed documentation for section 53 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 54 + +This is detailed documentation for section 54 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 55 + +This is detailed documentation for section 55 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 56 + +This is detailed documentation for section 56 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 57 + +This is detailed documentation for section 57 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 58 + +This is detailed documentation for section 58 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 59 + +This is detailed documentation for section 59 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 60 + +This is detailed documentation for section 60 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 61 + +This is detailed documentation for section 61 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 62 + +This is detailed documentation for section 62 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 63 + +This is detailed documentation for section 63 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 64 + +This is detailed documentation for section 64 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 65 + +This is detailed documentation for section 65 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 66 + +This is detailed documentation for section 66 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 67 + +This is detailed documentation for section 67 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 68 + +This is detailed documentation for section 68 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 69 + +This is detailed documentation for section 69 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 70 + +This is detailed documentation for section 70 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 71 + +This is detailed documentation for section 71 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 72 + +This is detailed documentation for section 72 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 73 + +This is detailed documentation for section 73 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 74 + +This is detailed documentation for section 74 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 75 + +This is detailed documentation for section 75 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 76 + +This is detailed documentation for section 76 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 77 + +This is detailed documentation for section 77 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 78 + +This is detailed documentation for section 78 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 79 + +This is detailed documentation for section 79 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 80 + +This is detailed documentation for section 80 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 81 + +This is detailed documentation for section 81 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 82 + +This is detailed documentation for section 82 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 83 + +This is detailed documentation for section 83 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 84 + +This is detailed documentation for section 84 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 85 + +This is detailed documentation for section 85 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 86 + +This is detailed documentation for section 86 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 87 + +This is detailed documentation for section 87 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 88 + +This is detailed documentation for section 88 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 89 + +This is detailed documentation for section 89 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 90 + +This is detailed documentation for section 90 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 91 + +This is detailed documentation for section 91 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 92 + +This is detailed documentation for section 92 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 93 + +This is detailed documentation for section 93 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 94 + +This is detailed documentation for section 94 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 95 + +This is detailed documentation for section 95 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 96 + +This is detailed documentation for section 96 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 97 + +This is detailed documentation for section 97 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 98 + +This is detailed documentation for section 98 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 99 + +This is detailed documentation for section 99 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 100 + +This is detailed documentation for section 100 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 101 + +This is detailed documentation for section 101 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 102 + +This is detailed documentation for section 102 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 103 + +This is detailed documentation for section 103 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 104 + +This is detailed documentation for section 104 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 105 + +This is detailed documentation for section 105 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 106 + +This is detailed documentation for section 106 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 107 + +This is detailed documentation for section 107 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 108 + +This is detailed documentation for section 108 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 109 + +This is detailed documentation for section 109 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 110 + +This is detailed documentation for section 110 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 111 + +This is detailed documentation for section 111 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 112 + +This is detailed documentation for section 112 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 113 + +This is detailed documentation for section 113 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 114 + +This is detailed documentation for section 114 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 115 + +This is detailed documentation for section 115 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 116 + +This is detailed documentation for section 116 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 117 + +This is detailed documentation for section 117 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 118 + +This is detailed documentation for section 118 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 119 + +This is detailed documentation for section 119 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 120 + +This is detailed documentation for section 120 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 121 + +This is detailed documentation for section 121 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 122 + +This is detailed documentation for section 122 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 123 + +This is detailed documentation for section 123 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 124 + +This is detailed documentation for section 124 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 125 + +This is detailed documentation for section 125 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 126 + +This is detailed documentation for section 126 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 127 + +This is detailed documentation for section 127 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 128 + +This is detailed documentation for section 128 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 129 + +This is detailed documentation for section 129 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 130 + +This is detailed documentation for section 130 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 131 + +This is detailed documentation for section 131 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 132 + +This is detailed documentation for section 132 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 133 + +This is detailed documentation for section 133 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 134 + +This is detailed documentation for section 134 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 135 + +This is detailed documentation for section 135 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 136 + +This is detailed documentation for section 136 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 137 + +This is detailed documentation for section 137 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 138 + +This is detailed documentation for section 138 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 139 + +This is detailed documentation for section 139 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 140 + +This is detailed documentation for section 140 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 141 + +This is detailed documentation for section 141 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 142 + +This is detailed documentation for section 142 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 143 + +This is detailed documentation for section 143 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 144 + +This is detailed documentation for section 144 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 145 + +This is detailed documentation for section 145 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 146 + +This is detailed documentation for section 146 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 147 + +This is detailed documentation for section 147 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 148 + +This is detailed documentation for section 148 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 149 + +This is detailed documentation for section 149 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 150 + +This is detailed documentation for section 150 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 151 + +This is detailed documentation for section 151 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 152 + +This is detailed documentation for section 152 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 153 + +This is detailed documentation for section 153 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 154 + +This is detailed documentation for section 154 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 155 + +This is detailed documentation for section 155 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 156 + +This is detailed documentation for section 156 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 157 + +This is detailed documentation for section 157 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 158 + +This is detailed documentation for section 158 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 159 + +This is detailed documentation for section 159 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 160 + +This is detailed documentation for section 160 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 161 + +This is detailed documentation for section 161 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 162 + +This is detailed documentation for section 162 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 163 + +This is detailed documentation for section 163 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 164 + +This is detailed documentation for section 164 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 165 + +This is detailed documentation for section 165 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 166 + +This is detailed documentation for section 166 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 167 + +This is detailed documentation for section 167 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 168 + +This is detailed documentation for section 168 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 169 + +This is detailed documentation for section 169 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 170 + +This is detailed documentation for section 170 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 171 + +This is detailed documentation for section 171 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 172 + +This is detailed documentation for section 172 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 173 + +This is detailed documentation for section 173 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 174 + +This is detailed documentation for section 174 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 175 + +This is detailed documentation for section 175 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 176 + +This is detailed documentation for section 176 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 177 + +This is detailed documentation for section 177 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 178 + +This is detailed documentation for section 178 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 179 + +This is detailed documentation for section 179 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 180 + +This is detailed documentation for section 180 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 181 + +This is detailed documentation for section 181 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 182 + +This is detailed documentation for section 182 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 183 + +This is detailed documentation for section 183 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 184 + +This is detailed documentation for section 184 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 185 + +This is detailed documentation for section 185 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 186 + +This is detailed documentation for section 186 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 187 + +This is detailed documentation for section 187 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 188 + +This is detailed documentation for section 188 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 189 + +This is detailed documentation for section 189 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 190 + +This is detailed documentation for section 190 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 191 + +This is detailed documentation for section 191 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 192 + +This is detailed documentation for section 192 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 193 + +This is detailed documentation for section 193 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 194 + +This is detailed documentation for section 194 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 195 + +This is detailed documentation for section 195 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 196 + +This is detailed documentation for section 196 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 197 + +This is detailed documentation for section 197 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 198 + +This is detailed documentation for section 198 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 199 + +This is detailed documentation for section 199 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 200 + +This is detailed documentation for section 200 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 201 + +This is detailed documentation for section 201 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 202 + +This is detailed documentation for section 202 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 203 + +This is detailed documentation for section 203 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 204 + +This is detailed documentation for section 204 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 205 + +This is detailed documentation for section 205 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 206 + +This is detailed documentation for section 206 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 207 + +This is detailed documentation for section 207 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 208 + +This is detailed documentation for section 208 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 209 + +This is detailed documentation for section 209 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 210 + +This is detailed documentation for section 210 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 211 + +This is detailed documentation for section 211 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 212 + +This is detailed documentation for section 212 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 213 + +This is detailed documentation for section 213 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 214 + +This is detailed documentation for section 214 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 215 + +This is detailed documentation for section 215 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 216 + +This is detailed documentation for section 216 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 217 + +This is detailed documentation for section 217 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 218 + +This is detailed documentation for section 218 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 219 + +This is detailed documentation for section 219 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 220 + +This is detailed documentation for section 220 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 221 + +This is detailed documentation for section 221 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 222 + +This is detailed documentation for section 222 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 223 + +This is detailed documentation for section 223 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 224 + +This is detailed documentation for section 224 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 225 + +This is detailed documentation for section 225 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 226 + +This is detailed documentation for section 226 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 227 + +This is detailed documentation for section 227 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 228 + +This is detailed documentation for section 228 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 229 + +This is detailed documentation for section 229 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 230 + +This is detailed documentation for section 230 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 231 + +This is detailed documentation for section 231 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 232 + +This is detailed documentation for section 232 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 233 + +This is detailed documentation for section 233 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 234 + +This is detailed documentation for section 234 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 235 + +This is detailed documentation for section 235 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 236 + +This is detailed documentation for section 236 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 237 + +This is detailed documentation for section 237 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 238 + +This is detailed documentation for section 238 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 239 + +This is detailed documentation for section 239 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 240 + +This is detailed documentation for section 240 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 241 + +This is detailed documentation for section 241 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 242 + +This is detailed documentation for section 242 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 243 + +This is detailed documentation for section 243 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 244 + +This is detailed documentation for section 244 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 245 + +This is detailed documentation for section 245 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 246 + +This is detailed documentation for section 246 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 247 + +This is detailed documentation for section 247 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 248 + +This is detailed documentation for section 248 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 249 + +This is detailed documentation for section 249 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 250 + +This is detailed documentation for section 250 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 251 + +This is detailed documentation for section 251 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 252 + +This is detailed documentation for section 252 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 253 + +This is detailed documentation for section 253 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 254 + +This is detailed documentation for section 254 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 255 + +This is detailed documentation for section 255 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 256 + +This is detailed documentation for section 256 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 257 + +This is detailed documentation for section 257 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 258 + +This is detailed documentation for section 258 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 259 + +This is detailed documentation for section 259 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 260 + +This is detailed documentation for section 260 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 261 + +This is detailed documentation for section 261 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 262 + +This is detailed documentation for section 262 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 263 + +This is detailed documentation for section 263 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 264 + +This is detailed documentation for section 264 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 265 + +This is detailed documentation for section 265 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 266 + +This is detailed documentation for section 266 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 267 + +This is detailed documentation for section 267 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 268 + +This is detailed documentation for section 268 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 269 + +This is detailed documentation for section 269 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 270 + +This is detailed documentation for section 270 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 271 + +This is detailed documentation for section 271 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 272 + +This is detailed documentation for section 272 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 273 + +This is detailed documentation for section 273 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 274 + +This is detailed documentation for section 274 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 275 + +This is detailed documentation for section 275 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 276 + +This is detailed documentation for section 276 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 277 + +This is detailed documentation for section 277 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 278 + +This is detailed documentation for section 278 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 279 + +This is detailed documentation for section 279 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 280 + +This is detailed documentation for section 280 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 281 + +This is detailed documentation for section 281 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 282 + +This is detailed documentation for section 282 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 283 + +This is detailed documentation for section 283 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 284 + +This is detailed documentation for section 284 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 285 + +This is detailed documentation for section 285 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 286 + +This is detailed documentation for section 286 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 287 + +This is detailed documentation for section 287 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 288 + +This is detailed documentation for section 288 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 289 + +This is detailed documentation for section 289 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 290 + +This is detailed documentation for section 290 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 291 + +This is detailed documentation for section 291 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 292 + +This is detailed documentation for section 292 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 293 + +This is detailed documentation for section 293 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 294 + +This is detailed documentation for section 294 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 295 + +This is detailed documentation for section 295 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 296 + +This is detailed documentation for section 296 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 297 + +This is detailed documentation for section 297 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 298 + +This is detailed documentation for section 298 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 299 + +This is detailed documentation for section 299 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 300 + +This is detailed documentation for section 300 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 301 + +This is detailed documentation for section 301 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 302 + +This is detailed documentation for section 302 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 303 + +This is detailed documentation for section 303 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 304 + +This is detailed documentation for section 304 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 305 + +This is detailed documentation for section 305 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 306 + +This is detailed documentation for section 306 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 307 + +This is detailed documentation for section 307 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 308 + +This is detailed documentation for section 308 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 309 + +This is detailed documentation for section 309 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 310 + +This is detailed documentation for section 310 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 311 + +This is detailed documentation for section 311 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 312 + +This is detailed documentation for section 312 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 313 + +This is detailed documentation for section 313 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 314 + +This is detailed documentation for section 314 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 315 + +This is detailed documentation for section 315 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 316 + +This is detailed documentation for section 316 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 317 + +This is detailed documentation for section 317 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 318 + +This is detailed documentation for section 318 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 319 + +This is detailed documentation for section 319 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 320 + +This is detailed documentation for section 320 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 321 + +This is detailed documentation for section 321 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 322 + +This is detailed documentation for section 322 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 323 + +This is detailed documentation for section 323 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 324 + +This is detailed documentation for section 324 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 325 + +This is detailed documentation for section 325 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 326 + +This is detailed documentation for section 326 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 327 + +This is detailed documentation for section 327 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 328 + +This is detailed documentation for section 328 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 329 + +This is detailed documentation for section 329 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 330 + +This is detailed documentation for section 330 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 331 + +This is detailed documentation for section 331 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 332 + +This is detailed documentation for section 332 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 333 + +This is detailed documentation for section 333 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 334 + +This is detailed documentation for section 334 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 335 + +This is detailed documentation for section 335 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 336 + +This is detailed documentation for section 336 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 337 + +This is detailed documentation for section 337 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 338 + +This is detailed documentation for section 338 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 339 + +This is detailed documentation for section 339 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 340 + +This is detailed documentation for section 340 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 341 + +This is detailed documentation for section 341 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 342 + +This is detailed documentation for section 342 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 343 + +This is detailed documentation for section 343 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 344 + +This is detailed documentation for section 344 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 345 + +This is detailed documentation for section 345 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 346 + +This is detailed documentation for section 346 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 347 + +This is detailed documentation for section 347 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 348 + +This is detailed documentation for section 348 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 349 + +This is detailed documentation for section 349 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 350 + +This is detailed documentation for section 350 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 351 + +This is detailed documentation for section 351 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 352 + +This is detailed documentation for section 352 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 353 + +This is detailed documentation for section 353 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 354 + +This is detailed documentation for section 354 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 355 + +This is detailed documentation for section 355 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 356 + +This is detailed documentation for section 356 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 357 + +This is detailed documentation for section 357 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 358 + +This is detailed documentation for section 358 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 359 + +This is detailed documentation for section 359 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 360 + +This is detailed documentation for section 360 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 361 + +This is detailed documentation for section 361 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 362 + +This is detailed documentation for section 362 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 363 + +This is detailed documentation for section 363 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 364 + +This is detailed documentation for section 364 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 365 + +This is detailed documentation for section 365 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 366 + +This is detailed documentation for section 366 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 367 + +This is detailed documentation for section 367 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 368 + +This is detailed documentation for section 368 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 369 + +This is detailed documentation for section 369 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 370 + +This is detailed documentation for section 370 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 371 + +This is detailed documentation for section 371 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 372 + +This is detailed documentation for section 372 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 373 + +This is detailed documentation for section 373 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 374 + +This is detailed documentation for section 374 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 375 + +This is detailed documentation for section 375 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 376 + +This is detailed documentation for section 376 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 377 + +This is detailed documentation for section 377 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 378 + +This is detailed documentation for section 378 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 379 + +This is detailed documentation for section 379 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 380 + +This is detailed documentation for section 380 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 381 + +This is detailed documentation for section 381 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 382 + +This is detailed documentation for section 382 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 383 + +This is detailed documentation for section 383 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 384 + +This is detailed documentation for section 384 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 385 + +This is detailed documentation for section 385 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 386 + +This is detailed documentation for section 386 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 387 + +This is detailed documentation for section 387 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 388 + +This is detailed documentation for section 388 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 389 + +This is detailed documentation for section 389 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 390 + +This is detailed documentation for section 390 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 391 + +This is detailed documentation for section 391 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 392 + +This is detailed documentation for section 392 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 393 + +This is detailed documentation for section 393 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 394 + +This is detailed documentation for section 394 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 395 + +This is detailed documentation for section 395 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 396 + +This is detailed documentation for section 396 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 397 + +This is detailed documentation for section 397 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 398 + +This is detailed documentation for section 398 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 399 + +This is detailed documentation for section 399 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 400 + +This is detailed documentation for section 400 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 401 + +This is detailed documentation for section 401 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 402 + +This is detailed documentation for section 402 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 403 + +This is detailed documentation for section 403 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 404 + +This is detailed documentation for section 404 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 405 + +This is detailed documentation for section 405 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 406 + +This is detailed documentation for section 406 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 407 + +This is detailed documentation for section 407 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 408 + +This is detailed documentation for section 408 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 409 + +This is detailed documentation for section 409 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 410 + +This is detailed documentation for section 410 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 411 + +This is detailed documentation for section 411 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 412 + +This is detailed documentation for section 412 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 413 + +This is detailed documentation for section 413 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 414 + +This is detailed documentation for section 414 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 415 + +This is detailed documentation for section 415 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 416 + +This is detailed documentation for section 416 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 417 + +This is detailed documentation for section 417 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 418 + +This is detailed documentation for section 418 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 419 + +This is detailed documentation for section 419 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 420 + +This is detailed documentation for section 420 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 421 + +This is detailed documentation for section 421 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 422 + +This is detailed documentation for section 422 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 423 + +This is detailed documentation for section 423 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 424 + +This is detailed documentation for section 424 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 425 + +This is detailed documentation for section 425 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 426 + +This is detailed documentation for section 426 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 427 + +This is detailed documentation for section 427 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 428 + +This is detailed documentation for section 428 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 429 + +This is detailed documentation for section 429 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 430 + +This is detailed documentation for section 430 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 431 + +This is detailed documentation for section 431 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 432 + +This is detailed documentation for section 432 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 433 + +This is detailed documentation for section 433 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 434 + +This is detailed documentation for section 434 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 435 + +This is detailed documentation for section 435 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 436 + +This is detailed documentation for section 436 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 437 + +This is detailed documentation for section 437 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 438 + +This is detailed documentation for section 438 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 439 + +This is detailed documentation for section 439 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 440 + +This is detailed documentation for section 440 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 441 + +This is detailed documentation for section 441 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 442 + +This is detailed documentation for section 442 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 443 + +This is detailed documentation for section 443 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 444 + +This is detailed documentation for section 444 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 445 + +This is detailed documentation for section 445 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 446 + +This is detailed documentation for section 446 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 447 + +This is detailed documentation for section 447 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 448 + +This is detailed documentation for section 448 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 449 + +This is detailed documentation for section 449 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 450 + +This is detailed documentation for section 450 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 451 + +This is detailed documentation for section 451 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 452 + +This is detailed documentation for section 452 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 453 + +This is detailed documentation for section 453 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 454 + +This is detailed documentation for section 454 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 455 + +This is detailed documentation for section 455 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 456 + +This is detailed documentation for section 456 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 457 + +This is detailed documentation for section 457 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 458 + +This is detailed documentation for section 458 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 459 + +This is detailed documentation for section 459 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 460 + +This is detailed documentation for section 460 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 461 + +This is detailed documentation for section 461 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 462 + +This is detailed documentation for section 462 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 463 + +This is detailed documentation for section 463 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 464 + +This is detailed documentation for section 464 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 465 + +This is detailed documentation for section 465 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 466 + +This is detailed documentation for section 466 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 467 + +This is detailed documentation for section 467 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 468 + +This is detailed documentation for section 468 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 469 + +This is detailed documentation for section 469 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 470 + +This is detailed documentation for section 470 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 471 + +This is detailed documentation for section 471 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 472 + +This is detailed documentation for section 472 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 473 + +This is detailed documentation for section 473 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 474 + +This is detailed documentation for section 474 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 475 + +This is detailed documentation for section 475 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 476 + +This is detailed documentation for section 476 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 477 + +This is detailed documentation for section 477 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 478 + +This is detailed documentation for section 478 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 479 + +This is detailed documentation for section 479 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 480 + +This is detailed documentation for section 480 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 481 + +This is detailed documentation for section 481 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 482 + +This is detailed documentation for section 482 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 483 + +This is detailed documentation for section 483 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 484 + +This is detailed documentation for section 484 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 485 + +This is detailed documentation for section 485 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 486 + +This is detailed documentation for section 486 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 487 + +This is detailed documentation for section 487 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 488 + +This is detailed documentation for section 488 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 489 + +This is detailed documentation for section 489 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 490 + +This is detailed documentation for section 490 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 491 + +This is detailed documentation for section 491 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 492 + +This is detailed documentation for section 492 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 493 + +This is detailed documentation for section 493 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 494 + +This is detailed documentation for section 494 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 495 + +This is detailed documentation for section 495 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 496 + +This is detailed documentation for section 496 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 497 + +This is detailed documentation for section 497 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 498 + +This is detailed documentation for section 498 with enough content to push the file over the size limit. It includes repetitive explanatory text. + +## Section 499 + +This is detailed documentation for section 499 with enough content to push the file over the size limit. It includes repetitive explanatory text. + diff --git a/agents/codex/rules/instruction-size-within-32kib/tests/pass/AGENTS.md b/agents/codex/rules/instruction-size-within-32kib/tests/pass/AGENTS.md new file mode 100644 index 0000000..96d9527 --- /dev/null +++ b/agents/codex/rules/instruction-size-within-32kib/tests/pass/AGENTS.md @@ -0,0 +1,15 @@ +# MyApp + +Compact instruction file well under 32 KiB. + +## Commands + +- `pytest tests/` — run tests +- `npm run build` — production build + +## Structure + +``` +src/ # Application code +tests/ # Test suite +``` diff --git a/agents/codex/rules/nested-files-for-subprojects/rule.md b/agents/codex/rules/nested-files-for-subprojects/rule.md new file mode 100644 index 0000000..b288453 --- /dev/null +++ b/agents/codex/rules/nested-files-for-subprojects/rule.md @@ -0,0 +1,53 @@ +--- +id: "CODEX:S:0005" +slug: nested-files-for-subprojects +title: Nested AGENTS.md for Subprojects +category: structure +type: mechanical +level: L3 +backed_by: +- agents-md-spec +- codex-agent-loop +- codex-agents-md +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0005:check:0001" + type: mechanical + check: file_count + args: + pattern: "**/AGENTS.md" + min: 2 + severity: medium +question: "Do subproject directories in a monorepo have their own AGENTS.md when they + have distinct conventions?" +criteria: +- Directories with project manifest files (package.json, setup.py, etc.) are + identified as subprojects +- Each subproject directory contains an AGENTS.md or AGENTS.override.md file +- Subproject AGENTS.md files contain conventions specific to that subproject's + stack +- The root AGENTS.md covers only shared, cross-subproject conventions +--- + +# Nested AGENTS.md for Subprojects + +In monorepo setups, each subproject directory with distinct conventions must have its own AGENTS.md. + +## Pass / Fail + +**Pass:** A monorepo has packages/api/ (Python, FastAPI) and packages/web/ (TypeScript, React). Both +directories contain AGENTS.md files with stack-specific conventions. The root AGENTS.md +covers shared conventions. Codex loads the appropriate instructions when working in either +subproject. +**Fail:** A monorepo has packages/api/ (Python) and packages/web/ (TypeScript). Only the root +AGENTS.md exists with TypeScript conventions. When Codex works in packages/api/, it applies +TypeScript conventions to Python code because no api-specific AGENTS.md overrides the root. + +## Limitations + +Identifying "subproject directories with distinct conventions" requires heuristics: presence +of package.json, setup.py, Cargo.toml, or other project manifests. The check cannot +determine whether a subproject's conventions actually differ from the root without semantic +analysis. Some monorepos have uniform conventions across all subprojects, making per- +subproject AGENTS.md unnecessary. The check flags subprojects without AGENTS.md as warnings, +not errors. diff --git a/agents/codex/rules/nested-files-for-subprojects/rule.yml b/agents/codex/rules/nested-files-for-subprojects/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/nested-files-for-subprojects/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/nested-files-for-subprojects/tests/fail/AGENTS.md b/agents/codex/rules/nested-files-for-subprojects/tests/fail/AGENTS.md new file mode 100644 index 0000000..8519c86 --- /dev/null +++ b/agents/codex/rules/nested-files-for-subprojects/tests/fail/AGENTS.md @@ -0,0 +1,7 @@ +# MyMonorepo + +Monorepo with no nested instruction files. + +## Commands + +- `npm test` — run tests diff --git a/agents/codex/rules/nested-files-for-subprojects/tests/pass/AGENTS.md b/agents/codex/rules/nested-files-for-subprojects/tests/pass/AGENTS.md new file mode 100644 index 0000000..52c9f97 --- /dev/null +++ b/agents/codex/rules/nested-files-for-subprojects/tests/pass/AGENTS.md @@ -0,0 +1,7 @@ +# MyMonorepo + +Monorepo with multiple subprojects. + +## Commands + +- `npm test` — run all tests diff --git a/agents/codex/rules/nested-files-for-subprojects/tests/pass/packages/auth/AGENTS.md b/agents/codex/rules/nested-files-for-subprojects/tests/pass/packages/auth/AGENTS.md new file mode 100644 index 0000000..8f2cdc5 --- /dev/null +++ b/agents/codex/rules/nested-files-for-subprojects/tests/pass/packages/auth/AGENTS.md @@ -0,0 +1,7 @@ +# Auth Package + +Authentication service with JWT tokens. + +## Commands + +- `pytest tests/` — run auth tests diff --git a/agents/codex/rules/recognized-filenames-only/rule.md b/agents/codex/rules/recognized-filenames-only/rule.md new file mode 100644 index 0000000..241d6d8 --- /dev/null +++ b/agents/codex/rules/recognized-filenames-only/rule.md @@ -0,0 +1,48 @@ +--- +id: "CODEX:S:0004" +slug: recognized-filenames-only +title: Recognized Filenames Only +category: structure +type: mechanical +level: L2 +backed_by: +- codex-agents-md +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0004:check:0001" + type: mechanical + check: file_count + args: + pattern: "**/INSTRUCTIONS.md" + max: 0 + severity: medium +question: "Do all instruction-intent files use filenames that Codex recognizes for + automatic discovery?" +criteria: +- All instruction files are named AGENTS.md or AGENTS.override.md +- No files with instruction content use alternative names that Codex would + ignore +- Configured fallback filenames (if any) are on the recognized list +- Files named similarly but incorrectly (agents.md, AGENT.md) are flagged as + likely mistakes +--- + +# Recognized Filenames Only + +Codex instruction files must use recognized filenames (AGENTS.md, AGENTS.override.md, or configured fallbacks). + +## Pass / Fail + +**Pass:** All instruction files are named AGENTS.md or AGENTS.override.md. No files with instruction +content use non-standard names. Codex discovers and loads every intended instruction file. +**Fail:** A directory contains INSTRUCTIONS.md with coding conventions intended for Codex. Because +the filename is not on the recognized list, Codex ignores it entirely. The developer +believes the instructions are active, but they are never loaded. + +## Limitations + +This check identifies files that appear to contain instruction content but use unrecognized +filenames. Detecting "instruction intent" in non-standard files requires heuristics (e.g., +files mentioning "Codex", "agent", or "instructions" in their content). Files with +ambiguous purpose may produce false positives. The recognized filename list may change +across Codex versions; this rule uses the documented set as of the backing claims. diff --git a/agents/codex/rules/recognized-filenames-only/rule.yml b/agents/codex/rules/recognized-filenames-only/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/recognized-filenames-only/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/recognized-filenames-only/tests/fail/INSTRUCTIONS.md b/agents/codex/rules/recognized-filenames-only/tests/fail/INSTRUCTIONS.md new file mode 100644 index 0000000..887f331 --- /dev/null +++ b/agents/codex/rules/recognized-filenames-only/tests/fail/INSTRUCTIONS.md @@ -0,0 +1,7 @@ +# MyApp + +Using wrong filename — will be silently ignored by Codex. + +## Commands + +- `npm test` — run tests diff --git a/agents/codex/rules/recognized-filenames-only/tests/pass/AGENTS.md b/agents/codex/rules/recognized-filenames-only/tests/pass/AGENTS.md new file mode 100644 index 0000000..11aee84 --- /dev/null +++ b/agents/codex/rules/recognized-filenames-only/tests/pass/AGENTS.md @@ -0,0 +1,7 @@ +# MyApp + +Using the correct AGENTS.md filename. + +## Commands + +- `npm test` — run tests diff --git a/agents/codex/rules/skills-within-instruction-budget/rule.md b/agents/codex/rules/skills-within-instruction-budget/rule.md new file mode 100644 index 0000000..6fc84f6 --- /dev/null +++ b/agents/codex/rules/skills-within-instruction-budget/rule.md @@ -0,0 +1,50 @@ +--- +id: "CODEX:S:0007" +slug: skills-within-instruction-budget +title: Skills Within Instruction Budget +category: structure +type: mechanical +level: L6 +backed_by: +- codex-agent-loop +targets: '{{instruction_files}}' +checks: +- id: "CODEX:S:0007:check:0001" + type: mechanical + check: aggregate_byte_size + args: + pattern: "**/AGENTS.md" + max: 32768 + severity: medium +question: "Does the combined size of AGENTS.md files and configured skill content + fit within the 32 KiB budget?" +criteria: +- The sum of all AGENTS.md file sizes plus skill content sizes does not exceed + 32768 bytes +- Skill content includes preamble, metadata, and usage text as injected by Codex +- The calculation uses the worst-case directory chain for AGENTS.md sizing +- Empty AGENTS.md files and unconfigured skills are excluded from the + calculation +--- + +# Skills Within Instruction Budget + +The combined size of AGENTS.md files plus configured skill content must not exceed the 32 KiB instruction budget. + +## Pass / Fail + +**Pass:** AGENTS.md files total 12 KiB. Three configured skills contribute 6 KiB of preamble, +metadata, and usage text. The combined total is 18 KiB, within the 32 KiB budget. All +instructions and skill definitions are fully loaded. +**Fail:** AGENTS.md files total 24 KiB. Four configured skills contribute 12 KiB. The combined +total is 36 KiB, exceeding the 32 KiB budget. Skill definitions loaded last are truncated, +causing incomplete or broken skill behavior during task execution. + +## Limitations + +Skill content size depends on the configured skills at runtime, which may vary per user +or environment. This check measures the skill content from the project's skill configuration +files but cannot account for user-level or dynamically added skills. The 32 KiB default +budget can be changed via configuration; this rule uses the default value. The exact +serialization overhead (metadata headers, separators) added by Codex may vary across +versions, introducing a small margin of error. diff --git a/agents/codex/rules/skills-within-instruction-budget/rule.yml b/agents/codex/rules/skills-within-instruction-budget/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/agents/codex/rules/skills-within-instruction-budget/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/agents/codex/rules/skills-within-instruction-budget/tests/fail/AGENTS.md b/agents/codex/rules/skills-within-instruction-budget/tests/fail/AGENTS.md new file mode 100644 index 0000000..adf5da6 --- /dev/null +++ b/agents/codex/rules/skills-within-instruction-budget/tests/fail/AGENTS.md @@ -0,0 +1,1543 @@ +# MyApp + +Instructions that will be combined with verbose skills to exceed budget. + +## Section 0: Module Configuration 0 + +This section provides comprehensive documentation for module 0 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_0_ENDPOINT`: Service endpoint URL for module 0 (required, no default) +- `MODULE_0_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_0_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_0_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_0_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 0 tests with: `npm run test:module-0` +Integration tests require the staging environment to be running. + + +## Section 1: Module Configuration 1 + +This section provides comprehensive documentation for module 1 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_1_ENDPOINT`: Service endpoint URL for module 1 (required, no default) +- `MODULE_1_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_1_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_1_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_1_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 1 tests with: `npm run test:module-1` +Integration tests require the staging environment to be running. + + +## Section 2: Module Configuration 2 + +This section provides comprehensive documentation for module 2 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_2_ENDPOINT`: Service endpoint URL for module 2 (required, no default) +- `MODULE_2_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_2_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_2_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_2_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 2 tests with: `npm run test:module-2` +Integration tests require the staging environment to be running. + + +## Section 3: Module Configuration 3 + +This section provides comprehensive documentation for module 3 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_3_ENDPOINT`: Service endpoint URL for module 3 (required, no default) +- `MODULE_3_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_3_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_3_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_3_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 3 tests with: `npm run test:module-3` +Integration tests require the staging environment to be running. + + +## Section 4: Module Configuration 4 + +This section provides comprehensive documentation for module 4 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_4_ENDPOINT`: Service endpoint URL for module 4 (required, no default) +- `MODULE_4_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_4_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_4_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_4_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 4 tests with: `npm run test:module-4` +Integration tests require the staging environment to be running. + + +## Section 5: Module Configuration 5 + +This section provides comprehensive documentation for module 5 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_5_ENDPOINT`: Service endpoint URL for module 5 (required, no default) +- `MODULE_5_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_5_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_5_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_5_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 5 tests with: `npm run test:module-5` +Integration tests require the staging environment to be running. + + +## Section 6: Module Configuration 6 + +This section provides comprehensive documentation for module 6 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_6_ENDPOINT`: Service endpoint URL for module 6 (required, no default) +- `MODULE_6_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_6_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_6_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_6_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 6 tests with: `npm run test:module-6` +Integration tests require the staging environment to be running. + + +## Section 7: Module Configuration 7 + +This section provides comprehensive documentation for module 7 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_7_ENDPOINT`: Service endpoint URL for module 7 (required, no default) +- `MODULE_7_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_7_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_7_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_7_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 7 tests with: `npm run test:module-7` +Integration tests require the staging environment to be running. + + +## Section 8: Module Configuration 8 + +This section provides comprehensive documentation for module 8 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_8_ENDPOINT`: Service endpoint URL for module 8 (required, no default) +- `MODULE_8_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_8_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_8_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_8_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 8 tests with: `npm run test:module-8` +Integration tests require the staging environment to be running. + + +## Section 9: Module Configuration 9 + +This section provides comprehensive documentation for module 9 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_9_ENDPOINT`: Service endpoint URL for module 9 (required, no default) +- `MODULE_9_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_9_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_9_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_9_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 9 tests with: `npm run test:module-9` +Integration tests require the staging environment to be running. + + +## Section 10: Module Configuration 10 + +This section provides comprehensive documentation for module 10 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_10_ENDPOINT`: Service endpoint URL for module 10 (required, no default) +- `MODULE_10_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_10_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_10_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_10_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 10 tests with: `npm run test:module-10` +Integration tests require the staging environment to be running. + + +## Section 11: Module Configuration 11 + +This section provides comprehensive documentation for module 11 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_11_ENDPOINT`: Service endpoint URL for module 11 (required, no default) +- `MODULE_11_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_11_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_11_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_11_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 11 tests with: `npm run test:module-11` +Integration tests require the staging environment to be running. + + +## Section 12: Module Configuration 12 + +This section provides comprehensive documentation for module 12 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_12_ENDPOINT`: Service endpoint URL for module 12 (required, no default) +- `MODULE_12_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_12_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_12_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_12_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 12 tests with: `npm run test:module-12` +Integration tests require the staging environment to be running. + + +## Section 13: Module Configuration 13 + +This section provides comprehensive documentation for module 13 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_13_ENDPOINT`: Service endpoint URL for module 13 (required, no default) +- `MODULE_13_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_13_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_13_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_13_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 13 tests with: `npm run test:module-13` +Integration tests require the staging environment to be running. + + +## Section 14: Module Configuration 14 + +This section provides comprehensive documentation for module 14 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_14_ENDPOINT`: Service endpoint URL for module 14 (required, no default) +- `MODULE_14_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_14_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_14_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_14_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 14 tests with: `npm run test:module-14` +Integration tests require the staging environment to be running. + + +## Section 15: Module Configuration 15 + +This section provides comprehensive documentation for module 15 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_15_ENDPOINT`: Service endpoint URL for module 15 (required, no default) +- `MODULE_15_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_15_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_15_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_15_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 15 tests with: `npm run test:module-15` +Integration tests require the staging environment to be running. + + +## Section 16: Module Configuration 16 + +This section provides comprehensive documentation for module 16 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_16_ENDPOINT`: Service endpoint URL for module 16 (required, no default) +- `MODULE_16_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_16_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_16_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_16_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 16 tests with: `npm run test:module-16` +Integration tests require the staging environment to be running. + + +## Section 17: Module Configuration 17 + +This section provides comprehensive documentation for module 17 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_17_ENDPOINT`: Service endpoint URL for module 17 (required, no default) +- `MODULE_17_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_17_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_17_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_17_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 17 tests with: `npm run test:module-17` +Integration tests require the staging environment to be running. + + +## Section 18: Module Configuration 18 + +This section provides comprehensive documentation for module 18 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_18_ENDPOINT`: Service endpoint URL for module 18 (required, no default) +- `MODULE_18_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_18_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_18_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_18_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 18 tests with: `npm run test:module-18` +Integration tests require the staging environment to be running. + + +## Section 19: Module Configuration 19 + +This section provides comprehensive documentation for module 19 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_19_ENDPOINT`: Service endpoint URL for module 19 (required, no default) +- `MODULE_19_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_19_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_19_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_19_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 19 tests with: `npm run test:module-19` +Integration tests require the staging environment to be running. + + +## Section 20: Module Configuration 20 + +This section provides comprehensive documentation for module 20 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_20_ENDPOINT`: Service endpoint URL for module 20 (required, no default) +- `MODULE_20_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_20_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_20_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_20_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 20 tests with: `npm run test:module-20` +Integration tests require the staging environment to be running. + + +## Section 21: Module Configuration 21 + +This section provides comprehensive documentation for module 21 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_21_ENDPOINT`: Service endpoint URL for module 21 (required, no default) +- `MODULE_21_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_21_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_21_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_21_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 21 tests with: `npm run test:module-21` +Integration tests require the staging environment to be running. + + +## Section 22: Module Configuration 22 + +This section provides comprehensive documentation for module 22 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_22_ENDPOINT`: Service endpoint URL for module 22 (required, no default) +- `MODULE_22_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_22_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_22_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_22_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 22 tests with: `npm run test:module-22` +Integration tests require the staging environment to be running. + + +## Section 23: Module Configuration 23 + +This section provides comprehensive documentation for module 23 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_23_ENDPOINT`: Service endpoint URL for module 23 (required, no default) +- `MODULE_23_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_23_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_23_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_23_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 23 tests with: `npm run test:module-23` +Integration tests require the staging environment to be running. + + +## Section 24: Module Configuration 24 + +This section provides comprehensive documentation for module 24 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_24_ENDPOINT`: Service endpoint URL for module 24 (required, no default) +- `MODULE_24_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_24_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_24_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_24_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 24 tests with: `npm run test:module-24` +Integration tests require the staging environment to be running. + + +## Section 25: Module Configuration 25 + +This section provides comprehensive documentation for module 25 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_25_ENDPOINT`: Service endpoint URL for module 25 (required, no default) +- `MODULE_25_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_25_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_25_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_25_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 25 tests with: `npm run test:module-25` +Integration tests require the staging environment to be running. + + +## Section 26: Module Configuration 26 + +This section provides comprehensive documentation for module 26 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_26_ENDPOINT`: Service endpoint URL for module 26 (required, no default) +- `MODULE_26_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_26_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_26_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_26_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 26 tests with: `npm run test:module-26` +Integration tests require the staging environment to be running. + + +## Section 27: Module Configuration 27 + +This section provides comprehensive documentation for module 27 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_27_ENDPOINT`: Service endpoint URL for module 27 (required, no default) +- `MODULE_27_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_27_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_27_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_27_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 27 tests with: `npm run test:module-27` +Integration tests require the staging environment to be running. + + +## Section 28: Module Configuration 28 + +This section provides comprehensive documentation for module 28 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_28_ENDPOINT`: Service endpoint URL for module 28 (required, no default) +- `MODULE_28_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_28_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_28_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_28_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 28 tests with: `npm run test:module-28` +Integration tests require the staging environment to be running. + + +## Section 29: Module Configuration 29 + +This section provides comprehensive documentation for module 29 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_29_ENDPOINT`: Service endpoint URL for module 29 (required, no default) +- `MODULE_29_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_29_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_29_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_29_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 29 tests with: `npm run test:module-29` +Integration tests require the staging environment to be running. + + +## Section 30: Module Configuration 30 + +This section provides comprehensive documentation for module 30 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_30_ENDPOINT`: Service endpoint URL for module 30 (required, no default) +- `MODULE_30_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_30_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_30_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_30_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 30 tests with: `npm run test:module-30` +Integration tests require the staging environment to be running. + + +## Section 31: Module Configuration 31 + +This section provides comprehensive documentation for module 31 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_31_ENDPOINT`: Service endpoint URL for module 31 (required, no default) +- `MODULE_31_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_31_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_31_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_31_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 31 tests with: `npm run test:module-31` +Integration tests require the staging environment to be running. + + +## Section 32: Module Configuration 32 + +This section provides comprehensive documentation for module 32 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_32_ENDPOINT`: Service endpoint URL for module 32 (required, no default) +- `MODULE_32_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_32_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_32_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_32_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 32 tests with: `npm run test:module-32` +Integration tests require the staging environment to be running. + + +## Section 33: Module Configuration 33 + +This section provides comprehensive documentation for module 33 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_33_ENDPOINT`: Service endpoint URL for module 33 (required, no default) +- `MODULE_33_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_33_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_33_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_33_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 33 tests with: `npm run test:module-33` +Integration tests require the staging environment to be running. + + +## Section 34: Module Configuration 34 + +This section provides comprehensive documentation for module 34 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_34_ENDPOINT`: Service endpoint URL for module 34 (required, no default) +- `MODULE_34_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_34_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_34_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_34_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 34 tests with: `npm run test:module-34` +Integration tests require the staging environment to be running. + + +## Section 35: Module Configuration 35 + +This section provides comprehensive documentation for module 35 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_35_ENDPOINT`: Service endpoint URL for module 35 (required, no default) +- `MODULE_35_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_35_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_35_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_35_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 35 tests with: `npm run test:module-35` +Integration tests require the staging environment to be running. + + +## Section 36: Module Configuration 36 + +This section provides comprehensive documentation for module 36 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_36_ENDPOINT`: Service endpoint URL for module 36 (required, no default) +- `MODULE_36_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_36_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_36_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_36_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 36 tests with: `npm run test:module-36` +Integration tests require the staging environment to be running. + + +## Section 37: Module Configuration 37 + +This section provides comprehensive documentation for module 37 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_37_ENDPOINT`: Service endpoint URL for module 37 (required, no default) +- `MODULE_37_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_37_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_37_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_37_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 37 tests with: `npm run test:module-37` +Integration tests require the staging environment to be running. + + +## Section 38: Module Configuration 38 + +This section provides comprehensive documentation for module 38 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_38_ENDPOINT`: Service endpoint URL for module 38 (required, no default) +- `MODULE_38_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_38_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_38_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_38_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 38 tests with: `npm run test:module-38` +Integration tests require the staging environment to be running. + + +## Section 39: Module Configuration 39 + +This section provides comprehensive documentation for module 39 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_39_ENDPOINT`: Service endpoint URL for module 39 (required, no default) +- `MODULE_39_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_39_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_39_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_39_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 39 tests with: `npm run test:module-39` +Integration tests require the staging environment to be running. + + +## Section 40: Module Configuration 40 + +This section provides comprehensive documentation for module 40 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_40_ENDPOINT`: Service endpoint URL for module 40 (required, no default) +- `MODULE_40_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_40_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_40_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_40_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 40 tests with: `npm run test:module-40` +Integration tests require the staging environment to be running. + + +## Section 41: Module Configuration 41 + +This section provides comprehensive documentation for module 41 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_41_ENDPOINT`: Service endpoint URL for module 41 (required, no default) +- `MODULE_41_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_41_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_41_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_41_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 41 tests with: `npm run test:module-41` +Integration tests require the staging environment to be running. + + +## Section 42: Module Configuration 42 + +This section provides comprehensive documentation for module 42 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_42_ENDPOINT`: Service endpoint URL for module 42 (required, no default) +- `MODULE_42_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_42_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_42_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_42_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 42 tests with: `npm run test:module-42` +Integration tests require the staging environment to be running. + + +## Section 43: Module Configuration 43 + +This section provides comprehensive documentation for module 43 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_43_ENDPOINT`: Service endpoint URL for module 43 (required, no default) +- `MODULE_43_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_43_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_43_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_43_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 43 tests with: `npm run test:module-43` +Integration tests require the staging environment to be running. + + +## Section 44: Module Configuration 44 + +This section provides comprehensive documentation for module 44 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_44_ENDPOINT`: Service endpoint URL for module 44 (required, no default) +- `MODULE_44_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_44_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_44_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_44_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 44 tests with: `npm run test:module-44` +Integration tests require the staging environment to be running. + + +## Section 45: Module Configuration 45 + +This section provides comprehensive documentation for module 45 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_45_ENDPOINT`: Service endpoint URL for module 45 (required, no default) +- `MODULE_45_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_45_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_45_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_45_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 45 tests with: `npm run test:module-45` +Integration tests require the staging environment to be running. + + +## Section 46: Module Configuration 46 + +This section provides comprehensive documentation for module 46 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_46_ENDPOINT`: Service endpoint URL for module 46 (required, no default) +- `MODULE_46_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_46_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_46_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_46_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 46 tests with: `npm run test:module-46` +Integration tests require the staging environment to be running. + + +## Section 47: Module Configuration 47 + +This section provides comprehensive documentation for module 47 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_47_ENDPOINT`: Service endpoint URL for module 47 (required, no default) +- `MODULE_47_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_47_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_47_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_47_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 47 tests with: `npm run test:module-47` +Integration tests require the staging environment to be running. + + +## Section 48: Module Configuration 48 + +This section provides comprehensive documentation for module 48 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_48_ENDPOINT`: Service endpoint URL for module 48 (required, no default) +- `MODULE_48_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_48_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_48_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_48_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 48 tests with: `npm run test:module-48` +Integration tests require the staging environment to be running. + + +## Section 49: Module Configuration 49 + +This section provides comprehensive documentation for module 49 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_49_ENDPOINT`: Service endpoint URL for module 49 (required, no default) +- `MODULE_49_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_49_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_49_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_49_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 49 tests with: `npm run test:module-49` +Integration tests require the staging environment to be running. + + +## Section 50: Module Configuration 50 + +This section provides comprehensive documentation for module 50 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_50_ENDPOINT`: Service endpoint URL for module 50 (required, no default) +- `MODULE_50_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_50_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_50_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_50_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 50 tests with: `npm run test:module-50` +Integration tests require the staging environment to be running. + + +## Section 51: Module Configuration 51 + +This section provides comprehensive documentation for module 51 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_51_ENDPOINT`: Service endpoint URL for module 51 (required, no default) +- `MODULE_51_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_51_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_51_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_51_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 51 tests with: `npm run test:module-51` +Integration tests require the staging environment to be running. + + +## Section 52: Module Configuration 52 + +This section provides comprehensive documentation for module 52 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_52_ENDPOINT`: Service endpoint URL for module 52 (required, no default) +- `MODULE_52_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_52_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_52_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_52_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 52 tests with: `npm run test:module-52` +Integration tests require the staging environment to be running. + + +## Section 53: Module Configuration 53 + +This section provides comprehensive documentation for module 53 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_53_ENDPOINT`: Service endpoint URL for module 53 (required, no default) +- `MODULE_53_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_53_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_53_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_53_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 53 tests with: `npm run test:module-53` +Integration tests require the staging environment to be running. + + +## Section 54: Module Configuration 54 + +This section provides comprehensive documentation for module 54 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_54_ENDPOINT`: Service endpoint URL for module 54 (required, no default) +- `MODULE_54_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_54_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_54_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_54_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 54 tests with: `npm run test:module-54` +Integration tests require the staging environment to be running. + + +## Section 55: Module Configuration 55 + +This section provides comprehensive documentation for module 55 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_55_ENDPOINT`: Service endpoint URL for module 55 (required, no default) +- `MODULE_55_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_55_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_55_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_55_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 55 tests with: `npm run test:module-55` +Integration tests require the staging environment to be running. + + +## Section 56: Module Configuration 56 + +This section provides comprehensive documentation for module 56 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_56_ENDPOINT`: Service endpoint URL for module 56 (required, no default) +- `MODULE_56_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_56_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_56_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_56_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 56 tests with: `npm run test:module-56` +Integration tests require the staging environment to be running. + + +## Section 57: Module Configuration 57 + +This section provides comprehensive documentation for module 57 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_57_ENDPOINT`: Service endpoint URL for module 57 (required, no default) +- `MODULE_57_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_57_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_57_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_57_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 57 tests with: `npm run test:module-57` +Integration tests require the staging environment to be running. + + +## Section 58: Module Configuration 58 + +This section provides comprehensive documentation for module 58 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_58_ENDPOINT`: Service endpoint URL for module 58 (required, no default) +- `MODULE_58_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_58_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_58_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_58_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 58 tests with: `npm run test:module-58` +Integration tests require the staging environment to be running. + + +## Section 59: Module Configuration 59 + +This section provides comprehensive documentation for module 59 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_59_ENDPOINT`: Service endpoint URL for module 59 (required, no default) +- `MODULE_59_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_59_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_59_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_59_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 59 tests with: `npm run test:module-59` +Integration tests require the staging environment to be running. + + +## Section 60: Module Configuration 60 + +This section provides comprehensive documentation for module 60 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_60_ENDPOINT`: Service endpoint URL for module 60 (required, no default) +- `MODULE_60_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_60_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_60_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_60_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 60 tests with: `npm run test:module-60` +Integration tests require the staging environment to be running. + + +## Section 61: Module Configuration 61 + +This section provides comprehensive documentation for module 61 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_61_ENDPOINT`: Service endpoint URL for module 61 (required, no default) +- `MODULE_61_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_61_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_61_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_61_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 61 tests with: `npm run test:module-61` +Integration tests require the staging environment to be running. + + +## Section 62: Module Configuration 62 + +This section provides comprehensive documentation for module 62 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_62_ENDPOINT`: Service endpoint URL for module 62 (required, no default) +- `MODULE_62_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_62_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_62_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_62_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 62 tests with: `npm run test:module-62` +Integration tests require the staging environment to be running. + + +## Section 63: Module Configuration 63 + +This section provides comprehensive documentation for module 63 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_63_ENDPOINT`: Service endpoint URL for module 63 (required, no default) +- `MODULE_63_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_63_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_63_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_63_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 63 tests with: `npm run test:module-63` +Integration tests require the staging environment to be running. + + +## Section 64: Module Configuration 64 + +This section provides comprehensive documentation for module 64 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_64_ENDPOINT`: Service endpoint URL for module 64 (required, no default) +- `MODULE_64_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_64_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_64_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_64_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 64 tests with: `npm run test:module-64` +Integration tests require the staging environment to be running. + + +## Section 65: Module Configuration 65 + +This section provides comprehensive documentation for module 65 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_65_ENDPOINT`: Service endpoint URL for module 65 (required, no default) +- `MODULE_65_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_65_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_65_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_65_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 65 tests with: `npm run test:module-65` +Integration tests require the staging environment to be running. + + +## Section 66: Module Configuration 66 + +This section provides comprehensive documentation for module 66 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_66_ENDPOINT`: Service endpoint URL for module 66 (required, no default) +- `MODULE_66_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_66_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_66_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_66_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 66 tests with: `npm run test:module-66` +Integration tests require the staging environment to be running. + + +## Section 67: Module Configuration 67 + +This section provides comprehensive documentation for module 67 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_67_ENDPOINT`: Service endpoint URL for module 67 (required, no default) +- `MODULE_67_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_67_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_67_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_67_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 67 tests with: `npm run test:module-67` +Integration tests require the staging environment to be running. + + +## Section 68: Module Configuration 68 + +This section provides comprehensive documentation for module 68 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_68_ENDPOINT`: Service endpoint URL for module 68 (required, no default) +- `MODULE_68_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_68_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_68_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_68_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 68 tests with: `npm run test:module-68` +Integration tests require the staging environment to be running. + + +## Section 69: Module Configuration 69 + +This section provides comprehensive documentation for module 69 of the application. The module +handles critical business logic and must be configured according to the specifications below. +All developers working on this module should review these guidelines before making changes. +The configuration values listed here are validated at startup and incorrect values will prevent +the application from launching. Contact the platform team if you need to modify any defaults. + +### Configuration Keys + +- `MODULE_69_ENDPOINT`: Service endpoint URL for module 69 (required, no default) +- `MODULE_69_TIMEOUT_MS`: Request timeout in milliseconds (default: 5000) +- `MODULE_69_RETRY_COUNT`: Number of retry attempts for failed requests (default: 3) +- `MODULE_69_CACHE_TTL`: Cache time-to-live in seconds (default: 300) +- `MODULE_69_LOG_LEVEL`: Logging verbosity for this module (default: info) + +### Testing Guidelines + +Run module 69 tests with: `npm run test:module-69` +Integration tests require the staging environment to be running. + diff --git a/agents/codex/rules/skills-within-instruction-budget/tests/pass/AGENTS.md b/agents/codex/rules/skills-within-instruction-budget/tests/pass/AGENTS.md new file mode 100644 index 0000000..5a4a67c --- /dev/null +++ b/agents/codex/rules/skills-within-instruction-budget/tests/pass/AGENTS.md @@ -0,0 +1,12 @@ +# MyApp + +Compact instructions with skills. + +## Commands + +- `npm test` — run tests + +## Skills + +- deploy — deploy to staging +- test — run full test suite diff --git a/core/content/C1-core-sections/C1-core-sections.md b/core/content/C1-core-sections/C1-core-sections.md deleted file mode 100644 index 2f4468a..0000000 --- a/core/content/C1-core-sections/C1-core-sections.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -id: C1 -title: Core Sections -category: content -type: semantic -backed_by: - - source: claude-code-memory - claim: use-structure - - source: spec-writing-for-agents - claim: commands-early - - source: agents-md-spec - claim: root-placement - - source: agents-md-spec - claim: executable-commands - - source: agents-md-spec - claim: recommended-sections - - source: agents-md-spec - claim: no-required-fields - - source: using-claude-md-files - claim: usage-patterns - - source: claude-md-guide - claim: practical-examples - - source: claude-md-optimization-study - claim: optimization-improvement - - source: dometrain-claude-md-guide - claim: domain-terminology - - source: dometrain-claude-md-guide - claim: command-specificity - - source: osmani-ai-coding-workflow - claim: planning-before-coding -checks: - - id: C1-missing-sections - name: Large file missing core sections - severity: high - pattern_confidence: high -question: "Does this file have adequate coverage of project context?" -criteria: - - Files 100+ lines have Project/Stack/Commands/Constraints sections - - Section names may vary but concepts must be present - - Smaller files may omit sections if context is clear -sources: - - "https://claude.com/blog/using-claude-md-files" -see_also: [C3, S1] ---- - -# Core Sections - -Large instruction files include Project, Stack, Commands, Constraints. - -## Pattern - -**Good:** ## Stack, ## Commands, ## Constraints sections present -**Bad:** 150-line file with no organizational structure diff --git a/core/content/C1-core-sections/C1-core-sections.yml b/core/content/C1-core-sections/C1-core-sections.yml deleted file mode 100644 index ab93365..0000000 --- a/core/content/C1-core-sections/C1-core-sections.yml +++ /dev/null @@ -1,11 +0,0 @@ -rules: - - id: C1-missing-sections - message: "Large file may be missing core sections" - severity: WARNING - languages: [generic] - patterns: - - pattern-regex: "(?s)(?:[^\\n]*\\n){100,}" - - pattern-not-regex: "(?i)##?\\s*(stack|tech|commands?|scripts?|constraints?|rules)" - paths: - include: - - "{{main_instruction_file}}" diff --git a/core/content/C1-core-sections/tests/fail.md b/core/content/C1-core-sections/tests/fail.md deleted file mode 100644 index 7c3f8fd..0000000 --- a/core/content/C1-core-sections/tests/fail.md +++ /dev/null @@ -1,105 +0,0 @@ -# Test Document - -This file has over 100 lines but no core sections like Commands or Stack. - -## Introduction - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Details - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## More - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Extra - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Final - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Padding - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## More Padding - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Additional Padding - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. diff --git a/core/content/C1-core-sections/tests/pass.md b/core/content/C1-core-sections/tests/pass.md deleted file mode 100644 index 1c45fbf..0000000 --- a/core/content/C1-core-sections/tests/pass.md +++ /dev/null @@ -1,93 +0,0 @@ -# Test Document - -This file has over 100 lines with proper core sections. - -## Tech Stack - -- Node.js -- TypeScript - -## Commands - -- npm install -- npm test - -## Constraints - -- Follow code style - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Details - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## More - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Extra - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Final - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Padding - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. diff --git a/core/content/C2-single-source-of-truth/C2-single-source-of-truth.md b/core/content/C2-single-source-of-truth/C2-single-source-of-truth.md deleted file mode 100644 index 5385d7b..0000000 --- a/core/content/C2-single-source-of-truth/C2-single-source-of-truth.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -id: C2 -title: Single Source of Truth -category: content -type: semantic -backed_by: - - source: claude-code-memory - claim: keep-rules-focused - - source: dometrain-claude-md-guide - claim: duplicate-instruction-waste -checks: - - id: C2-duplicate-instruction - name: Duplicate instruction across files - severity: high - pattern_confidence: low -question: "Are instructions duplicated across multiple files?" -criteria: - - Same rule not stated in multiple locations - - References point to canonical source - - No conflicting versions of same instruction -sources: - - "https://code.claude.com/docs/en/memory" -see_also: [M2, S2] ---- - -# Single Source of Truth - -No duplicate instructions across files. - -## Pattern - -**Good:** "See @docs/testing.md for test conventions" -**Bad:** Same test rules in root file and docs/testing.md diff --git a/core/content/C2-single-source-of-truth/C2-single-source-of-truth.yml b/core/content/C2-single-source-of-truth/C2-single-source-of-truth.yml deleted file mode 100644 index 56d1578..0000000 --- a/core/content/C2-single-source-of-truth/C2-single-source-of-truth.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: C2-duplicate-instruction - message: "Potential duplicate instruction" - severity: WARNING - languages: [generic] - pattern-regex: "(?i)(NEVER|ALWAYS|MUST)\\s+[^\\n]{10,50}" - paths: - include: - - "{{instruction_files}}" diff --git a/core/content/C2-single-source-of-truth/tests/fail.md b/core/content/C2-single-source-of-truth/tests/fail.md deleted file mode 100644 index 1e3c8e2..0000000 --- a/core/content/C2-single-source-of-truth/tests/fail.md +++ /dev/null @@ -1,7 +0,0 @@ -# Test Document - -ALWAYS use TypeScript for new code. - -NEVER skip type checking. - -MUST run linter before commit. diff --git a/core/content/C2-single-source-of-truth/tests/pass.md b/core/content/C2-single-source-of-truth/tests/pass.md deleted file mode 100644 index 9d824d4..0000000 --- a/core/content/C2-single-source-of-truth/tests/pass.md +++ /dev/null @@ -1,5 +0,0 @@ -# Test Document - -Follow the coding guidelines. - -See @docs/style-guide.md for details. diff --git a/core/content/C3-has-project-description/C3-has-project-description.md b/core/content/C3-has-project-description/C3-has-project-description.md deleted file mode 100644 index 42d4200..0000000 --- a/core/content/C3-has-project-description/C3-has-project-description.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -id: C3 -title: Has Project Description -category: content -type: deterministic -backed_by: - - source: anthropic-teams-claude-code - claim: team-onboarding - - source: agents-md-spec - claim: recommended-sections - - source: agents-md-spec - claim: readme-for-agents - - source: using-claude-md-files - claim: usage-patterns - - source: dometrain-claude-md-guide - claim: domain-terminology -checks: - - id: C3-no-description - name: First line after title is empty - severity: medium - pattern_confidence: high -sources: - - "https://claude.com/blog/using-claude-md-files" -see_also: [C1, S4] ---- - -# Has Project Description - -First line after title is non-empty project description. - -## Pattern - -**Good:** "# MyApp\n\nA REST API for user management." -**Bad:** "# MyApp\n\n## Tech Stack" (no description) diff --git a/core/content/C3-has-project-description/C3-has-project-description.yml b/core/content/C3-has-project-description/C3-has-project-description.yml deleted file mode 100644 index 98cc734..0000000 --- a/core/content/C3-has-project-description/C3-has-project-description.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: C3-no-description - message: "First line after title is empty or heading" - severity: WARNING - languages: [generic] - pattern-regex: "^#\\s+[^\\n]+\\n\\s*\\n##" - paths: - include: - - "{{main_instruction_file}}" diff --git a/core/content/C3-has-project-description/tests/fail.md b/core/content/C3-has-project-description/tests/fail.md deleted file mode 100644 index 0d99484..0000000 --- a/core/content/C3-has-project-description/tests/fail.md +++ /dev/null @@ -1,5 +0,0 @@ -# Project Name - -## Getting Started - -Instructions here. diff --git a/core/content/C3-has-project-description/tests/pass.md b/core/content/C3-has-project-description/tests/pass.md deleted file mode 100644 index 89c3074..0000000 --- a/core/content/C3-has-project-description/tests/pass.md +++ /dev/null @@ -1,7 +0,0 @@ -# Project Name - -A brief description of what this project does and its purpose. - -## Getting Started - -Instructions here. diff --git a/core/content/C4-links-are-valid/C4-links-are-valid.md b/core/content/C4-links-are-valid/C4-links-are-valid.md deleted file mode 100644 index 9c2109d..0000000 --- a/core/content/C4-links-are-valid/C4-links-are-valid.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: C4 -title: Links Are Valid -category: content -type: semantic -backed_by: - - source: claude-code-memory - claim: imports-syntax -checks: - - id: C4-broken-import - name: "@import references non-existent file" - severity: high - pattern_confidence: very_high -question: "Do all @import references point to files that exist?" -criteria: - - Each @path/to/file reference resolves to an existing file - - Paths are relative to the project root - - Verify using filesystem, not text matching -sources: - - "https://code.claude.com/docs/en/memory" -see_also: [S2, M3] ---- - -# Links Are Valid - -All @imports and file references resolve to existing files. - -## Pattern - -**Good:** @docs/api.md where docs/api.md exists -**Bad:** @docs/old-api.md where file was deleted diff --git a/core/content/C4-links-are-valid/C4-links-are-valid.yml b/core/content/C4-links-are-valid/C4-links-are-valid.yml deleted file mode 100644 index 8730690..0000000 --- a/core/content/C4-links-are-valid/C4-links-are-valid.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: C4-broken-import - message: "@import reference to validate" - severity: WARNING - languages: [generic] - pattern-regex: "@[a-zA-Z0-9_/.-]+\\.(md|yml|yaml|json)" - paths: - include: - - "{{instruction_files}}" diff --git a/core/content/C4-links-are-valid/tests/fail.md b/core/content/C4-links-are-valid/tests/fail.md deleted file mode 100644 index 4c12875..0000000 --- a/core/content/C4-links-are-valid/tests/fail.md +++ /dev/null @@ -1,5 +0,0 @@ -# Test Document - -See @docs/nonexistent-file.md for details. - -Reference @config/missing.yml for settings. diff --git a/core/content/C4-links-are-valid/tests/pass.md b/core/content/C4-links-are-valid/tests/pass.md deleted file mode 100644 index f170fb3..0000000 --- a/core/content/C4-links-are-valid/tests/pass.md +++ /dev/null @@ -1,5 +0,0 @@ -# Test Document - -This file has no @import references to validate. - -All links are inline text without file references. diff --git a/core/content/C5-has-version-date/C5-has-version-date.md b/core/content/C5-has-version-date/C5-has-version-date.md deleted file mode 100644 index 910f2fd..0000000 --- a/core/content/C5-has-version-date/C5-has-version-date.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: C5 -title: Has Version/Date -category: content -type: deterministic -backed_by: - - source: claude-code-memory - claim: review-periodically -checks: - - id: C5-no-version - name: No version or date marker - severity: low - pattern_confidence: high -sources: - - "https://code.claude.com/docs/en/memory" -see_also: [M1, C1] ---- - -# Has Version/Date - -Root instruction file has version pattern or date in header. - -## Pattern - -**Good:** "<!-- Last updated: 2024-01-15 -->" or "v1.2.0" -**Bad:** No version tracking in file diff --git a/core/content/C5-has-version-date/C5-has-version-date.yml b/core/content/C5-has-version-date/C5-has-version-date.yml deleted file mode 100644 index d247d0d..0000000 --- a/core/content/C5-has-version-date/C5-has-version-date.yml +++ /dev/null @@ -1,11 +0,0 @@ -rules: - - id: C5-no-version - message: "No version or date marker found" - severity: WARNING - languages: [generic] - patterns: - - pattern-regex: "(?s)\\A#[\\s\\S]+" - - pattern-not-regex: "(?i)(v[0-9]+\\.[0-9]+|version|\\d{4}-\\d{2}-\\d{2}|last updated)" - paths: - include: - - "{{main_instruction_file}}" diff --git a/core/content/C5-has-version-date/tests/fail.md b/core/content/C5-has-version-date/tests/fail.md deleted file mode 100644 index 335d2bb..0000000 --- a/core/content/C5-has-version-date/tests/fail.md +++ /dev/null @@ -1,7 +0,0 @@ -# Test Document - -This markdown file has no date marker anywhere. - -## Section - -Some content here. diff --git a/core/content/C5-has-version-date/tests/pass.md b/core/content/C5-has-version-date/tests/pass.md deleted file mode 100644 index 82167e4..0000000 --- a/core/content/C5-has-version-date/tests/pass.md +++ /dev/null @@ -1,8 +0,0 @@ -# Test Document -<!-- Last updated: 2025-01-15 --> - -This file has a date marker so should not trigger. - -## Section - -More content. diff --git a/core/content/ask-not-guess/rule.md b/core/content/ask-not-guess/rule.md new file mode 100644 index 0000000..dd33965 --- /dev/null +++ b/core/content/ask-not-guess/rule.md @@ -0,0 +1,46 @@ +--- +id: "CORE:C:0022" +slug: ask-not-guess +title: Ask Not Guess +category: content +type: deterministic +level: L2 +backed_by: +- claude-code-issue-13579 +- osmani-ai-coding-workflow +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0022:check:0001" + type: deterministic + negate: true + severity: high +question: "Does this instruction file tell the agent to ask for clarification rather + than guessing?" +criteria: +- File contains a directive to ask, confirm, or clarify when context is missing + or ambiguous +- The directive contrasts asking with guessing, assuming, or inferring +- The directive is framed as a general workflow principle (not specific to one + scenario) +--- + +# Ask Not Guess + +Instruction files must include a directive for the agent to ask for clarification +rather than guessing when context is insufficient. + +## Pass / Fail + +**Pass:** "When unsure about requirements or design decisions, ask for clarification instead +of guessing. It's faster to ask one question than to redo an incorrect implementation." +**Fail:** An instruction file that describes the project thoroughly but contains no directive +about asking vs guessing. The agent encounters an ambiguous requirement and reads +50 files trying to infer the answer instead of asking the user. + +## Limitations + +Pattern-matches for keywords like "ask", "clarif", "instead of guessing", "when +unsure", "when unclear". May miss semantically equivalent instructions (e.g., "check +with me before making assumptions"). May false-positive on unrelated uses of "ask" +(e.g., "ask the API for a token"). Cannot verify that the directive is followed at +runtime. diff --git a/core/content/ask-not-guess/rule.yml b/core/content/ask-not-guess/rule.yml new file mode 100644 index 0000000..5eab2ff --- /dev/null +++ b/core/content/ask-not-guess/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0022.check.0001" + message: "Ask-when-uncertain instruction found" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(ask (the user|for clarification|before)|do not (assume|guess)|when (uncertain|unclear|ambiguous))" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/ask-not-guess/tests/fail/CLAUDE.md b/core/content/ask-not-guess/tests/fail/CLAUDE.md new file mode 100644 index 0000000..dc51673 --- /dev/null +++ b/core/content/ask-not-guess/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Collaborative development project. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Style + +Use 2-space indentation. diff --git a/core/content/ask-not-guess/tests/pass/CLAUDE.md b/core/content/ask-not-guess/tests/pass/CLAUDE.md new file mode 100644 index 0000000..dac7a13 --- /dev/null +++ b/core/content/ask-not-guess/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Collaborative development project. + +## Process + +When requirements are ambiguous, ask the user before proceeding. +Do not assume or guess when uncertain about the intended behavior. + +## Commands + +- `npm test` — run tests diff --git a/core/content/explain-reasoning/rule.md b/core/content/explain-reasoning/rule.md new file mode 100644 index 0000000..503e573 --- /dev/null +++ b/core/content/explain-reasoning/rule.md @@ -0,0 +1,46 @@ +--- +id: "CORE:C:0023" +slug: explain-reasoning +title: Explain Reasoning +category: content +type: deterministic +level: L2 +backed_by: +- osmani-ai-coding-workflow +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0023:check:0001" + type: deterministic + negate: true + severity: high +question: "Does this instruction file tell the agent to explain its reasoning when + making changes?" +criteria: +- File contains a directive to explain, document, or describe reasoning behind + changes +- The directive applies to code changes, bug fixes, or architectural decisions + (not just documentation tasks) +- The directive asks for the "why" (root cause, tradeoffs) not just the "what" + (description of change) +--- + +# Explain Reasoning + +Instruction files must include a directive for the agent to explain its reasoning +or changes. + +## Pass / Fail + +**Pass:** "When fixing bugs, briefly explain the root cause and why this fix works. When +making architectural decisions, document the tradeoffs considered." +**Fail:** An instruction file that describes coding standards and testing requirements but +contains no directive about explaining reasoning. The agent silently changes a +function signature without explaining why the original was wrong. + +## Limitations + +Pattern-matches for keywords like "explain", "reasoning", "why", "document", +"comment", "describe". May miss semantically equivalent phrasing (e.g., "show your +work"). May false-positive on unrelated uses of "explain" (e.g., "explain the API +to new developers" as a documentation task). Cannot assess whether the agent actually +follows the directive. diff --git a/core/content/explain-reasoning/rule.yml b/core/content/explain-reasoning/rule.yml new file mode 100644 index 0000000..14a452c --- /dev/null +++ b/core/content/explain-reasoning/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0023.check.0001" + message: "Explain-reasoning instruction found" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(explain|reasoning|rationale|why .+ chose|comment explaining|document .+ decision)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/explain-reasoning/tests/fail/CLAUDE.md b/core/content/explain-reasoning/tests/fail/CLAUDE.md new file mode 100644 index 0000000..584b243 --- /dev/null +++ b/core/content/explain-reasoning/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Code review focused project. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +Code is in src/ directory. diff --git a/core/content/explain-reasoning/tests/pass/CLAUDE.md b/core/content/explain-reasoning/tests/pass/CLAUDE.md new file mode 100644 index 0000000..e13fc90 --- /dev/null +++ b/core/content/explain-reasoning/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Code review focused project. + +## Process + +When fixing a bug, add a brief comment explaining the root cause and why this fix was chosen. +Document the reasoning behind architectural decisions in commit messages. + +## Commands + +- `npm test` — run tests diff --git a/core/content/has-boundaries/rule.md b/core/content/has-boundaries/rule.md new file mode 100644 index 0000000..fd36613 --- /dev/null +++ b/core/content/has-boundaries/rule.md @@ -0,0 +1,53 @@ +--- +id: "CORE:C:0005" +slug: has-boundaries +title: Has Boundaries +category: content +type: deterministic +level: L2 +backed_by: +- claude-code-settings +- osmani-ai-coding-workflow +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0005:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files define boundaries or prohibitions for the agent?" +criteria: +- At least one instruction file contains explicit prohibitions or off-limits + declarations +- Boundaries use imperative language (never, must not, do not) or equivalent + constraint syntax +- At least one boundary addresses files, directories, or operations the agent + must avoid +--- + +# Has Boundaries + +The instruction files must define boundaries specifying what the agent should never do +or never touch. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Constraints +- NEVER modify files in vendor/ or node_modules/ +- NEVER push directly to main +- NEVER commit .env files or credentials +- Ask before deleting any file +``` +Clear prohibitions that prevent the agent from causing damage. +**Fail:** The instruction file documents commands and project structure but includes no constraints, +prohibitions, or off-limits areas. The agent has no guardrails preventing it from modifying +generated code, pushing to production branches, or touching sensitive configuration. + +## Limitations + +Cannot verify that boundaries are comprehensive enough for the project's risk profile. +A project with database access that only restricts file modifications would pass despite +missing critical operational boundaries. Cannot detect boundaries that are too restrictive +and would prevent the agent from doing useful work. diff --git a/core/content/has-boundaries/rule.yml b/core/content/has-boundaries/rule.yml new file mode 100644 index 0000000..f0210fb --- /dev/null +++ b/core/content/has-boundaries/rule.yml @@ -0,0 +1,12 @@ +rules: + - id: "CORE.C.0005.check.0001" + message: "Boundary constraints documented" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)(never modify|never edit|never touch|do not modify)" + - pattern-regex: "(?i)off.limits" + - pattern-regex: "(?i)## (boundaries|constraints)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-boundaries/tests/fail/CLAUDE.md b/core/content/has-boundaries/tests/fail/CLAUDE.md new file mode 100644 index 0000000..2e0f9cc --- /dev/null +++ b/core/content/has-boundaries/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Financial services API. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Style + +Use TypeScript strict mode. diff --git a/core/content/has-boundaries/tests/pass/CLAUDE.md b/core/content/has-boundaries/tests/pass/CLAUDE.md new file mode 100644 index 0000000..8f487fb --- /dev/null +++ b/core/content/has-boundaries/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Financial services API. + +## Boundaries + +Never modify: .env, vendor/, production.config.js +Never edit migration files after they have been applied. + +## Commands + +- `npm test` — run tests diff --git a/core/content/has-commands/rule.md b/core/content/has-commands/rule.md new file mode 100644 index 0000000..b3c9ea5 --- /dev/null +++ b/core/content/has-commands/rule.md @@ -0,0 +1,54 @@ +--- +id: "CORE:C:0003" +slug: has-commands +title: Has Commands +category: content +type: deterministic +level: L2 +backed_by: +- claude-md-optimization-study +- dometrain-claude-md-guide +- instruction-limits-principles +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0003:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files include runnable project commands with full syntax?" +criteria: +- At least one instruction file contains executable command strings (not just + tool names) +- Commands include flags or parameters where applicable (not bare command names + like `npm test`) +- At least two distinct commands are documented +--- + +# Has Commands + +The instruction files must include commonly-used project commands with full invocation +syntax including flags and parameters. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Commands +npm run test -- --coverage +npm run lint -- --fix +docker compose up -d +``` +Commands are complete with flags and ready to copy-paste into a terminal. +**Fail:** The instruction file has no commands section. Or it lists tool names without invocation +syntax: +``` +We use npm for testing and docker for deployment. +``` +The agent cannot execute anything from this. + +## Limitations + +Cannot verify that documented commands are valid or currently functional. Cannot assess +whether the command set covers the right subset of commonly-used operations versus being +exhaustive or too sparse. Cannot detect commands that are missing critical flags. diff --git a/core/content/has-commands/rule.yml b/core/content/has-commands/rule.yml new file mode 100644 index 0000000..8238bae --- /dev/null +++ b/core/content/has-commands/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0003.check.0001" + message: "Executable commands found in instruction file" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "`[a-z]+ .+`" + - pattern-regex: "\\$ [a-z]+" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-commands/tests/fail/CLAUDE.md b/core/content/has-commands/tests/fail/CLAUDE.md new file mode 100644 index 0000000..8aa4ff6 --- /dev/null +++ b/core/content/has-commands/tests/fail/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +API service built with Express. + +## Getting Started + +Use pytest for testing. Build with npm. Deploy using Docker. diff --git a/core/content/has-commands/tests/pass/CLAUDE.md b/core/content/has-commands/tests/pass/CLAUDE.md new file mode 100644 index 0000000..0f6706e --- /dev/null +++ b/core/content/has-commands/tests/pass/CLAUDE.md @@ -0,0 +1,9 @@ +# MyApp + +API service built with Express. + +## Commands + +- `pytest tests/ -v --cov=src` — run tests with coverage +- `npm run build -- --mode production` — production build +- `docker compose up -d` — start services diff --git a/core/content/has-constraints-and-pitfalls/rule.md b/core/content/has-constraints-and-pitfalls/rule.md new file mode 100644 index 0000000..2a628ad --- /dev/null +++ b/core/content/has-constraints-and-pitfalls/rule.md @@ -0,0 +1,54 @@ +--- +id: "CORE:C:0010" +slug: has-constraints-and-pitfalls +title: Has Constraints and Pitfalls +category: content +type: deterministic +level: L2 +backed_by: +- claude-md-optimization-study +- osmani-ai-coding-workflow +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0010:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files document project-specific pitfalls, constraints, + or anti-patterns?" +criteria: +- At least one instruction file describes a known pitfall, technical constraint, + or approach to avoid +- Pitfalls are project-specific (reference specific libraries, APIs, or codebase + patterns) +- At least one pitfall includes the correct alternative approach or workaround +--- + +# Has Constraints and Pitfalls + +The instruction files must describe project-specific constraints, known pitfalls, or +approaches to avoid. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Pitfalls +- The ORM does not support nested transactions. Always use `db.begin_nested()` for + savepoints instead of nested `db.begin()` calls. +- The Redis client silently reconnects on timeout. Always check `client.connected` + before assuming a failed operation truly failed. +- NEVER use `datetime.now()` -- always use `datetime.utcnow()` or the project's + `get_current_time()` helper which respects timezone configuration. +``` +Each pitfall is specific, explains the problem, and gives the correct approach. +**Fail:** The instruction file documents commands, structure, and style conventions but has no +mention of things to avoid, known issues, gotchas, or anti-patterns. The agent has no +way to avoid known mistakes without discovering them through trial and error. + +## Limitations + +Cannot verify that documented pitfalls are still relevant or accurate. A pitfall fixed +three versions ago would still pass. Cannot assess whether the pitfall set is complete +for the project's complexity. Cannot distinguish between genuine project pitfalls and +generic programming advice. diff --git a/core/content/has-constraints-and-pitfalls/rule.yml b/core/content/has-constraints-and-pitfalls/rule.yml new file mode 100644 index 0000000..f3984e7 --- /dev/null +++ b/core/content/has-constraints-and-pitfalls/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0010.check.0001" + message: "Constraint or pitfall documentation found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## (constraint|pitfall|caveat|gotcha)" + - pattern-regex: "(?i)(avoid|watch out|be careful|known issue)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-constraints-and-pitfalls/tests/fail/CLAUDE.md b/core/content/has-constraints-and-pitfalls/tests/fail/CLAUDE.md new file mode 100644 index 0000000..efe3749 --- /dev/null +++ b/core/content/has-constraints-and-pitfalls/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Data processing pipeline. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +Source code is in the src/ directory. diff --git a/core/content/has-constraints-and-pitfalls/tests/pass/CLAUDE.md b/core/content/has-constraints-and-pitfalls/tests/pass/CLAUDE.md new file mode 100644 index 0000000..0510719 --- /dev/null +++ b/core/content/has-constraints-and-pitfalls/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Data processing pipeline. + +## Pitfalls + +The ORM silently truncates strings over 255 chars — always validate length before saving. +Avoid using raw SQL outside the `queries/` directory. + +## Commands + +- `npm test` — run tests diff --git a/core/content/has-domain-terminology/rule.md b/core/content/has-domain-terminology/rule.md new file mode 100644 index 0000000..136d366 --- /dev/null +++ b/core/content/has-domain-terminology/rule.md @@ -0,0 +1,57 @@ +--- +id: "CORE:C:0012" +slug: has-domain-terminology +title: Has Domain Terminology +category: content +type: deterministic +level: L2 +backed_by: +- claude-md-optimization-study +- dometrain-claude-md-guide +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0012:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files define project-specific terminology or acronyms?" +criteria: +- At least one instruction file defines domain-specific terms, acronyms, or + business concepts +- Definitions include enough context to use the term correctly (not just + expanding an acronym) +- At least two terms are defined +--- + +# Has Domain Terminology + +The instruction files must define domain-specific terminology, acronyms, or business +concepts used in the project. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Terminology +- PDP: Product Detail Page -- the main page displaying a single product +- SKU: Stock Keeping Unit -- unique identifier for a purchasable product variant +- Fulfillment: the process of picking, packing, and shipping an order from warehouse + to customer delivery +- Cart abandonment: when a user adds items to cart but does not complete checkout +``` +Each term is defined with enough context for the agent to use it correctly. +**Fail:** The instruction file uses acronyms and domain terms throughout: +``` +The PDP component fetches SKU data from the fulfillment API. Handle cart +abandonment events in the analytics pipeline. +``` +But never defines PDP, SKU, fulfillment, or cart abandonment. The agent must guess +what these terms mean. + +## Limitations + +Cannot verify that defined terms are used consistently throughout the codebase. Cannot +detect domain terms that are used in the codebase but missing from the glossary. Cannot +assess whether definitions are accurate for the project's business domain. Projects with +no domain-specific terminology (pure infrastructure, for example) may legitimately lack +this section. diff --git a/core/content/has-domain-terminology/rule.yml b/core/content/has-domain-terminology/rule.yml new file mode 100644 index 0000000..0a10f10 --- /dev/null +++ b/core/content/has-domain-terminology/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0012.check.0001" + message: "Terminology or definition content found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## (terminology|glossary|definition)" + - pattern-regex: "[A-Z]{2,}\\s*[=:—–-]" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-domain-terminology/tests/fail/CLAUDE.md b/core/content/has-domain-terminology/tests/fail/CLAUDE.md new file mode 100644 index 0000000..6008b72 --- /dev/null +++ b/core/content/has-domain-terminology/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +E-commerce platform. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +Source in src/, tests in tests/. diff --git a/core/content/has-domain-terminology/tests/pass/CLAUDE.md b/core/content/has-domain-terminology/tests/pass/CLAUDE.md new file mode 100644 index 0000000..8d064ae --- /dev/null +++ b/core/content/has-domain-terminology/tests/pass/CLAUDE.md @@ -0,0 +1,13 @@ +# MyApp + +E-commerce platform. + +## Terminology + +PDP = Product Detail Page +SKU = Stock Keeping Unit +Cart = in-memory shopping state (not persisted to database until checkout) + +## Commands + +- `npm test` — run tests diff --git a/core/content/has-project-description/rule.md b/core/content/has-project-description/rule.md new file mode 100644 index 0000000..b769ceb --- /dev/null +++ b/core/content/has-project-description/rule.md @@ -0,0 +1,56 @@ +--- +id: "CORE:C:0001" +slug: has-project-description +title: Has Project Description +category: content +type: deterministic +level: L1 +backed_by: +- claude-md-guide +- instruction-limits-principles +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0001:check:0001" + type: deterministic + severity: critical +question: "Does the instruction file contain a project description near the top?" +criteria: +- The first or second section after the title heading contains prose describing + the project +- The description includes at least one sentence about what the project is or + does +- The description appears before any commands, constraints, or configuration + sections +--- + +# Has Project Description + +The main instruction file must contain a project description within the first two sections +after the title heading. + +## Pass / Fail + +**Pass:** CLAUDE.md starts with: +``` +# MyProject +A REST API for inventory management built with FastAPI and PostgreSQL. +``` +The project description immediately follows the title, giving the agent enough context +to understand what the codebase does. +**Fail:** CLAUDE.md starts with: +``` +# CLAUDE.md + +## Commands +npm run build +npm run test +``` +Jumps straight to commands with no description of what the project is or does. + +## Limitations + +Cannot evaluate whether the description is accurate or sufficiently detailed for the +project's complexity. A one-word description like "A server" would pass the structural +check despite being nearly useless. Does not verify the description matches the actual +codebase contents. diff --git a/core/content/has-project-description/rule.yml b/core/content/has-project-description/rule.yml new file mode 100644 index 0000000..a396d75 --- /dev/null +++ b/core/content/has-project-description/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0001.check.0001" + message: "File opens with H2 instead of project description" + severity: ERROR + languages: [generic] + pattern-regex: "\\A## " + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-project-description/tests/fail/CLAUDE.md b/core/content/has-project-description/tests/fail/CLAUDE.md new file mode 100644 index 0000000..d6fd9e8 --- /dev/null +++ b/core/content/has-project-description/tests/fail/CLAUDE.md @@ -0,0 +1,9 @@ +## Commands + +git checkout -b feature/new-thing +npm install +npm test + +## Testing + +Run `pytest` for backend tests. diff --git a/core/content/has-project-description/tests/pass/CLAUDE.md b/core/content/has-project-description/tests/pass/CLAUDE.md new file mode 100644 index 0000000..f8731d7 --- /dev/null +++ b/core/content/has-project-description/tests/pass/CLAUDE.md @@ -0,0 +1,8 @@ +# MyApp + +Real-time collaboration platform built on WebSockets and React. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build diff --git a/core/content/has-project-structure/rule.md b/core/content/has-project-structure/rule.md new file mode 100644 index 0000000..4055016 --- /dev/null +++ b/core/content/has-project-structure/rule.md @@ -0,0 +1,51 @@ +--- +id: "CORE:C:0002" +slug: has-project-structure +title: Has Project Structure +category: content +type: deterministic +level: L2 +backed_by: +- claude-md-optimization-study +- dometrain-claude-md-guide +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0002:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files describe the project's directory layout or file + organization?" +criteria: +- At least one instruction file contains a section describing directory + structure or file organization +- The description maps directory or file paths to their purpose +- At least two directories or file locations are described +--- + +# Has Project Structure + +The instruction files must describe the project's directory structure or file organization. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Structure +src/ - Application source code +src/models/ - Database models +tests/ - Test suite (mirrors src/ layout) +docs/ - Project documentation +scripts/ - Build and deployment scripts +``` +Directories are listed with their purpose, giving the agent a map of the codebase. +**Fail:** The instruction file contains commands, style guides, and constraints but never mentions +where source code lives, where tests go, or how the repository is organized. The agent +must guess file placement from existing code. + +## Limitations + +Cannot verify the documented structure matches the actual filesystem. A stale structure +section that lists directories that no longer exist would still pass. Cannot assess +whether the structure description is complete enough for the project's complexity. diff --git a/core/content/has-project-structure/rule.yml b/core/content/has-project-structure/rule.yml new file mode 100644 index 0000000..7832e7a --- /dev/null +++ b/core/content/has-project-structure/rule.yml @@ -0,0 +1,12 @@ +rules: + - id: "CORE.C.0002.check.0001" + message: "Project structure documentation found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## (project )?structure" + - pattern-regex: "(?i)## director" + - pattern-regex: "src/|tests/|docs/" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-project-structure/tests/fail/CLAUDE.md b/core/content/has-project-structure/tests/fail/CLAUDE.md new file mode 100644 index 0000000..45927fe --- /dev/null +++ b/core/content/has-project-structure/tests/fail/CLAUDE.md @@ -0,0 +1,11 @@ +# MyApp + +E-commerce platform built with Django and React. + +## Style + +Use 2-space indentation for JavaScript files. + +## Deployment + +Deploy via CI/CD pipeline. diff --git a/core/content/has-project-structure/tests/pass/CLAUDE.md b/core/content/has-project-structure/tests/pass/CLAUDE.md new file mode 100644 index 0000000..02356f6 --- /dev/null +++ b/core/content/has-project-structure/tests/pass/CLAUDE.md @@ -0,0 +1,17 @@ +# MyApp + +E-commerce platform built with Django and React. + +## Structure + +``` +src/api/ # Django REST endpoints +src/models/ # Database models +src/web/ # React frontend +tests/ # Test suite +docs/ # Documentation +``` + +## Commands + +- `python manage.py test` — run tests diff --git a/core/content/has-style-conventions/rule.md b/core/content/has-style-conventions/rule.md new file mode 100644 index 0000000..46f54ae --- /dev/null +++ b/core/content/has-style-conventions/rule.md @@ -0,0 +1,60 @@ +--- +id: "CORE:C:0009" +slug: has-style-conventions +title: Has Style Conventions +category: content +type: deterministic +level: L2 +backed_by: +- claude-md-optimization-study +- dometrain-claude-md-guide +- osmani-ai-coding-workflow +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0009:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files describe coding style conventions beyond linter + scope?" +criteria: +- At least one instruction file describes naming patterns, architectural + preferences, or design conventions +- Conventions are project-specific (not generic advice like "use good names") +- At least two distinct convention topics are covered (e.g., naming and + architecture, or naming and patterns) +--- + +# Has Style Conventions + +The instruction files must describe coding style conventions such as naming patterns, +architectural preferences, or output examples. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Conventions +- Name React components PascalCase (e.g., UserProfileCard) +- Use custom hooks for shared state (useAuth, useCart) +- Prefer composition over inheritance +- Service functions return Result<T, Error>, never throw +- Example: + ```ts + export function getUser(id: string): Result<User, NotFoundError> { + // ... + } + ``` +``` +Covers naming, patterns, and includes a concrete example. +**Fail:** The instruction file documents commands and project structure but has no mention of +coding style, naming conventions, component patterns, or architectural preferences. +The agent must reverse-engineer conventions from existing code. + +## Limitations + +Cannot verify that documented conventions are consistently followed in the codebase. +A project claiming PascalCase components while having snake_case components everywhere +would still pass. Cannot assess whether the conventions are complete for the project's +technology stack. diff --git a/core/content/has-style-conventions/rule.yml b/core/content/has-style-conventions/rule.yml new file mode 100644 index 0000000..b90fc89 --- /dev/null +++ b/core/content/has-style-conventions/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0009.check.0001" + message: "Style convention content found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## (style|convention)" + - pattern-regex: "(?i)(naming|camelCase|PascalCase|snake_case)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-style-conventions/tests/fail/CLAUDE.md b/core/content/has-style-conventions/tests/fail/CLAUDE.md new file mode 100644 index 0000000..0c61608 --- /dev/null +++ b/core/content/has-style-conventions/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +React application with TypeScript. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Deployment + +Deploy via CI pipeline. diff --git a/core/content/has-style-conventions/tests/pass/CLAUDE.md b/core/content/has-style-conventions/tests/pass/CLAUDE.md new file mode 100644 index 0000000..77f1e7d --- /dev/null +++ b/core/content/has-style-conventions/tests/pass/CLAUDE.md @@ -0,0 +1,20 @@ +# MyApp + +React application with TypeScript. + +## Style Conventions + +Use camelCase for variables and functions. PascalCase for React components. +Prefix custom hooks with `use`. Name files after their default export. + +```tsx +// Example component structure +export function UserProfile({ userId }: Props) { + const user = useUser(userId); + return <ProfileCard user={user} />; +} +``` + +## Commands + +- `npm test` — run tests diff --git a/core/content/has-testing-conventions/rule.md b/core/content/has-testing-conventions/rule.md new file mode 100644 index 0000000..c110e4a --- /dev/null +++ b/core/content/has-testing-conventions/rule.md @@ -0,0 +1,52 @@ +--- +id: "CORE:C:0004" +slug: has-testing-conventions +title: Has Testing Conventions +category: content +type: deterministic +level: L2 +backed_by: +- claude-md-optimization-study +- osmani-ai-coding-workflow +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0004:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files describe testing conventions, test frameworks, + or how to run tests?" +criteria: +- At least one instruction file mentions a test framework, test runner, or test + execution command +- "Testing information includes at least one of: how to run tests, how to name test + files, or which framework to use" +- The testing content is specific to the project (not generic advice like "write + tests") +--- + +# Has Testing Conventions + +The instruction files must describe testing conventions, frameworks, or test execution +commands. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Testing +Run `pytest tests/` for unit tests. Name test files `test_*.py`. Each test +function should start with `test_`. Use fixtures from `conftest.py` for +database setup. +``` +Covers framework, execution command, naming convention, and shared fixtures. +**Fail:** The instruction file has commands and style guides but no mention of testing. The agent +does not know which test framework to use, how to name test files, or how to run the +test suite. + +## Limitations + +Cannot verify that described testing conventions match the actual test infrastructure. +A project claiming to use pytest while actually using unittest would still pass. Cannot +assess whether the conventions are complete enough for the project's test complexity. diff --git a/core/content/has-testing-conventions/rule.yml b/core/content/has-testing-conventions/rule.yml new file mode 100644 index 0000000..a9a3d48 --- /dev/null +++ b/core/content/has-testing-conventions/rule.yml @@ -0,0 +1,12 @@ +rules: + - id: "CORE.C.0004.check.0001" + message: "Testing conventions documented" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## test" + - pattern-regex: "(?i)(pytest|jest|vitest|mocha|unittest|rspec)" + - pattern-regex: "(test_\\*|\\*\\.test\\.|\\*\\.spec\\.)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-testing-conventions/tests/fail/CLAUDE.md b/core/content/has-testing-conventions/tests/fail/CLAUDE.md new file mode 100644 index 0000000..4910ab5 --- /dev/null +++ b/core/content/has-testing-conventions/tests/fail/CLAUDE.md @@ -0,0 +1,11 @@ +# MyApp + +Data processing pipeline. + +## Structure + +Pipeline stages are in the stages/ directory. + +## Deployment + +Deploy to production via CI. diff --git a/core/content/has-testing-conventions/tests/pass/CLAUDE.md b/core/content/has-testing-conventions/tests/pass/CLAUDE.md new file mode 100644 index 0000000..c0caa2f --- /dev/null +++ b/core/content/has-testing-conventions/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Data processing pipeline. + +## Testing + +Use pytest with test_*.py naming convention. +Run `pytest -x --tb=short` for fast feedback during development. + +## Commands + +- `pytest tests/` — run all tests diff --git a/core/content/has-workflow-instructions/rule.md b/core/content/has-workflow-instructions/rule.md new file mode 100644 index 0000000..eee07b9 --- /dev/null +++ b/core/content/has-workflow-instructions/rule.md @@ -0,0 +1,56 @@ +--- +id: "CORE:C:0011" +slug: has-workflow-instructions +title: Has Workflow Instructions +category: content +type: deterministic +level: L2 +backed_by: +- dometrain-claude-md-guide +- spec-writing-for-agents +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0011:check:0001" + type: deterministic + negate: true + severity: high +question: "Do the instruction files describe development workflows like branching, + review, or deployment?" +criteria: +- At least one instruction file describes a development workflow (branching, PR + process, deployment, or release) +- Workflows include concrete steps or conventions (not just "we use git") +- At least one workflow topic includes enough detail for the agent to follow it + independently +--- + +# Has Workflow Instructions + +The instruction files must describe development workflows such as branching, deployment, +or review processes. + +## Pass / Fail + +**Pass:** The instruction file contains: +``` +## Workflow +- Create feature branches from `develop` with prefix: `feat/`, `fix/`, `chore/` +- PR requires 1 approval before merge +- Squash merge to main +- Tag releases with `vX.Y.Z` format +- Run `make deploy-staging` to deploy to staging after merge +``` +Covers branching, review, merge strategy, and deployment. +**Fail:** The instruction file documents code conventions and commands but never mentions how to +branch, what the PR process is, how to deploy, or any development workflow. The agent +creates branches with arbitrary names and has no idea how to get code reviewed or +released. + +## Limitations + +Cannot verify that documented workflows match actual team practice. A project +documenting a PR-based workflow while actually committing directly to main would still +pass. Cannot assess whether workflows are complete for the project's deployment +complexity. Projects with no deployment (e.g., libraries) may legitimately have minimal +workflow documentation. diff --git a/core/content/has-workflow-instructions/rule.yml b/core/content/has-workflow-instructions/rule.yml new file mode 100644 index 0000000..e712ed4 --- /dev/null +++ b/core/content/has-workflow-instructions/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0011.check.0001" + message: "Workflow-related content found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## (workflow|process)" + - pattern-regex: "(?i)(branch|deploy|release|merge|PR|pull request)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/has-workflow-instructions/tests/fail/CLAUDE.md b/core/content/has-workflow-instructions/tests/fail/CLAUDE.md new file mode 100644 index 0000000..2cbc9ce --- /dev/null +++ b/core/content/has-workflow-instructions/tests/fail/CLAUDE.md @@ -0,0 +1,11 @@ +# MyApp + +SaaS platform. + +## Commands + +- `npm test` — run tests + +## Tech Stack + +Node.js 20, PostgreSQL 15, Redis 7. diff --git a/core/content/has-workflow-instructions/tests/pass/CLAUDE.md b/core/content/has-workflow-instructions/tests/pass/CLAUDE.md new file mode 100644 index 0000000..45877e1 --- /dev/null +++ b/core/content/has-workflow-instructions/tests/pass/CLAUDE.md @@ -0,0 +1,13 @@ +# MyApp + +SaaS platform. + +## Workflow + +Feature branches must follow `feature/JIRA-NNN` naming. +PRs require 2 approvals before merge to main. +Deploy to staging automatically on merge to develop. + +## Commands + +- `npm test` — run tests diff --git a/core/content/hierarchical-summary/rule.md b/core/content/hierarchical-summary/rule.md new file mode 100644 index 0000000..85ff3b3 --- /dev/null +++ b/core/content/hierarchical-summary/rule.md @@ -0,0 +1,53 @@ +--- +id: "CORE:C:0019" +slug: hierarchical-summary +title: Hierarchical Summary +category: content +type: semantic +level: L3 +backed_by: +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0019:check:0001" + type: deterministic + negate: true + severity: medium +- id: "CORE:C:0019:check:0002" + type: semantic + prompt: "Does the instruction file provide a hierarchical summary or table of contents for navigating the instruction system?" + severity: medium +question: "Does this instruction file include a summary or table of contents near + the top for quick orientation?" +criteria: +- File exceeding 100 lines contains a summary, overview, or table of contents + within the first 20 lines +- The summary references or links to detailed sections later in the file +- The summary covers the major topics addressed in the file (not just one + section) +- Files under 100 lines are exempt from this rule +--- + +# Hierarchical Summary + +Instruction files exceeding 100 lines must include a summary section or table of +contents near the top of the file. + +## Pass / Fail + +**Pass:** A 250-line CLAUDE.md opens with a 10-line summary: +"## Overview\n- Commands: build, test, lint (see ##Commands)\n- Structure: monorepo +with packages/ (see ##Structure)\n- Key constraints: ESM only, no require() +(see ##Constraints)\n- Testing: pytest with fixtures in tests/conftest.py +(see ##Testing)" +**Fail:** A 250-line CLAUDE.md jumps directly into a detailed `## Commands` section with no +overview, summary, or table of contents. The agent must read all 250 lines to +understand the file's scope before finding the relevant section. + +## Limitations + +Only applies to files exceeding 100 lines — short files are exempt. Cannot assess +whether the summary accurately reflects the file's content. A stale or incomplete +summary would pass the structural check. Cannot distinguish between a true summary +(condensed key points) and a table of contents (just section links) — both are +accepted as valid. diff --git a/core/content/hierarchical-summary/rule.yml b/core/content/hierarchical-summary/rule.yml new file mode 100644 index 0000000..4dc50c9 --- /dev/null +++ b/core/content/hierarchical-summary/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0019.check.0001" + message: "Navigation or summary content found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(?i)## (table of contents|contents|navigation|overview)" + - pattern-regex: "(?i)(see .+\\.md)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/hierarchical-summary/tests/fail/CLAUDE.md b/core/content/hierarchical-summary/tests/fail/CLAUDE.md new file mode 100644 index 0000000..d90b7f4 --- /dev/null +++ b/core/content/hierarchical-summary/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Large instruction system. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Style + +Use TypeScript strict mode. diff --git a/core/content/hierarchical-summary/tests/pass/CLAUDE.md b/core/content/hierarchical-summary/tests/pass/CLAUDE.md new file mode 100644 index 0000000..5467c84 --- /dev/null +++ b/core/content/hierarchical-summary/tests/pass/CLAUDE.md @@ -0,0 +1,14 @@ +# MyApp + +Large instruction system with navigation. + +## Overview + +- See @docs/api.md — API endpoint conventions and patterns +- See @docs/testing.md — test framework and fixture setup +- See @docs/deployment.md — CI/CD pipeline and release process +- See @docs/security.md — authentication and authorization rules + +## Commands + +- `npm test` — run tests diff --git a/core/content/persist-critical-constraints/rule.md b/core/content/persist-critical-constraints/rule.md new file mode 100644 index 0000000..2d9ff2b --- /dev/null +++ b/core/content/persist-critical-constraints/rule.md @@ -0,0 +1,52 @@ +--- +id: "CORE:C:0016" +slug: persist-critical-constraints +title: Persist Critical Constraints +category: content +type: semantic +level: L2 +backed_by: +- claude-code-issue-13579 +- claude-md-optimization-study +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0016:check:0001" + type: deterministic + negate: true + severity: medium +- id: "CORE:C:0016:check:0002" + type: semantic + prompt: "Are critical constraints and important directives persisted in the instruction file rather than only in conversation context?" + severity: medium +question: "Does this instruction file contain persistent, specific constraints rather + than relying on session memory for critical rules?" +criteria: +- File contains at least one explicit constraint or prohibition specific to the + project +- Constraints are stated as persistent directives (not conditional on session + context) +- Critical patterns are documented with enough detail to survive context + compaction (include the "why" not just the "what") +--- + +# Persist Critical Constraints + +Critical constraints and recurring correction patterns must be documented in the +instruction files, not left to session memory. + +## Pass / Fail + +**Pass:** "IMPORTANT: This project uses ESM modules only. Never use require() — it will fail +silently in production. Use `import` / `export` syntax exclusively." +The constraint is persisted in CLAUDE.md where it survives session compaction. +**Fail:** A developer repeatedly tells the agent "don't use require()" in chat messages across +multiple sessions, but the instruction file contains no mention of the ESM-only +constraint. After each compaction, the agent reverts to using require(). + +## Limitations + +Cannot detect what constraints are missing — only evaluates whether the file contains +the kind of persistent, specific constraints described. Cannot compare the instruction +file against chat history to find unpersisted corrections. Cannot distinguish between +a genuinely complete instruction file and one that is missing critical constraints the +author has not yet identified. diff --git a/core/content/persist-critical-constraints/rule.yml b/core/content/persist-critical-constraints/rule.yml new file mode 100644 index 0000000..4f85047 --- /dev/null +++ b/core/content/persist-critical-constraints/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0016.check.0001" + message: "Strong directive found in instruction file" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(NEVER|ALWAYS|MUST|CRITICAL|IMPORTANT)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/persist-critical-constraints/tests/fail/CLAUDE.md b/core/content/persist-critical-constraints/tests/fail/CLAUDE.md new file mode 100644 index 0000000..f977efd --- /dev/null +++ b/core/content/persist-critical-constraints/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Production API service. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +Code is in src/ directory. diff --git a/core/content/persist-critical-constraints/tests/pass/CLAUDE.md b/core/content/persist-critical-constraints/tests/pass/CLAUDE.md new file mode 100644 index 0000000..bc0d092 --- /dev/null +++ b/core/content/persist-critical-constraints/tests/pass/CLAUDE.md @@ -0,0 +1,13 @@ +# MyApp + +Production API service. + +## Critical Constraints + +NEVER modify the production database directly — use migrations only. +ALWAYS run `npm test` before pushing to ensure nothing is broken. +MUST use parameterized queries for all database operations. + +## Commands + +- `npm test` — run tests diff --git a/core/content/provides-pattern-examples/rule.md b/core/content/provides-pattern-examples/rule.md new file mode 100644 index 0000000..1af7929 --- /dev/null +++ b/core/content/provides-pattern-examples/rule.md @@ -0,0 +1,51 @@ +--- +id: "CORE:C:0025" +slug: provides-pattern-examples +title: Provides Pattern Examples +category: content +type: deterministic +level: L2 +backed_by: +- osmani-ai-coding-workflow +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0025:check:0001" + type: deterministic + negate: true + severity: high +question: "Does this instruction file include concrete examples of desired code patterns + from the project?" +criteria: +- File contains at least one code fence (```) or inline code example showing a + desired pattern +- Examples demonstrate project-specific patterns (component structure, naming, + API usage) not generic syntax +- Examples are presented as exemplary ("like this", "follow this pattern") not + just documentation of commands +- Prose descriptions of style without accompanying code examples do not satisfy + this rule +--- + +# Provides Pattern Examples + +Instruction files must include concrete examples of desired code patterns or output +formats from the project. + +## Pass / Fail + +**Pass:** "Example component:\n```tsx\nexport function UserCard({ user }: Props) {\n return +<Card title={user.name} />\n}\n```\nFollow this pattern for all new components: +named export, destructured props, single return." +**Fail:** "Follow the patterns used in the codebase. Components should be clean and follow +our conventions." — no actual examples of what those patterns or conventions look +like. + +## Limitations + +Pattern-matches for code fences (```), inline code backticks used as examples, or +phrases like "example", "pattern", "like this". May false-positive on code fences +used for non-exemplary purposes (e.g., documenting a command to run). Cannot assess +whether examples are representative of the codebase's actual style. Cannot +distinguish between exemplary patterns (good) and linter-enforceable formatting +rules (should use a linter instead, per conflict 0001). diff --git a/core/content/provides-pattern-examples/rule.yml b/core/content/provides-pattern-examples/rule.yml new file mode 100644 index 0000000..49303c2 --- /dev/null +++ b/core/content/provides-pattern-examples/rule.yml @@ -0,0 +1,12 @@ +rules: + - id: "CORE.C.0025.check.0001" + message: "Code example or file reference found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "```" + - pattern-regex: "src/[a-z]" + - pattern-regex: "see .+\\.[a-z]+:[0-9]" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/provides-pattern-examples/tests/fail/CLAUDE.md b/core/content/provides-pattern-examples/tests/fail/CLAUDE.md new file mode 100644 index 0000000..56fbe2b --- /dev/null +++ b/core/content/provides-pattern-examples/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +React application with established patterns. + +## Style + +Use functional components with hooks. Follow React best practices. +Keep components small and focused. + +## Commands + +- `npm test` — run tests diff --git a/core/content/provides-pattern-examples/tests/pass/CLAUDE.md b/core/content/provides-pattern-examples/tests/pass/CLAUDE.md new file mode 100644 index 0000000..03102e3 --- /dev/null +++ b/core/content/provides-pattern-examples/tests/pass/CLAUDE.md @@ -0,0 +1,17 @@ +# MyApp + +React application with established patterns. + +## Patterns + +New React components should follow this structure (see src/components/UserCard.tsx): + +```tsx +export function UserCard({ user }: Props) { + return <div className="card">{user.name}</div>; +} +``` + +## Commands + +- `npm test` — run tests diff --git a/core/content/repo-specific-content/rule.md b/core/content/repo-specific-content/rule.md new file mode 100644 index 0000000..fa11e4f --- /dev/null +++ b/core/content/repo-specific-content/rule.md @@ -0,0 +1,55 @@ +--- +id: "CORE:C:0017" +slug: repo-specific-content +title: Repo-Specific Content +category: content +type: semantic +level: L2 +backed_by: +- claude-md-optimization-study +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0017:check:0001" + type: deterministic + negate: true + severity: medium +- id: "CORE:C:0017:check:0002" + type: semantic + prompt: "Does the instruction file contain content specific to this repository rather than generic advice?" + severity: medium +question: "Does this instruction file contain content that is specific to its repository + rather than generic advice?" +criteria: +- File references specific file paths, module names, or API endpoints from the + project +- Constraints address real problems encountered in this repository (not + theoretical concerns) +- Generic programming advice (SOLID, clean code, meaningful names) is absent or + minimal +- Instructions would not make sense if copy-pasted into a different repository + without modification +--- + +# Repo-Specific Content + +Instruction file content must be specific to the repository rather than generic +advice applicable to any project. + +## Pass / Fail + +**Pass:** "This project uses a custom ORM wrapper in `lib/db.ts`. Always use `db.query()` +instead of raw SQL. The wrapper handles connection pooling and parameter escaping." +References a specific file, a specific API, and a specific reason. +**Fail:** "Write clean, maintainable code. Follow SOLID principles. Use meaningful variable +names. Keep functions short and focused." — this advice applies to every project +and provides no repo-specific value. + +## Limitations + +Requires semantic judgment — an LLM must assess whether content is repo-specific +or generic. Some instruction files legitimately contain a mix of both (e.g., a +project-specific section plus a brief general coding standard). Cannot verify that +referenced files or paths actually exist in the repository. Cannot detect generic +advice that has been superficially personalized (e.g., "In this project, write +clean code"). diff --git a/core/content/repo-specific-content/rule.yml b/core/content/repo-specific-content/rule.yml new file mode 100644 index 0000000..e4110a0 --- /dev/null +++ b/core/content/repo-specific-content/rule.yml @@ -0,0 +1,11 @@ +rules: + - id: "CORE.C.0017.check.0001" + message: "Project-specific path reference found" + severity: WARNING + languages: [generic] + pattern-either: + - pattern-regex: "(src/|tests/|lib/|app/)" + - pattern-regex: "(\\./|\\.\\w+rc|package\\.json|Makefile|Dockerfile)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/repo-specific-content/tests/fail/CLAUDE.md b/core/content/repo-specific-content/tests/fail/CLAUDE.md new file mode 100644 index 0000000..6f39d84 --- /dev/null +++ b/core/content/repo-specific-content/tests/fail/CLAUDE.md @@ -0,0 +1,5 @@ +# MyApp + +Write clean, maintainable code and follow best practices. +Use meaningful variable names and keep functions short. +Follow SOLID principles and write comprehensive tests. diff --git a/core/content/repo-specific-content/tests/pass/CLAUDE.md b/core/content/repo-specific-content/tests/pass/CLAUDE.md new file mode 100644 index 0000000..ed4d73f --- /dev/null +++ b/core/content/repo-specific-content/tests/pass/CLAUDE.md @@ -0,0 +1,16 @@ +# MyApp + +Our API uses the repository pattern in src/repos/. New endpoints must follow the existing UserRepo structure in src/repos/user.ts. + +## Commands + +- `pytest tests/ -v --cov=src` — run tests with coverage +- `npm run build` — production build via Dockerfile + +## Structure + +``` +src/repos/ # Repository pattern implementations +src/api/ # Express route handlers +tests/unit/ # Unit tests matching src/ structure +``` diff --git a/core/content/specificity-over-vagueness/rule.md b/core/content/specificity-over-vagueness/rule.md new file mode 100644 index 0000000..7bf22c2 --- /dev/null +++ b/core/content/specificity-over-vagueness/rule.md @@ -0,0 +1,62 @@ +--- +id: "CORE:C:0006" +slug: specificity-over-vagueness +title: Specificity Over Vagueness +category: content +type: semantic +level: L2 +backed_by: +- claude-code-memory +- spec-writing-for-agents +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0006:check:0001" + type: deterministic + severity: medium +- id: "CORE:C:0006:check:0002" + type: semantic + prompt: "Are the instructions specific and actionable, avoiding vague qualifiers like 'properly', 'well', 'clean'?" + severity: medium +question: "Are the instructions in the file specific and actionable rather than vague?" +criteria: +- Instructions reference concrete values, paths, commands, or patterns rather + than abstract qualities +- Directives are testable -- an observer could determine whether the agent + followed them +- The file does not contain platitudes like "write clean code" or "follow best + practices" as standalone instructions +--- + +# Specificity Over Vagueness + +Instructions must be specific and actionable rather than vague or generic. + +## Pass / Fail + +**Pass:** The instruction file contains specific, actionable directives: +``` +- Use 2-space indentation for TypeScript files +- Always run `npm test` before committing +- Name database migration files with timestamp prefix: `YYYYMMDD_HHMMSS_description.sql` +- Error responses must use the ApiError class from src/errors.ts +``` +Each instruction tells the agent exactly what to do with no ambiguity. +**Fail:** The instruction file contains vague, unactionable guidance: +``` +- Write clean code +- Follow best practices +- Format code properly +- Keep things simple +- Use good naming conventions +``` +None of these tell the agent what to actually do. "Clean code" and "best practices" +are subjective and produce inconsistent behavior. + +## Limitations + +Specificity exists on a spectrum. Some instructions are partially specific ("use +meaningful variable names" is more specific than "write clean code" but less specific +than "prefix boolean variables with is/has/should"). The semantic gate must make a +judgment call on borderline cases. Cannot assess whether specific instructions are +correct or appropriate for the project. diff --git a/core/content/specificity-over-vagueness/rule.yml b/core/content/specificity-over-vagueness/rule.yml new file mode 100644 index 0000000..5418d20 --- /dev/null +++ b/core/content/specificity-over-vagueness/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0006.check.0001" + message: "Vague qualifier found in instruction" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)\\b(properly|well|clean|good|nicely|appropriate|correct)\\b" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/specificity-over-vagueness/tests/fail/CLAUDE.md b/core/content/specificity-over-vagueness/tests/fail/CLAUDE.md new file mode 100644 index 0000000..4f9c1b3 --- /dev/null +++ b/core/content/specificity-over-vagueness/tests/fail/CLAUDE.md @@ -0,0 +1,9 @@ +# MyApp + +A web application. + +## Guidelines + +Write clean code and follow good practices. +Format code properly and use appropriate naming. +Handle errors well and write good tests. diff --git a/core/content/specificity-over-vagueness/tests/pass/CLAUDE.md b/core/content/specificity-over-vagueness/tests/pass/CLAUDE.md new file mode 100644 index 0000000..c56ae58 --- /dev/null +++ b/core/content/specificity-over-vagueness/tests/pass/CLAUDE.md @@ -0,0 +1,13 @@ +# MyApp + +API service built with Express and TypeScript. + +## Commands + +- `npm test` — run tests with Jest +- `npm run build` — production build with esbuild + +## Style + +Use 2-space indentation for TypeScript files. +Name test files `*.test.ts` in the `tests/` directory. diff --git a/core/content/structured-sections/rule.md b/core/content/structured-sections/rule.md new file mode 100644 index 0000000..d2630e3 --- /dev/null +++ b/core/content/structured-sections/rule.md @@ -0,0 +1,45 @@ +--- +id: "CORE:C:0015" +slug: structured-sections +title: Structured Sections +category: content +type: deterministic +level: L2 +backed_by: +- spec-writing-for-agents +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0015:check:0001" + type: deterministic + negate: true + severity: high +question: "Does this instruction file use Markdown headings to organize its content + into sections?" +criteria: +- File contains at least two Markdown headings (lines starting with ## or ###) +- No block of consecutive non-heading content exceeds 50 lines without a heading + break +- Headings use level 2 (##) or level 3 (###) — not level 1 (#) which is reserved + for the document title +--- + +# Structured Sections + +Instruction files must use Markdown headings (## or ###) to organize content into +distinct named sections. + +## Pass / Fail + +**Pass:** A CLAUDE.md file organized with `## Commands`, `## Structure`, `## Testing`, +`## Constraints` headings, each followed by relevant content for that topic. +**Fail:** A CLAUDE.md file that is a wall of text — 150 lines of instructions with no headings, +no section breaks, and no structural markers. All content runs together in a single +undifferentiated block. + +## Limitations + +Cannot assess whether headings are meaningful or well-chosen — only checks for their +presence. A file with headings like "## Section 1", "## Section 2" would pass despite +having non-descriptive section names. Does not check whether content is correctly +placed under its heading. Very short files (under 10 lines) may not need headings. diff --git a/core/content/structured-sections/rule.yml b/core/content/structured-sections/rule.yml new file mode 100644 index 0000000..aa6cac4 --- /dev/null +++ b/core/content/structured-sections/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0015.check.0001" + message: "Structured sections (## headings) found in instruction file" + severity: WARNING + languages: [generic] + pattern-regex: "^## " + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/structured-sections/tests/fail/CLAUDE.md b/core/content/structured-sections/tests/fail/CLAUDE.md new file mode 100644 index 0000000..f6c6103 --- /dev/null +++ b/core/content/structured-sections/tests/fail/CLAUDE.md @@ -0,0 +1,3 @@ +# MyApp + +This is a backend service for user management. It is built with Express and TypeScript. To run the tests you should use npm test and for building the production version use npm run build. The source code lives in the src directory and tests are in the tests directory. You should never commit env files and always run the linter before pushing code. The database uses PostgreSQL and migrations should be run with npm run migrate. diff --git a/core/content/structured-sections/tests/pass/CLAUDE.md b/core/content/structured-sections/tests/pass/CLAUDE.md new file mode 100644 index 0000000..1e49b5e --- /dev/null +++ b/core/content/structured-sections/tests/pass/CLAUDE.md @@ -0,0 +1,19 @@ +# MyApp + +Backend service for user management. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +``` +src/ # Application code +tests/ # Test suite +``` + +## Constraints + +- Never commit .env files diff --git a/core/content/universal-content-only/rule.md b/core/content/universal-content-only/rule.md new file mode 100644 index 0000000..ecc1385 --- /dev/null +++ b/core/content/universal-content-only/rule.md @@ -0,0 +1,67 @@ +--- +id: "CORE:C:0007" +slug: universal-content-only +title: Universal Content Only +category: content +type: semantic +level: L2 +backed_by: +- enterprise-claude-usage +- instruction-limits-principles +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:C:0007:check:0001" + type: deterministic + severity: medium +- id: "CORE:C:0007:check:0002" + type: semantic + prompt: "Does the main instruction file contain only universal content, or does it include domain-specific content that belongs in supplementary files?" + severity: medium +question: "Does the main instruction file contain only content relevant to most agent + tasks?" +criteria: +- The main instruction file focuses on project-wide conventions, commands, and + constraints +- Specialized or niche content is either absent from the main file or referenced + via imports +- The main file does not contain lengthy reference documentation for narrow use + cases +--- + +# Universal Content Only + +The main instruction file must contain only guidance that applies to the majority of +agent tasks. + +## Pass / Fail + +**Pass:** The main CLAUDE.md contains project-wide conventions (structure, commands, style, boundaries) +and imports specialized content: +``` +# MyProject +A REST API for order management. + +## Commands +npm run test -- --coverage +npm run build + +## Constraints +- NEVER modify generated files in src/generated/ + +See docs/api-setup.md for API gateway configuration. +See docs/database.md for migration procedures. +``` +Niche setup guides live in imported files, keeping the main file focused. +**Fail:** The main CLAUDE.md is 2000 lines long and includes detailed API documentation for a +rarely-used internal service, step-by-step database migration guides, historical +architecture decisions, and onboarding instructions for a specific CI provider -- +alongside the core project conventions. Most of this content is irrelevant to typical +agent tasks. + +## Limitations + +"Universally applicable" is context-dependent. In a small project with one developer, +everything might be universally applicable. The semantic gate must judge relevance +relative to the project's scope. Cannot determine actual task frequency distribution +to verify whether content truly applies to "the majority" of tasks. diff --git a/core/content/universal-content-only/rule.yml b/core/content/universal-content-only/rule.yml new file mode 100644 index 0000000..91acb33 --- /dev/null +++ b/core/content/universal-content-only/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.C.0007.check.0001" + message: "Potentially domain-specific content in main instruction file" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(when working on|for .+ files|in the .+ directory|specific to)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/content/universal-content-only/tests/fail/CLAUDE.md b/core/content/universal-content-only/tests/fail/CLAUDE.md new file mode 100644 index 0000000..50fb2bf --- /dev/null +++ b/core/content/universal-content-only/tests/fail/CLAUDE.md @@ -0,0 +1,13 @@ +# MyApp + +E-commerce platform built with Django. + +## Commands + +- `pytest tests/` — run tests + +## API Patterns + +When working on API files, use Django REST Framework serializers. +For authentication files, always use JWT tokens with 1-hour expiry. +In the payments directory, use Stripe SDK v3 with idempotency keys. diff --git a/core/content/universal-content-only/tests/pass/CLAUDE.md b/core/content/universal-content-only/tests/pass/CLAUDE.md new file mode 100644 index 0000000..15dcfc5 --- /dev/null +++ b/core/content/universal-content-only/tests/pass/CLAUDE.md @@ -0,0 +1,13 @@ +# MyApp + +E-commerce platform built with Django. + +## Commands + +- `pytest tests/` — run tests +- `npm run build` — build frontend + +## Structure + +See @docs/api.md for API conventions. +See @docs/frontend.md for React patterns. diff --git a/core/efficiency/.gitkeep b/core/efficiency/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/core/efficiency/E1-code-block-line-limit/E1-code-block-line-limit.md b/core/efficiency/E1-code-block-line-limit/E1-code-block-line-limit.md deleted file mode 100644 index 5bef878..0000000 --- a/core/efficiency/E1-code-block-line-limit/E1-code-block-line-limit.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: E1 -title: Code Block Line Limit -category: efficiency -type: deterministic -backed_by: [] # Tier: experimental — sources exist but claims not yet extracted -checks: - - id: E1-code-block-too-long - name: Code block exceeds 10 lines - severity: medium - pattern_confidence: very_high -sources: - - "https://www.humanlayer.dev/blog/writing-a-good-claude-md" -see_also: [S3, S1] ---- - -# Code Block Line Limit - -Code blocks stay under 10 lines to minimize token usage. - -## Pattern - -**Good:** 5-line example showing key pattern -**Bad:** 25-line function pasted as example diff --git a/core/efficiency/E1-code-block-line-limit/E1-code-block-line-limit.yml b/core/efficiency/E1-code-block-line-limit/E1-code-block-line-limit.yml deleted file mode 100644 index 168bc38..0000000 --- a/core/efficiency/E1-code-block-line-limit/E1-code-block-line-limit.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: E1-code-block-too-long - message: "Code block exceeds 10 lines" - severity: WARNING - languages: [generic] - pattern-regex: "```[^\\n]*\\n(?:[^\\n]*\\n){10,}```" - paths: - include: - - "{{instruction_files}}" diff --git a/core/efficiency/E1-code-block-line-limit/tests/fail.md b/core/efficiency/E1-code-block-line-limit/tests/fail.md deleted file mode 100644 index 5124f81..0000000 --- a/core/efficiency/E1-code-block-line-limit/tests/fail.md +++ /dev/null @@ -1,16 +0,0 @@ -# Test Document - -```python -def example(): - line1 = "code" - line2 = "code" - line3 = "code" - line4 = "code" - line5 = "code" - line6 = "code" - line7 = "code" - line8 = "code" - line9 = "code" - line10 = "code" - line11 = "code" -``` diff --git a/core/efficiency/E1-code-block-line-limit/tests/pass.md b/core/efficiency/E1-code-block-line-limit/tests/pass.md deleted file mode 100644 index 7582871..0000000 --- a/core/efficiency/E1-code-block-line-limit/tests/pass.md +++ /dev/null @@ -1,7 +0,0 @@ -# Test Document - -```bash -npm install -npm test -npm run build -``` diff --git a/core/efficiency/E2-import-count/E2-import-count.md b/core/efficiency/E2-import-count/E2-import-count.md deleted file mode 100644 index f9755e8..0000000 --- a/core/efficiency/E2-import-count/E2-import-count.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: E2 -title: Import Count -category: efficiency -type: deterministic -backed_by: - - source: claude-code-memory - claim: import-max-depth -checks: - - id: E2-too-many-imports - name: More than 10 @imports in root file - severity: medium - pattern_confidence: high -sources: - - "https://code.claude.com/docs/en/memory" - - "https://dev.to/anvodev/how-i-organized-my-claudemd-in-a-monorepo-with-too-many-contexts-37k7" -see_also: [S2, S1] ---- - -# Import Count - -@imports scale with file size; root file under 10 imports. - -## Pattern - -**Good:** 3-5 imports to key documentation -**Bad:** 15 imports loading everything at once diff --git a/core/efficiency/E2-import-count/E2-import-count.yml b/core/efficiency/E2-import-count/E2-import-count.yml deleted file mode 100644 index 0dfcb01..0000000 --- a/core/efficiency/E2-import-count/E2-import-count.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: E2-too-many-imports - message: "More than 10 @imports in root file" - severity: WARNING - languages: [generic] - pattern-regex: "(?s)(@[a-zA-Z0-9_/.-]+\\.md.*){10,}" - paths: - include: - - "{{instruction_files}}" diff --git a/core/efficiency/E2-import-count/tests/fail.md b/core/efficiency/E2-import-count/tests/fail.md deleted file mode 100644 index 47a40f3..0000000 --- a/core/efficiency/E2-import-count/tests/fail.md +++ /dev/null @@ -1,13 +0,0 @@ -# Test Document - -See @docs/file1.md for details. -See @docs/file2.md for details. -See @docs/file3.md for details. -See @docs/file4.md for details. -See @docs/file5.md for details. -See @docs/file6.md for details. -See @docs/file7.md for details. -See @docs/file8.md for details. -See @docs/file9.md for details. -See @docs/file10.md for details. -See @docs/file11.md for details. diff --git a/core/efficiency/E2-import-count/tests/pass.md b/core/efficiency/E2-import-count/tests/pass.md deleted file mode 100644 index c69b486..0000000 --- a/core/efficiency/E2-import-count/tests/pass.md +++ /dev/null @@ -1,4 +0,0 @@ -# Test Document - -See @docs/architecture.md for system overview. -See @docs/api.md for API documentation. diff --git a/core/governance/.gitkeep b/core/governance/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/core/maintenance/.gitkeep b/core/maintenance/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/core/maintenance/M1-version-control/M1-version-control.md b/core/maintenance/M1-version-control/M1-version-control.md deleted file mode 100644 index f7fcd9b..0000000 --- a/core/maintenance/M1-version-control/M1-version-control.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -id: M1 -title: Version Control -category: maintenance -type: deterministic -backed_by: - - source: agents-md-spec - claim: living-document - - source: claude-md-guide - claim: file-placement - - source: dometrain-claude-md-guide - claim: living-document-updates - - source: osmani-ai-coding-workflow - claim: commit-savepoints -checks: - - id: M1-not-tracked - name: Instruction file not in git - severity: high - pattern_confidence: high -sources: - - "https://agents.md/" -see_also: [C5] ---- - -# Version Control - -Instruction files are git-tracked for change history. - -## Pattern - -**Good:** CLAUDE.md committed and tracked in git -**Bad:** Instruction file in .gitignore - -## Limitations - -Pattern detects explicit exclusion via `.gitignore` only. Cannot detect files that were never `git add`-ed — that requires runtime `git status` checks (tooling concern, not static analysis). diff --git a/core/maintenance/M1-version-control/M1-version-control.yml b/core/maintenance/M1-version-control/M1-version-control.yml deleted file mode 100644 index 38839a1..0000000 --- a/core/maintenance/M1-version-control/M1-version-control.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: M1-not-tracked - message: "Instruction file should be git-tracked" - severity: WARNING - languages: [generic] - pattern-regex: "{{main_instruction_file}}" - paths: - include: - - ".gitignore" diff --git a/core/maintenance/M1-version-control/tests/fail.gitignore b/core/maintenance/M1-version-control/tests/fail.gitignore deleted file mode 100644 index 13af612..0000000 --- a/core/maintenance/M1-version-control/tests/fail.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -# Ignore node modules -node_modules/ - -# Ignore instruction file (bad practice) -CLAUDE.md diff --git a/core/maintenance/M1-version-control/tests/pass.gitignore b/core/maintenance/M1-version-control/tests/pass.gitignore deleted file mode 100644 index 3934e2c..0000000 --- a/core/maintenance/M1-version-control/tests/pass.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -# Ignore node modules -node_modules/ - -# Ignore build artifacts -dist/ diff --git a/core/maintenance/M2-no-conflicting-rules/M2-no-conflicting-rules.md b/core/maintenance/M2-no-conflicting-rules/M2-no-conflicting-rules.md deleted file mode 100644 index ee59382..0000000 --- a/core/maintenance/M2-no-conflicting-rules/M2-no-conflicting-rules.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: M2 -title: No Conflicting Rules -category: maintenance -type: semantic -backed_by: - - source: claude-code-memory - claim: keep-rules-focused -checks: - - id: M2-potential-conflict - name: Potential conflicting MUST/MUST NOT - severity: high - pattern_confidence: high -question: "Do any rules contradict each other?" -criteria: - - No MUST and MUST NOT on same topic - - Parent and child rules are consistent - - No implicit contradictions -sources: - - "https://code.claude.com/docs/en/memory" -see_also: [C2] ---- - -# No Conflicting Rules - -No contradictory MUST/MUST NOT on same topic. - -## Pattern - -**Good:** Consistent rules across all files -**Bad:** Root says "MUST use tabs", child says "MUST use spaces" diff --git a/core/maintenance/M2-no-conflicting-rules/M2-no-conflicting-rules.yml b/core/maintenance/M2-no-conflicting-rules/M2-no-conflicting-rules.yml deleted file mode 100644 index 1a148b6..0000000 --- a/core/maintenance/M2-no-conflicting-rules/M2-no-conflicting-rules.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: M2-potential-conflict - message: "Potential rule to check for conflicts" - severity: WARNING - languages: [generic] - pattern-regex: "\\b(MUST|MUST NOT|NEVER|ALWAYS)\\b" - paths: - include: - - "{{instruction_files}}" diff --git a/core/maintenance/M2-no-conflicting-rules/tests/fail.md b/core/maintenance/M2-no-conflicting-rules/tests/fail.md deleted file mode 100644 index fca3d98..0000000 --- a/core/maintenance/M2-no-conflicting-rules/tests/fail.md +++ /dev/null @@ -1,9 +0,0 @@ -# Test Document - -You MUST use TypeScript. - -You MUST NOT use TypeScript for scripts. - -ALWAYS validate input. - -NEVER validate user input directly. diff --git a/core/maintenance/M2-no-conflicting-rules/tests/pass.md b/core/maintenance/M2-no-conflicting-rules/tests/pass.md deleted file mode 100644 index 905afa9..0000000 --- a/core/maintenance/M2-no-conflicting-rules/tests/pass.md +++ /dev/null @@ -1,7 +0,0 @@ -# Test Document - -Use TypeScript for application code. - -Use JavaScript for build scripts. - -Follow the linting rules. diff --git a/core/maintenance/M3-map-staleness-prevention/M3-map-staleness-prevention.md b/core/maintenance/M3-map-staleness-prevention/M3-map-staleness-prevention.md deleted file mode 100644 index 19c56bd..0000000 --- a/core/maintenance/M3-map-staleness-prevention/M3-map-staleness-prevention.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -id: M3 -title: Map Staleness Prevention -category: maintenance -type: deterministic -backed_by: [] -checks: - - id: M3-stale-path - name: Path in backbone.yml may not exist - severity: high - pattern_confidence: low -sources: [] -see_also: [C4] ---- - -# Map Staleness Prevention - -Paths in backbone.yml exist on filesystem. - -## Pattern - -**Good:** All paths in backbone.yml resolve to files -**Bad:** backbone.yml references deleted directories diff --git a/core/maintenance/M3-map-staleness-prevention/M3-map-staleness-prevention.yml b/core/maintenance/M3-map-staleness-prevention/M3-map-staleness-prevention.yml deleted file mode 100644 index 40608ec..0000000 --- a/core/maintenance/M3-map-staleness-prevention/M3-map-staleness-prevention.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: M3-stale-path - message: "Path reference to validate" - severity: WARNING - languages: [yaml] - pattern-regex: "path:\\s*['\"]?[a-zA-Z0-9_/.-]+['\"]?" - paths: - include: - - ".reporails/backbone.yml" diff --git a/core/maintenance/M3-map-staleness-prevention/tests/fail.yml b/core/maintenance/M3-map-staleness-prevention/tests/fail.yml deleted file mode 100644 index 5a4ade1..0000000 --- a/core/maintenance/M3-map-staleness-prevention/tests/fail.yml +++ /dev/null @@ -1,7 +0,0 @@ -# backbone.yml - path references without validation metadata -maps: - components: - api: - path: src/api/ - web: - path: src/web/ diff --git a/core/maintenance/M3-map-staleness-prevention/tests/pass.yml b/core/maintenance/M3-map-staleness-prevention/tests/pass.yml deleted file mode 100644 index a2140db..0000000 --- a/core/maintenance/M3-map-staleness-prevention/tests/pass.yml +++ /dev/null @@ -1,10 +0,0 @@ -# backbone.yml - path references with validation -maps: - components: - api: - path: src/api/ - web: - path: src/web/ -validation: - last_checked: "2025-01-15" - ci_hook: validate-backbone diff --git a/core/maintenance/M4-backbone-index-completeness/M4-backbone-index-completeness.md b/core/maintenance/M4-backbone-index-completeness/M4-backbone-index-completeness.md deleted file mode 100644 index fe9e4eb..0000000 --- a/core/maintenance/M4-backbone-index-completeness/M4-backbone-index-completeness.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: M2 -title: Backbone Index Completeness -category: maintenance -type: deterministic -backed_by: [] - # experimental tier — community pattern (no official/research source) -checks: - - id: M2-index-present - name: Backbone has rules index section - severity: medium - pattern_confidence: low -sources: [] -see_also: [M3] ---- - -# Backbone Index Completeness - -Every rule directory on the filesystem is registered in `backbone.yml` `rules.index`. - -Complements M3 (which checks the inverse: backbone paths exist on disk). M4 ensures no filesystem entity is orphaned from the index. - -## Pattern - -**Good:** All rule directories under `core/` and `agents/*/rules/` have corresponding entries in `rules.index` -**Bad:** A rule directory exists but has no entry in `rules.index`, making it invisible to backbone-based path resolution - -## Recommended Automation - -A pre-commit hook can enforce this automatically: - -1. List rule directories matching `core/*/{ID}-{slug}/` and `agents/*/rules/{ID}-{slug}/` -2. Parse `rules.index` from `.reporails/backbone.yml` -3. Warn on mismatches (directories not in index, or index entries without directories) - -Example check (conceptual — adapt to your CI toolchain): - -```bash -# Extract rule IDs from filesystem -fs_ids=$(find core agents/*/rules -mindepth 2 -maxdepth 2 -type d \ - | sed 's|.*/\([A-Z_]*[0-9]*\)-.*|\1|' | sort -u) - -# Extract rule IDs from backbone index -index_ids=$(grep -E '^\s+[A-Z_]+[0-9]+:' .reporails/backbone.yml \ - | sed 's/^\s*\([A-Z_]*[0-9]*\):.*/\1/' | sort -u) - -# Compare -diff <(echo "$fs_ids") <(echo "$index_ids") -``` - -This is documented as a recommendation. The framework does not ship executable hooks. diff --git a/core/maintenance/M4-backbone-index-completeness/M4-backbone-index-completeness.yml b/core/maintenance/M4-backbone-index-completeness/M4-backbone-index-completeness.yml deleted file mode 100644 index e8bcd62..0000000 --- a/core/maintenance/M4-backbone-index-completeness/M4-backbone-index-completeness.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: M4-index-present - message: "Backbone index section — validate completeness against filesystem" - severity: WARNING - languages: [yaml] - pattern-regex: "index:" - paths: - include: - - ".reporails/backbone.yml" diff --git a/core/maintenance/M4-backbone-index-completeness/tests/fail.yml b/core/maintenance/M4-backbone-index-completeness/tests/fail.yml deleted file mode 100644 index 6e8d92a..0000000 --- a/core/maintenance/M4-backbone-index-completeness/tests/fail.yml +++ /dev/null @@ -1,7 +0,0 @@ -# ruleid: M6-index-present -# fail: backbone with index section — gate for CLI cross-reference validation -rules: - core: core/ - index: - S1: size-limits - # Missing: C1, M1, CLAUDE_S1 exist on disk but not in index diff --git a/core/maintenance/M4-backbone-index-completeness/tests/pass.yml b/core/maintenance/M4-backbone-index-completeness/tests/pass.yml deleted file mode 100644 index dfac68d..0000000 --- a/core/maintenance/M4-backbone-index-completeness/tests/pass.yml +++ /dev/null @@ -1,8 +0,0 @@ -# pass: backbone with complete index covering all filesystem rules -rules: - core: core/ - index: - S1: size-limits - C1: core-sections - M1: version-control - CLAUDE_S1: skill-size-limits diff --git a/core/structure/S1-size-limits/S1-size-limits.md b/core/structure/S1-size-limits/S1-size-limits.md deleted file mode 100644 index 05d9f69..0000000 --- a/core/structure/S1-size-limits/S1-size-limits.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: S1 -title: Size Limits -category: structure -type: deterministic -backed_by: - - source: instruction-limits-principles - claim: line-limit - - source: agents-md-spec - claim: root-placement - - source: codex-agents-md - claim: size-limit-32kb - - source: instruction-limits-principles - claim: instruction-capacity - - source: instruction-limits-principles - claim: less-is-more - - source: spec-writing-for-agents - claim: curse-of-instructions - - source: monorepo-claude-md-organization - claim: reduction-achieved - - source: enterprise-claude-usage - claim: kb-limit - - source: claude-md-optimization-study - claim: optimization-improvement - - source: claude-code-issue-13579 - claim: token-waste-measured -checks: - - id: S1-root-too-long - name: Root instruction file exceeds 200 lines - severity: critical - pattern_confidence: very_high -sources: - - "https://www.humanlayer.dev/blog/writing-a-good-claude-md" -see_also: [S2] ---- - -# Size Limits - -Prevents instruction degradation from token bloat. Frontier LLMs follow ~150-200 instructions with reasonable consistency; exceeding this causes uniform quality degradation. - -## Pattern - -**Good:** Root file under 100 lines with @imports for details -**Bad:** 300-line monolithic instruction file with 200+ instructions diff --git a/core/structure/S1-size-limits/S1-size-limits.yml b/core/structure/S1-size-limits/S1-size-limits.yml deleted file mode 100644 index 97cb3be..0000000 --- a/core/structure/S1-size-limits/S1-size-limits.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: S1-root-too-long - message: "Root instruction file exceeds 200 lines" - severity: ERROR - languages: [generic] - pattern-regex: "(?s)(?:[^\\n]*\\n){200,}" - paths: - include: - - "{{main_instruction_file}}" diff --git a/core/structure/S1-size-limits/tests/fail.md b/core/structure/S1-size-limits/tests/fail.md deleted file mode 100644 index 40cf048..0000000 --- a/core/structure/S1-size-limits/tests/fail.md +++ /dev/null @@ -1,206 +0,0 @@ -# Test Document That Is Too Long - -This file has over 200 lines to trigger the S1-root-too-long rule. - -## Section 1 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 2 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 3 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 4 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 5 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 6 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 7 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 8 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 9 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 10 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 11 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 12 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 13 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 14 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 15 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 16 - -Content line. -Content line. -Content line. -Content line. -Content line. diff --git a/core/structure/S1-size-limits/tests/pass.md b/core/structure/S1-size-limits/tests/pass.md deleted file mode 100644 index 6a01623..0000000 --- a/core/structure/S1-size-limits/tests/pass.md +++ /dev/null @@ -1,7 +0,0 @@ -# Test Document - -This file is under 200 lines. - -## Section - -Some content here. diff --git a/core/structure/S2-progressive-disclosure/S2-progressive-disclosure.md b/core/structure/S2-progressive-disclosure/S2-progressive-disclosure.md deleted file mode 100644 index ab37dba..0000000 --- a/core/structure/S2-progressive-disclosure/S2-progressive-disclosure.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: S2 -title: Progressive Disclosure -category: structure -type: deterministic -backed_by: - - source: claude-code-memory - claim: imports-syntax - - source: claude-code-memory - claim: recursive-discovery - - source: instruction-limits-principles - claim: progressive-files - - source: agents-md-spec - claim: nested-monorepo - - source: codex-agents-md - claim: discovery-order - - source: codex-agent-loop - claim: cascading-later-wins - - source: agents-md-spec - claim: nearest-precedence - - source: spec-writing-for-agents - claim: modularity - - source: monorepo-claude-md-organization - claim: reduction-achieved - - source: monorepo-claude-md-organization - claim: service-specific-files - - source: claude-md-guide - claim: file-placement - - source: dometrain-claude-md-guide - claim: lazy-loading-context -checks: - - id: S2-large-file-no-imports - name: File over 100 lines without @imports or references - severity: high - pattern_confidence: high -sources: - - "https://code.claude.com/docs/en/memory" -see_also: [S1, E2] ---- - -# Progressive Disclosure - -Large files use @imports or "See X for Y" to avoid token bloat. - -## Pattern - -**Good:** `@docs/api-reference.md` or "See CONTRIBUTING.md for style guide" -**Bad:** 150-line file with all content inline diff --git a/core/structure/S2-progressive-disclosure/S2-progressive-disclosure.yml b/core/structure/S2-progressive-disclosure/S2-progressive-disclosure.yml deleted file mode 100644 index 8ae4909..0000000 --- a/core/structure/S2-progressive-disclosure/S2-progressive-disclosure.yml +++ /dev/null @@ -1,11 +0,0 @@ -rules: - - id: S2-large-file-no-imports - message: "File over 100 lines without @imports or external references" - severity: WARNING - languages: [generic] - patterns: - - pattern-regex: "(?s)(?:[^\\n]*\\n){100,}" - - pattern-not-regex: "@[a-zA-Z0-9_/.-]+\\.(md|yml|yaml)|[Ss]ee\\s+[A-Z][a-zA-Z0-9_.-]+\\s+for" - paths: - include: - - "{{main_instruction_file}}" diff --git a/core/structure/S2-progressive-disclosure/tests/fail.md b/core/structure/S2-progressive-disclosure/tests/fail.md deleted file mode 100644 index 5c64c1f..0000000 --- a/core/structure/S2-progressive-disclosure/tests/fail.md +++ /dev/null @@ -1,105 +0,0 @@ -# Test Document Without Imports - -This file has over 100 lines but no @imports references. - -## Section 1 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 2 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 3 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 4 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 5 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 6 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 7 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 8 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. diff --git a/core/structure/S2-progressive-disclosure/tests/pass.md b/core/structure/S2-progressive-disclosure/tests/pass.md deleted file mode 100644 index a31c976..0000000 --- a/core/structure/S2-progressive-disclosure/tests/pass.md +++ /dev/null @@ -1,94 +0,0 @@ -# Test Document With Imports - -This file has over 100 lines but includes @imports references. - -See @docs/architecture.md for details. - -## Section 1 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 2 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 3 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 4 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 5 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 6 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. - -## Section 7 - -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. -Content line. diff --git a/core/structure/S3-no-embedded-code-snippets/S3-no-embedded-code-snippets.md b/core/structure/S3-no-embedded-code-snippets/S3-no-embedded-code-snippets.md deleted file mode 100644 index 11aaae3..0000000 --- a/core/structure/S3-no-embedded-code-snippets/S3-no-embedded-code-snippets.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: S3 -title: No Embedded Code Snippets -category: structure -type: deterministic -backed_by: - - source: spec-writing-for-agents - claim: code-snippet-beats-prose -checks: - - id: S3-code-block-too-long - name: Code block exceeds 10 lines - severity: medium - pattern_confidence: very_high -sources: - - "https://www.humanlayer.dev/blog/writing-a-good-claude-md" -see_also: [E1, S1] ---- - -# No Embedded Code Snippets - -Code blocks should be brief examples, not function definitions. - -## Pattern - -**Good:** 3-line config example -**Bad:** 20-line function pasted inline diff --git a/core/structure/S3-no-embedded-code-snippets/S3-no-embedded-code-snippets.yml b/core/structure/S3-no-embedded-code-snippets/S3-no-embedded-code-snippets.yml deleted file mode 100644 index 7bbd19c..0000000 --- a/core/structure/S3-no-embedded-code-snippets/S3-no-embedded-code-snippets.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: S3-code-block-too-long - message: "Code block exceeds 10 lines" - severity: WARNING - languages: [generic] - pattern-regex: "```[^\\n]*\\n(?:[^\\n]*\\n){10,}```" - paths: - include: - - "{{instruction_files}}" diff --git a/core/structure/S3-no-embedded-code-snippets/tests/fail.md b/core/structure/S3-no-embedded-code-snippets/tests/fail.md deleted file mode 100644 index 793d5bf..0000000 --- a/core/structure/S3-no-embedded-code-snippets/tests/fail.md +++ /dev/null @@ -1,18 +0,0 @@ -# Test Document With Long Code Block - -This file has a code block exceeding 10 lines. - -```python -def example(): - line1 = "code" - line2 = "code" - line3 = "code" - line4 = "code" - line5 = "code" - line6 = "code" - line7 = "code" - line8 = "code" - line9 = "code" - line10 = "code" - line11 = "code" -``` diff --git a/core/structure/S3-no-embedded-code-snippets/tests/pass.md b/core/structure/S3-no-embedded-code-snippets/tests/pass.md deleted file mode 100644 index 4d2e091..0000000 --- a/core/structure/S3-no-embedded-code-snippets/tests/pass.md +++ /dev/null @@ -1,13 +0,0 @@ -# Test Document With Short Code Block - -This file has code blocks under 10 lines. - -```bash -npm install -npm test -``` - -```python -def short(): - return "ok" -``` diff --git a/core/structure/S4-clear-markdown-structure/S4-clear-markdown-structure.md b/core/structure/S4-clear-markdown-structure/S4-clear-markdown-structure.md deleted file mode 100644 index f101ca2..0000000 --- a/core/structure/S4-clear-markdown-structure/S4-clear-markdown-structure.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: S4 -title: Clear Markdown Structure -category: structure -type: deterministic -backed_by: - - source: claude-code-memory - claim: use-structure - - source: agents-md-spec - claim: standard-markdown -checks: - - id: S4-heading-hierarchy-skip - name: Heading level skipped (e.g., # to ###) - severity: medium - pattern_confidence: medium -sources: - - "https://code.claude.com/docs/en/memory" -see_also: [C1, S2] ---- - -# Clear Markdown Structure - -Headings follow hierarchy: # then ## then ###, no skipping. - -## Pattern - -**Good:** # Title, ## Section, ### Subsection -**Bad:** # Title, ### Subsection (skipped ##) diff --git a/core/structure/S4-clear-markdown-structure/S4-clear-markdown-structure.yml b/core/structure/S4-clear-markdown-structure/S4-clear-markdown-structure.yml deleted file mode 100644 index bbda532..0000000 --- a/core/structure/S4-clear-markdown-structure/S4-clear-markdown-structure.yml +++ /dev/null @@ -1,9 +0,0 @@ -rules: - - id: S4-heading-hierarchy-skip - message: "Heading level skipped (e.g., # to ###)" - severity: WARNING - languages: [generic] - pattern-regex: "^#\\s[^\\n]+\\n(?:(?!^##?\\s)[^\\n]*\\n)*^###\\s" - paths: - include: - - "{{instruction_files}}" diff --git a/core/structure/S4-clear-markdown-structure/tests/fail.md b/core/structure/S4-clear-markdown-structure/tests/fail.md deleted file mode 100644 index bac4490..0000000 --- a/core/structure/S4-clear-markdown-structure/tests/fail.md +++ /dev/null @@ -1,7 +0,0 @@ -# Main Title - -Some content here. - -### Skipped to H3 - -This skips the H2 level, which is bad structure. diff --git a/core/structure/S4-clear-markdown-structure/tests/pass.md b/core/structure/S4-clear-markdown-structure/tests/pass.md deleted file mode 100644 index b73cd18..0000000 --- a/core/structure/S4-clear-markdown-structure/tests/pass.md +++ /dev/null @@ -1,11 +0,0 @@ -# Main Title - -Some content here. - -## Section - -More content. - -### Subsection - -Proper hierarchy from H1 to H2 to H3. diff --git a/core/structure/cross-agent-compatibility/rule.md b/core/structure/cross-agent-compatibility/rule.md new file mode 100644 index 0000000..ae62ab5 --- /dev/null +++ b/core/structure/cross-agent-compatibility/rule.md @@ -0,0 +1,55 @@ +--- +id: "CORE:S:0010" +slug: cross-agent-compatibility +title: Cross-Agent Compatibility +category: structure +type: mechanical +level: L3 +backed_by: +- agents-md-spec +- enterprise-claude-usage +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0010:check:0001" + type: mechanical + check: file_exists + args: + path: "CLAUDE.md" + severity: medium +- id: "CORE:S:0010:check:0002" + type: mechanical + check: file_exists + args: + path: "AGENTS.md" + severity: medium +question: "Does the project provide instruction files for more than one AI agent?" +criteria: +- At least two distinct agent instruction file types are present in the project +- Recognized file types include CLAUDE.md, AGENTS.md, .cursorrules, + .github/copilot-instructions.md +- Both files contain non-trivial content (not empty) +- Files are tracked by version control +--- + +# Cross-Agent Compatibility + +Projects with instruction files for one agent should also provide an instruction file for at least one other major agent. + +## Pass / Fail + +**Pass:** A project contains both CLAUDE.md (Claude-specific instructions) and +AGENTS.md (vendor-neutral instructions). The AGENTS.md file provides +equivalent guidance that Codex, Copilot, or Cursor agents can consume. +Both files are committed and tracked. +**Fail:** A project contains only CLAUDE.md with no AGENTS.md, no .cursorrules, and +no other agent instruction file. Developers using Codex or Copilot receive +no project-specific guidance. The instruction system is locked to a single +agent vendor. + +## Limitations + +Checks for the presence of multiple agent instruction file types but cannot +verify that their content is consistent or equivalent. A project with +CLAUDE.md containing detailed instructions and an empty AGENTS.md technically +passes. Cannot assess whether the instruction files provide equivalent +guidance quality across agents. diff --git a/core/structure/cross-agent-compatibility/rule.yml b/core/structure/cross-agent-compatibility/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/cross-agent-compatibility/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/cross-agent-compatibility/tests/fail/CLAUDE.md b/core/structure/cross-agent-compatibility/tests/fail/CLAUDE.md new file mode 100644 index 0000000..4b826c0 --- /dev/null +++ b/core/structure/cross-agent-compatibility/tests/fail/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Only one agent instruction file in a multi-agent project. + +## Commands + +- `pytest tests/` — run tests diff --git a/core/structure/cross-agent-compatibility/tests/pass/AGENTS.md b/core/structure/cross-agent-compatibility/tests/pass/AGENTS.md new file mode 100644 index 0000000..cdeda9d --- /dev/null +++ b/core/structure/cross-agent-compatibility/tests/pass/AGENTS.md @@ -0,0 +1,8 @@ +# MyApp + +E-commerce platform built with Python and React. + +## Commands + +- `pytest tests/` — run tests +- `npm run build` — build frontend diff --git a/core/structure/cross-agent-compatibility/tests/pass/CLAUDE.md b/core/structure/cross-agent-compatibility/tests/pass/CLAUDE.md new file mode 100644 index 0000000..cdeda9d --- /dev/null +++ b/core/structure/cross-agent-compatibility/tests/pass/CLAUDE.md @@ -0,0 +1,8 @@ +# MyApp + +E-commerce platform built with Python and React. + +## Commands + +- `pytest tests/` — run tests +- `npm run build` — build frontend diff --git a/core/structure/cross-agent-compatibility/tests/pass/packages/api/CLAUDE.md b/core/structure/cross-agent-compatibility/tests/pass/packages/api/CLAUDE.md new file mode 100644 index 0000000..ab4ba0b --- /dev/null +++ b/core/structure/cross-agent-compatibility/tests/pass/packages/api/CLAUDE.md @@ -0,0 +1,8 @@ +# API Package + +REST API endpoints with JSON responses. + +## Commands + +- `npm run test:api` -- run API tests +- `npm run build:api` -- build API package diff --git a/core/structure/decomposed-instruction-system/rule.md b/core/structure/decomposed-instruction-system/rule.md new file mode 100644 index 0000000..206cf45 --- /dev/null +++ b/core/structure/decomposed-instruction-system/rule.md @@ -0,0 +1,50 @@ +--- +id: "CORE:S:0007" +slug: decomposed-instruction-system +title: Decomposed Instruction System +category: structure +type: mechanical +level: L3 +backed_by: +- claude-md-guide +- dometrain-claude-md-guide +- instruction-limits-principles +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0007:check:0001" + type: mechanical + check: file_count + args: + pattern: "{{instruction_files}}" + min: 2 + severity: medium +question: "Does the instruction system consist of at least two files?" +criteria: +- At least two files exist in the instruction system (main file + at least one + supplementary) +- Files are counted from the combined instruction_files template variable + resolution +- Both the main instruction file and supplementary files contribute to the count +--- + +# Decomposed Instruction System + +The instruction system must consist of at least two files. + +## Pass / Fail + +**Pass:** A project has CLAUDE.md at the root containing high-level project guidance +and a .claude/rules/testing.md file with detailed testing instructions. +The instruction system consists of 2 files, meeting the minimum threshold. +**Fail:** A project has only a single CLAUDE.md file at the root. All instructions — +project description, coding standards, testing procedures, deployment notes — +are packed into one 280-line file. No supplementary files, no .claude/rules/ +directory, no imported content. + +## Limitations + +Checks file count only, not whether decomposition is meaningful. A project +with CLAUDE.md and a trivially small .claude/rules/placeholder.md technically +passes but has not genuinely decomposed its instruction system. Cannot assess +whether the decomposition follows a logical separation of concerns. diff --git a/core/structure/decomposed-instruction-system/rule.yml b/core/structure/decomposed-instruction-system/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/decomposed-instruction-system/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/decomposed-instruction-system/tests/fail/CLAUDE.md b/core/structure/decomposed-instruction-system/tests/fail/CLAUDE.md new file mode 100644 index 0000000..0a14827 --- /dev/null +++ b/core/structure/decomposed-instruction-system/tests/fail/CLAUDE.md @@ -0,0 +1,15 @@ +# MyApp + +Single monolithic instruction file with no decomposition. + +## Commands + +- `npm test` — run tests + +## Testing + +Use Jest for unit tests. Name test files `*.test.ts`. + +## Style + +Use 2-space indentation. Max line length 100. diff --git a/core/structure/decomposed-instruction-system/tests/pass/.claude/rules/testing.md b/core/structure/decomposed-instruction-system/tests/pass/.claude/rules/testing.md new file mode 100644 index 0000000..7ab24c3 --- /dev/null +++ b/core/structure/decomposed-instruction-system/tests/pass/.claude/rules/testing.md @@ -0,0 +1,3 @@ +# Testing Conventions + +Use Jest for unit tests. Name test files `*.test.ts`. \ No newline at end of file diff --git a/core/structure/decomposed-instruction-system/tests/pass/CLAUDE.md b/core/structure/decomposed-instruction-system/tests/pass/CLAUDE.md new file mode 100644 index 0000000..ae82759 --- /dev/null +++ b/core/structure/decomposed-instruction-system/tests/pass/CLAUDE.md @@ -0,0 +1,6 @@ +# MyApp + +Platform built with React and Node.js. + +See @docs/testing.md for testing conventions. +See @docs/style.md for code style. diff --git a/core/structure/decomposed-instruction-system/tests/pass/packages/core/CLAUDE.md b/core/structure/decomposed-instruction-system/tests/pass/packages/core/CLAUDE.md new file mode 100644 index 0000000..6890728 --- /dev/null +++ b/core/structure/decomposed-instruction-system/tests/pass/packages/core/CLAUDE.md @@ -0,0 +1,8 @@ +# Core Package + +Business logic for the core domain. + +## Commands + +- `npm run test:core` -- run core package tests +- `npm run build:core` -- build core package diff --git a/core/structure/instruction-file-exists/rule.md b/core/structure/instruction-file-exists/rule.md new file mode 100644 index 0000000..82a2186 --- /dev/null +++ b/core/structure/instruction-file-exists/rule.md @@ -0,0 +1,47 @@ +--- +id: "CORE:S:0001" +slug: instruction-file-exists +title: Instruction File Exists +category: structure +type: mechanical +level: L1 +backed_by: +- agents-md-spec +- claude-md-guide +- dometrain-claude-md-guide +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0001:check:0001" + type: mechanical + check: file_exists + severity: critical +question: "Does at least one recognized instruction file exist in the project?" +criteria: +- A file matching a recognized instruction filename pattern exists in the + project root +- The recognized filenames include CLAUDE.md, AGENTS.md, and agent-equivalent + files +- The file is not empty (has at least 1 byte of content) +--- + +# Instruction File Exists + +At least one recognized instruction file must exist in the project. + +## Pass / Fail + +**Pass:** A repository contains a CLAUDE.md file at the project root with at least +10 lines of project-specific content. The file is committed to git. +Alternatively, an AGENTS.md file exists at the root. +**Fail:** A repository has no CLAUDE.md, no AGENTS.md, and no other recognized +instruction file anywhere in the project tree. The agent must operate +without any project-specific guidance. + +## Limitations + +Cannot verify the instruction file contains meaningful content — only that +a file with a recognized name exists at the expected location. An empty or +trivially small file passes this rule but would fail content-level checks. +Does not check for agent-specific variants (e.g., .cursorrules) beyond the +recognized set. diff --git a/core/structure/instruction-file-exists/rule.yml b/core/structure/instruction-file-exists/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/instruction-file-exists/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/instruction-file-exists/tests/fail/README.md b/core/structure/instruction-file-exists/tests/fail/README.md new file mode 100644 index 0000000..936d3fd --- /dev/null +++ b/core/structure/instruction-file-exists/tests/fail/README.md @@ -0,0 +1,3 @@ +# No Instruction File + +This project has no CLAUDE.md or AGENTS.md. diff --git a/core/structure/instruction-file-exists/tests/pass/CLAUDE.md b/core/structure/instruction-file-exists/tests/pass/CLAUDE.md new file mode 100644 index 0000000..e38d960 --- /dev/null +++ b/core/structure/instruction-file-exists/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +A sample project with a valid instruction file. + +## Commands + +- `npm test` — run tests diff --git a/core/structure/instruction-file-is-markdown/rule.md b/core/structure/instruction-file-is-markdown/rule.md new file mode 100644 index 0000000..83e8201 --- /dev/null +++ b/core/structure/instruction-file-is-markdown/rule.md @@ -0,0 +1,40 @@ +--- +id: "CORE:S:0002" +slug: instruction-file-is-markdown +title: Instruction File Is Markdown +category: structure +type: mechanical +level: L1 +backed_by: +- agents-md-spec +- spec-writing-for-agents +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0002:check:0001" + type: mechanical + check: file_exists + severity: critical +question: "Does every instruction file use the .md file extension?" +criteria: +- Every recognized instruction file has a .md file extension +- No instruction files use alternative extensions (.txt, .yaml, .rst, .org) +- The filename follows the expected naming convention for the agent +--- + +# Instruction File Is Markdown + +Every instruction file must use Markdown format with a .md extension. + +## Pass / Fail + +**Pass:** The project root contains CLAUDE.md — a file with the .md extension +containing standard Markdown syntax (headings, lists, code blocks). +**Fail:** The project root contains a file named CLAUDE.txt or CLAUDE.yaml that +serves as the instruction file but does not use Markdown format or the +.md file extension. + +## Limitations + +Only checks the file extension, not whether the content is valid Markdown. +A file named CLAUDE.md containing raw JSON or binary data would pass this +check. Content validity is outside the scope of a mechanical extension check. diff --git a/core/structure/instruction-file-is-markdown/rule.yml b/core/structure/instruction-file-is-markdown/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/instruction-file-is-markdown/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/instruction-file-is-markdown/tests/fail/README.md b/core/structure/instruction-file-is-markdown/tests/fail/README.md new file mode 100644 index 0000000..01738dc --- /dev/null +++ b/core/structure/instruction-file-is-markdown/tests/fail/README.md @@ -0,0 +1,3 @@ +# No Instruction File + +This project has a README but no CLAUDE.md or AGENTS.md instruction file. diff --git a/core/structure/instruction-file-is-markdown/tests/pass/CLAUDE.md b/core/structure/instruction-file-is-markdown/tests/pass/CLAUDE.md new file mode 100644 index 0000000..a780a16 --- /dev/null +++ b/core/structure/instruction-file-is-markdown/tests/pass/CLAUDE.md @@ -0,0 +1,8 @@ +# MyApp + +Web application built with React and Node.js. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build diff --git a/core/structure/instruction-file-size-limit/rule.md b/core/structure/instruction-file-size-limit/rule.md new file mode 100644 index 0000000..edbcb4e --- /dev/null +++ b/core/structure/instruction-file-size-limit/rule.md @@ -0,0 +1,46 @@ +--- +id: "CORE:S:0005" +slug: instruction-file-size-limit +title: Instruction File Size Limit +category: structure +type: mechanical +level: L2 +backed_by: +- claude-md-guide +- instruction-limits-principles +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0005:check:0001" + type: mechanical + check: line_count + args: + max: 300 + severity: high +question: "Is every instruction file at most 300 lines long?" +criteria: +- Every instruction file has a line count of 300 or fewer +- Line count includes all lines (blank lines, comments, content) +- Each file is evaluated independently, not as a sum +--- + +# Instruction File Size Limit + +Each instruction file must be at most 300 lines. + +## Pass / Fail + +**Pass:** A CLAUDE.md file contains 180 lines of concise project guidance. A +supplementary .claude/rules/testing.md file contains 45 lines. Each +individual file is well under the 300-line threshold. +**Fail:** A CLAUDE.md file contains 420 lines, including extensive inline code +examples, duplicated style guides, and verbose explanations that could be +moved to imported files. The single file exceeds the 300-line limit. + +## Limitations + +Line count is a coarse proxy for context consumption. A file with 290 lines +of dense technical content may consume more context than a 310-line file +with generous whitespace. Does not account for line length variation. Also +does not distinguish between the root instruction file and supplementary +files, though the threshold applies equally to both. diff --git a/core/structure/instruction-file-size-limit/rule.yml b/core/structure/instruction-file-size-limit/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/instruction-file-size-limit/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/instruction-file-size-limit/tests/fail/CLAUDE.md b/core/structure/instruction-file-size-limit/tests/fail/CLAUDE.md new file mode 100644 index 0000000..71b16ac --- /dev/null +++ b/core/structure/instruction-file-size-limit/tests/fail/CLAUDE.md @@ -0,0 +1,340 @@ +# Acme Platform Monorepo + +This is the main instruction file for the Acme Platform monorepo. +It contains all coding standards, deployment procedures, testing +requirements, security policies, and operational guidelines for +every service in the platform. All contributors must read and +follow every section of this document before submitting any code. + +Last updated: 2026-01-15 + +Maintainers: platform-team@acme.io + +## Commands + +Run the full test suite before every commit: + +```bash +npm run test:unit -- --coverage --verbose +npm run test:integration -- --timeout 30000 +npm run test:e2e -- --headless --retries 2 +npm run lint -- --fix --ext .ts,.tsx,.js,.jsx +npm run typecheck +npm run build -- --mode production +``` + +For individual services: + +```bash +cd services/api-gateway && npm run test && npm run build +cd services/user-service && npm run test && npm run build +cd services/billing && npm run test && npm run build +cd services/notifications && npm run test && npm run build +``` + +Database commands: + +```bash +npm run db:migrate -- --env development +npm run db:seed -- --env development +npm run db:reset -- --env test +``` + +## Project Structure + +``` +acme-platform/ + services/ + api-gateway/ # Express-based API gateway + src/ + routes/ + middleware/ + validators/ + tests/ + user-service/ # User management microservice + src/ + controllers/ + models/ + repositories/ + tests/ + billing/ # Stripe-integrated billing + src/ + handlers/ + webhooks/ + tests/ + notifications/ # Email and push notifications + src/ + providers/ + templates/ + tests/ + packages/ + shared-types/ # Shared TypeScript types + shared-utils/ # Shared utility functions + db-client/ # Database client wrapper + logger/ # Structured logging package + infrastructure/ + terraform/ # IaC definitions + docker/ # Dockerfiles + k8s/ # Kubernetes manifests + docs/ # Documentation +``` + +## Code Style and Conventions + +All code must follow these style rules without exception. + +### Naming Conventions + +- Use camelCase for variables and functions +- Use PascalCase for classes, interfaces, and type aliases +- Use UPPER_SNAKE_CASE for constants and environment variables +- Use kebab-case for file names and directory names +- Prefix interfaces with I (e.g., IUserRepository) +- Prefix type aliases with T (e.g., TUserResponse) +- Suffix abstract classes with Base (e.g., ServiceBase) + +### Import Ordering + +Always order imports in this exact sequence: + +```typescript +// 1. Node built-ins +import { readFile } from 'node:fs/promises'; +import { join } from 'node:path'; + +// 2. External dependencies +import express from 'express'; +import { z } from 'zod'; + +// 3. Internal packages +import { logger } from '@acme/logger'; +import { DbClient } from '@acme/db-client'; + +// 4. Relative imports +import { UserController } from './controllers/user-controller'; +import { validateRequest } from './middleware/validate'; +``` + +## API Patterns + +Every API endpoint must follow this exact pattern: + +```typescript +import { Router, Request, Response, NextFunction } from 'express'; +import { z } from 'zod'; +import { logger } from '@acme/logger'; +import { AppError } from '../errors/app-error'; + +const requestSchema = z.object({ + body: z.object({ + name: z.string().min(1).max(255), + email: z.string().email(), + role: z.enum(['admin', 'user', 'viewer']), + }), + params: z.object({ + id: z.string().uuid(), + }), +}); + +export const updateUser = async ( + req: Request, + res: Response, + next: NextFunction +) => { + try { + const validated = requestSchema.parse({ + body: req.body, + params: req.params, + }); + const result = await userService.update( + validated.params.id, + validated.body + ); + logger.info('User updated', { + userId: validated.params.id, + fields: Object.keys(validated.body), + }); + res.status(200).json({ success: true, data: result }); + } catch (error) { + next(error); + } +}; +``` + +Every endpoint must validate input with Zod. Every endpoint must +use structured logging. Every endpoint must return a consistent +response envelope. These requirements are mandatory for all services. + +## Database Conventions + +We use PostgreSQL with Prisma ORM. All database access must go +through the repository pattern. + +```typescript +export class UserRepository { + constructor(private readonly db: PrismaClient) {} + + async findById(id: string): Promise<User | null> { + return this.db.user.findUnique({ + where: { id }, + include: { + profile: true, + organization: true, + roles: { include: { permissions: true } }, + }, + }); + } + + async findByEmail(email: string): Promise<User | null> { + return this.db.user.findUnique({ where: { email } }); + } + + async create(data: CreateUserInput): Promise<User> { + return this.db.user.create({ + data: { ...data, createdAt: new Date(), updatedAt: new Date() }, + }); + } +} +``` + +### Migration Rules + +- Never modify existing migrations +- Always create a new migration for schema changes +- Name migrations descriptively: add-user-organization-relation +- Test migrations on a fresh database before committing +- Include both up and down migrations +- Never drop columns in production without a deprecation period + +## Testing Requirements + +All code must have tests. Minimum coverage is 80% for lines +and 75% for branches. These thresholds are enforced in CI. + +### Unit Tests + +Unit tests must be colocated with source files: + +```typescript +import { describe, it, expect, vi } from 'vitest'; +import { UserService } from './user-service'; + +describe('UserService', () => { + describe('createUser', () => { + it('should create a user with valid input', async () => { + const mockRepo = { + create: vi.fn().mockResolvedValue({ + id: 'user-1', + name: 'Test User', + email: 'test@example.com', + }), + findByEmail: vi.fn().mockResolvedValue(null), + }; + const service = new UserService(mockRepo as any); + const result = await service.createUser({ + name: 'Test User', + email: 'test@example.com', + }); + expect(result.id).toBe('user-1'); + expect(mockRepo.create).toHaveBeenCalledOnce(); + }); + + it('should reject duplicate emails', async () => { + const mockRepo = { + findByEmail: vi.fn().mockResolvedValue({ id: 'existing' }), + }; + const service = new UserService(mockRepo as any); + await expect( + service.createUser({ name: 'X', email: 'dup@example.com' }) + ).rejects.toThrow(/duplicate/i); + }); + }); +}); +``` + +### Integration Tests + +Integration tests must use the test database. Always seed data +in beforeEach and clean up in afterEach. Never rely on test ordering. + +## Security Policies + +### Authentication + +All endpoints except /health and /docs require authentication. +Use the authMiddleware on every router: + +```typescript +import { authMiddleware } from '../middleware/auth'; +import { rbacMiddleware } from '../middleware/rbac'; + +const router = Router(); +router.use(authMiddleware); + +router.get('/admin/users', rbacMiddleware('admin'), listUsersHandler); +router.post( + '/users/:id/deactivate', + rbacMiddleware('admin', 'manager'), + deactivateUserHandler +); +``` + +### Secrets Management + +- Never hardcode secrets in source code +- Never commit .env files +- Use AWS Secrets Manager for production secrets +- Use .env.example to document required variables +- Rotate secrets every 90 days +- Never log secrets or tokens, even partially +- Never include secrets in error messages +- Never pass secrets as URL query parameters +- Never store secrets in localStorage or cookies +- All secrets must be loaded at startup, not on demand + +## Deployment Procedures + +Deployments go through three environments: staging, canary, +and production. Each must pass health checks before promotion. + +```bash +# Deploy to staging +npm run deploy -- --env staging --service api-gateway +npm run healthcheck -- --env staging --timeout 60 + +# Promote to canary (10% traffic) +npm run deploy -- --env canary --service api-gateway +npm run healthcheck -- --env canary --timeout 120 +npm run smoke-test -- --env canary + +# Promote to production +npm run deploy -- --env production --service api-gateway +npm run healthcheck -- --env production --timeout 180 +npm run smoke-test -- --env production +npm run notify -- --channel deployments --status success +``` + +### Rollback Procedures + +If any health check fails, immediately roll back: + +```bash +npm run rollback -- --env production --service api-gateway +npm run notify -- --channel incidents --status rollback +``` + +## Error Handling + +All services must use the shared AppError class hierarchy. +Never throw plain Error objects. Never swallow errors silently. +Always include context in error messages. Always log errors with +structured metadata including requestId, userId, and service name. +Never expose internal error details to API consumers. Map all +internal errors to appropriate HTTP status codes. Use 400 for +validation errors, 401 for authentication, 403 for authorization, +404 for not found, and 500 for unexpected server errors. + +```typescript +export class AppError extends Error { + constructor( + message: string, diff --git a/core/structure/instruction-file-size-limit/tests/pass/CLAUDE.md b/core/structure/instruction-file-size-limit/tests/pass/CLAUDE.md new file mode 100644 index 0000000..f3cd723 --- /dev/null +++ b/core/structure/instruction-file-size-limit/tests/pass/CLAUDE.md @@ -0,0 +1,40 @@ +# MyApp + +Real-time collaboration platform built on WebSockets and React. + +## Tech Stack + +- TypeScript, React, Node.js +- PostgreSQL, Redis +- Docker, Kubernetes + +## Commands + +- `npm test` — run unit tests +- `npm run e2e` — run end-to-end tests +- `npm run build` — production build +- `npm run lint` — check code style + +## Structure + +``` +src/ + api/ # REST endpoints + ws/ # WebSocket handlers + models/ # Database models + services/ # Business logic +tests/ + unit/ # Unit tests + e2e/ # End-to-end tests +``` + +## Testing + +Use Jest for unit tests. Name test files `*.test.ts`. +Run `npm test -- --watch` during development. + +## Constraints + +- Never commit .env files +- Always use parameterized queries +- Keep API responses under 100ms diff --git a/core/structure/instruction-file-version-controlled/rule.md b/core/structure/instruction-file-version-controlled/rule.md new file mode 100644 index 0000000..fec2ac0 --- /dev/null +++ b/core/structure/instruction-file-version-controlled/rule.md @@ -0,0 +1,43 @@ +--- +id: "CORE:S:0003" +slug: instruction-file-version-controlled +title: Instruction File Is Version Controlled +category: structure +type: mechanical +level: L1 +backed_by: +- claude-code-settings +- claude-md-guide +- dometrain-claude-md-guide +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0003:check:0001" + type: mechanical + check: git_tracked + severity: critical +question: "Is every instruction file tracked by version control (git)?" +criteria: +- Every recognized instruction file is tracked in the git index +- The file appears in `git ls-files` output +- The file is not listed as untracked or ignored by git +--- + +# Instruction File Is Version Controlled + +Every instruction file must be tracked by version control. + +## Pass / Fail + +**Pass:** The CLAUDE.md file at the project root is tracked by git. Running +`git ls-files --error-unmatch CLAUDE.md` exits with code 0. The file +appears in `git status` as tracked (not under "Untracked files"). +**Fail:** A CLAUDE.md file exists at the project root but is listed under +"Untracked files" in `git status`. The file was created locally but +never staged or committed. Team members pulling the repo do not receive it. + +## Limitations + +Cannot detect files that were committed but later removed from tracking +via `git rm --cached` while still present on disk. The check queries +current git index state only. Also cannot verify the file is on the +default branch — it may be tracked only on a feature branch. diff --git a/core/structure/instruction-file-version-controlled/rule.yml b/core/structure/instruction-file-version-controlled/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/instruction-file-version-controlled/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/instruction-file-version-controlled/tests/fail/README.md b/core/structure/instruction-file-version-controlled/tests/fail/README.md new file mode 100644 index 0000000..1af1058 --- /dev/null +++ b/core/structure/instruction-file-version-controlled/tests/fail/README.md @@ -0,0 +1,3 @@ +# No Git Tracking + +This directory has no .git marker and no instruction files tracked in version control. diff --git a/core/structure/instruction-file-version-controlled/tests/pass/.git_marker b/core/structure/instruction-file-version-controlled/tests/pass/.git_marker new file mode 100644 index 0000000..2ed04e7 --- /dev/null +++ b/core/structure/instruction-file-version-controlled/tests/pass/.git_marker @@ -0,0 +1 @@ +Test fixture marker — stands in for .git which cannot be tracked by git. diff --git a/core/structure/instruction-file-version-controlled/tests/pass/CLAUDE.md b/core/structure/instruction-file-version-controlled/tests/pass/CLAUDE.md new file mode 100644 index 0000000..12f6947 --- /dev/null +++ b/core/structure/instruction-file-version-controlled/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Web application built with Django. + +## Commands + +- `python manage.py test` — run tests diff --git a/core/structure/local-files-not-committed/rule.md b/core/structure/local-files-not-committed/rule.md new file mode 100644 index 0000000..da468bf --- /dev/null +++ b/core/structure/local-files-not-committed/rule.md @@ -0,0 +1,50 @@ +--- +id: "CORE:S:0009" +slug: local-files-not-committed +title: Local Instruction Files Not Committed +category: structure +type: mechanical +level: L2 +backed_by: +- claude-code-memory +- claude-code-settings +- claude-md-guide +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0009:check:0001" + type: mechanical + check: file_count + args: + pattern: "**/*.local.md" + max: 0 + severity: high +question: "Do any local instruction files (.local variants) exist in the project tree?" +criteria: +- No file matching the *.local.md pattern exists anywhere in the project tree +- Local file patterns include CLAUDE.local.md and similar .local.md variants +- Local files are developer-specific and should not be present in shared project + trees +--- + +# Local Instruction Files Not Committed + +Local instruction files (.local variants) should not exist in the project tree. + +## Pass / Fail + +**Pass:** The project contains no files matching `**/*.local.md`. Developers +keep local instruction files outside the project tree, or the project has +never used local overrides. The file count check finds zero matches. +**Fail:** A file matching `**/*.local.md` exists in the project tree (e.g., +CLAUDE.local.md in the project root). The file count check finds one or more +matches, exceeding the maximum of zero. Local files risk being shared with +other developers or committed to version control. + +## Limitations + +Checks for file existence via glob pattern matching, not git tracking status. +A local file that exists on disk but is properly gitignored will still trigger +this rule. Git-tracking verification (via `git ls-files`) would require +runtime shell access, which the fixture-based test harness cannot provide. +Cannot detect local files with non-standard names outside the `*.local.md` +pattern. diff --git a/core/structure/local-files-not-committed/rule.yml b/core/structure/local-files-not-committed/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/local-files-not-committed/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/local-files-not-committed/tests/fail/CLAUDE.local.md b/core/structure/local-files-not-committed/tests/fail/CLAUDE.local.md new file mode 100644 index 0000000..e3f6108 --- /dev/null +++ b/core/structure/local-files-not-committed/tests/fail/CLAUDE.local.md @@ -0,0 +1,14 @@ +# Local Overrides + +My personal preferences for this project. + +## Editor Settings + +- Use 4-space indentation +- Enable auto-format on save +- Preferred theme: dark mode + +## Personal Notes + +- Ask Sarah about the auth module before refactoring +- The staging server is at 10.0.1.42 diff --git a/core/structure/local-files-not-committed/tests/fail/CLAUDE.md b/core/structure/local-files-not-committed/tests/fail/CLAUDE.md new file mode 100644 index 0000000..ec7847d --- /dev/null +++ b/core/structure/local-files-not-committed/tests/fail/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Project with no gitignore for local files. + +## Commands + +- `npm test` — run tests diff --git a/core/structure/local-files-not-committed/tests/pass/.gitignore b/core/structure/local-files-not-committed/tests/pass/.gitignore new file mode 100644 index 0000000..a32bdfd --- /dev/null +++ b/core/structure/local-files-not-committed/tests/pass/.gitignore @@ -0,0 +1,2 @@ +CLAUDE.local.md +.claude/*.local.* diff --git a/core/structure/local-files-not-committed/tests/pass/CLAUDE.md b/core/structure/local-files-not-committed/tests/pass/CLAUDE.md new file mode 100644 index 0000000..d552c26 --- /dev/null +++ b/core/structure/local-files-not-committed/tests/pass/CLAUDE.md @@ -0,0 +1,7 @@ +# MyApp + +Project with proper local file exclusions. + +## Commands + +- `npm test` — run tests diff --git a/core/structure/mcp-servers-documented/rule.md b/core/structure/mcp-servers-documented/rule.md new file mode 100644 index 0000000..55c6fbd --- /dev/null +++ b/core/structure/mcp-servers-documented/rule.md @@ -0,0 +1,57 @@ +--- +id: "CORE:S:0011" +slug: mcp-servers-documented +title: MCP Servers Documented +category: structure +type: deterministic +level: L6 +backed_by: +- claude-code-settings +- dometrain-claude-md-guide +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0011:check:0001" + type: mechanical + check: file_exists + args: + path: ".mcp.json" + severity: medium +- id: "CORE:S:0011:check:0002" + type: deterministic + negate: true + severity: medium +question: "If MCP server configuration exists, do the instruction files document their + usage?" +criteria: +- An MCP configuration file (.mcp.json or equivalent) exists in the project +- At least one instruction file contains documentation referencing MCP servers + or tools +- The MCP documentation describes purpose or usage guidance for the configured + servers +- The rule is not applicable if no MCP configuration file exists +--- + +# MCP Servers Documented + +If MCP server configuration exists, the instruction files must document MCP server usage. + +## Pass / Fail + +**Pass:** A project has .mcp.json defining a PostgreSQL MCP server and a GitHub MCP +server. The CLAUDE.md file contains a section "## Available Tools" or +"## MCP Servers" that explains: "Use the postgres MCP server for database +queries. Use the github MCP server for issue management. Do not use MCP +servers for tasks that can be done with standard CLI tools." +**Fail:** A project has .mcp.json with three MCP server configurations. None of the +instruction files (CLAUDE.md, .claude/rules/*.md) mention MCP, tools, or +servers. The agent discovers MCP servers at runtime but has no guidance on +when or how to use them. + +## Limitations + +Cannot verify that the documentation accurately describes the configured +MCP servers. A mention of "MCP" in any context (even unrelated) in the +instruction file would satisfy the pattern check. Cannot assess whether the +documentation provides sufficient detail for the agent to use the servers +correctly. Only triggers when .mcp.json or equivalent config exists — +projects without MCP config are not evaluated. diff --git a/core/structure/mcp-servers-documented/rule.yml b/core/structure/mcp-servers-documented/rule.yml new file mode 100644 index 0000000..cf15c15 --- /dev/null +++ b/core/structure/mcp-servers-documented/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.S.0011.check.0002" + message: "MCP server documentation found in instruction file" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)\\bMCP\\b" + paths: + include: + - "{{instruction_files}}" diff --git a/core/structure/mcp-servers-documented/tests/fail/CLAUDE.md b/core/structure/mcp-servers-documented/tests/fail/CLAUDE.md new file mode 100644 index 0000000..8d0c77d --- /dev/null +++ b/core/structure/mcp-servers-documented/tests/fail/CLAUDE.md @@ -0,0 +1,8 @@ +# MyApp + +Data analytics platform. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build diff --git a/core/structure/mcp-servers-documented/tests/pass/.mcp.json b/core/structure/mcp-servers-documented/tests/pass/.mcp.json new file mode 100644 index 0000000..6f0c34a --- /dev/null +++ b/core/structure/mcp-servers-documented/tests/pass/.mcp.json @@ -0,0 +1 @@ +{"mcpServers": {"filesystem": {"command": "npx", "args": ["-y", "@anthropic/mcp-filesystem"]}}} \ No newline at end of file diff --git a/core/structure/mcp-servers-documented/tests/pass/CLAUDE.md b/core/structure/mcp-servers-documented/tests/pass/CLAUDE.md new file mode 100644 index 0000000..b87f9bb --- /dev/null +++ b/core/structure/mcp-servers-documented/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Data analytics platform. + +## MCP Servers + +- **postgres-mcp**: Query the analytics database. Use for read-only data exploration. +- **slack-mcp**: Post deployment notifications to #releases channel. + +## Commands + +- `npm test` — run tests diff --git a/core/structure/no-sensitive-information/rule.md b/core/structure/no-sensitive-information/rule.md new file mode 100644 index 0000000..e8a4201 --- /dev/null +++ b/core/structure/no-sensitive-information/rule.md @@ -0,0 +1,53 @@ +--- +id: "CORE:S:0004" +slug: no-sensitive-information +title: No Sensitive Information in Instruction Files +category: structure +type: deterministic +level: L2 +backed_by: +- dometrain-claude-md-guide +- spec-writing-for-agents +- using-claude-md-files +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0004:check:0001" + type: deterministic + severity: high +question: "Do any instruction files contain secrets, API keys, credentials, or connection + strings?" +criteria: +- No instruction file contains strings matching common API key patterns (AWS, + GitHub, Stripe, OpenAI, etc.) +- No instruction file contains database connection strings with embedded + credentials +- No instruction file contains base64-encoded tokens longer than 40 characters +- No instruction file contains private key material (BEGIN RSA PRIVATE KEY, + etc.) +- No instruction file contains password assignments (password=, passwd=, + secret=) +--- + +# No Sensitive Information in Instruction Files + +No instruction file may contain secrets, API keys, credentials, or connection strings. + +## Pass / Fail + +**Pass:** A CLAUDE.md file references environment variables by name ("Use $DATABASE_URL +for connections") or refers to a secrets manager ("API keys are stored in +AWS Secrets Manager") without including the actual values. The file contains +no patterns matching API key formats, no base64-encoded tokens, and no +connection strings with embedded passwords. +**Fail:** A CLAUDE.md file contains the line "Use this API key for testing: +sk-proj-abc123def456ghi789". Or it includes a database connection string +like "postgresql://admin:p4ssw0rd@db.example.com:5432/production". Or it +embeds an AWS access key "AKIAIOSFODNN7EXAMPLE". + +## Limitations + +Pattern matching produces false positives on example/placeholder values, +documentation about secret formats, and strings that coincidentally match +secret patterns (e.g., long base64 strings in code examples). Cannot detect +secrets in custom or proprietary formats that do not match known patterns. +Cannot distinguish between a real secret and a deliberately redacted example. diff --git a/core/structure/no-sensitive-information/rule.yml b/core/structure/no-sensitive-information/rule.yml new file mode 100644 index 0000000..68d8720 --- /dev/null +++ b/core/structure/no-sensitive-information/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.S.0004.check.0001" + message: "Possible secret or credential detected in instruction file" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(api[_-]?key|secret[_-]?key|password|token|credential)\\s*[=:]\\s*['\"]?[A-Za-z0-9+/=_-]{8,}" + paths: + include: + - "{{instruction_files}}" diff --git a/core/structure/no-sensitive-information/tests/fail/CLAUDE.md b/core/structure/no-sensitive-information/tests/fail/CLAUDE.md new file mode 100644 index 0000000..05a5ca4 --- /dev/null +++ b/core/structure/no-sensitive-information/tests/fail/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +API platform built with Express. + +## Configuration + +DATABASE_URL=postgres://admin:s3cretP4ssw0rd@db.example.com:5432/myapp +API_KEY = supersecretvalue1234567890abc + +## Commands + +- `npm test` — run tests diff --git a/core/structure/no-sensitive-information/tests/pass/CLAUDE.md b/core/structure/no-sensitive-information/tests/pass/CLAUDE.md new file mode 100644 index 0000000..54f274e --- /dev/null +++ b/core/structure/no-sensitive-information/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +API platform built with Express. + +## Configuration + +Database credentials are stored in .env (not committed). +See .env.example for required environment variables. + +## Commands + +- `npm test` — run tests diff --git a/core/structure/reusable-skills-over-repeated-prompts/rule.md b/core/structure/reusable-skills-over-repeated-prompts/rule.md new file mode 100644 index 0000000..be9dba3 --- /dev/null +++ b/core/structure/reusable-skills-over-repeated-prompts/rule.md @@ -0,0 +1,56 @@ +--- +id: "CORE:S:0012" +slug: reusable-skills-over-repeated-prompts +title: Reusable Skills Over Repeated Prompts +category: structure +type: semantic +level: L6 +backed_by: +- dometrain-claude-md-guide +- osmani-ai-coding-workflow +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0012:check:0001" + type: deterministic + severity: medium +- id: "CORE:S:0012:check:0002" + type: semantic + prompt: "Are repeatable multi-step procedures extracted into reusable skills rather than inlined in instruction files?" + severity: medium +question: "Are repeatable multi-step procedures extracted into reusable skills rather + than inlined?" +criteria: +- No instruction file contains inline numbered procedures exceeding 10 steps +- Multi-step workflows reference skill files rather than embedding full + procedures +- A skills directory exists if the instruction file references workflow-like + operations +- Repeated procedural content across instruction files is consolidated into a + single skill +--- + +# Reusable Skills Over Repeated Prompts + +Repeatable multi-step procedures in instruction files should be extracted into reusable skills. + +## Pass / Fail + +**Pass:** A CLAUDE.md file says "For deployment, use the /deploy skill" and the +detailed deployment procedure lives in .claude/skills/deploy/SKILL.md with +step-by-step instructions. The root instruction file references the skill +rather than inlining the procedure. Common workflows (testing, releasing, +reviewing) are similarly extracted into skill files. +**Fail:** A CLAUDE.md file contains three inline multi-step procedures: a 25-line +deployment checklist, a 20-line release workflow, and a 15-line review +process — all written as numbered prose steps directly in the file. No +skills directory exists. The same deployment steps are also repeated in +.claude/rules/ops.md with slight variations. + +## Limitations + +Requires semantic evaluation (LLM judgment) to determine whether an inline +procedure is genuinely repeatable and would benefit from extraction versus +being a one-off instruction. Cannot establish a bright-line threshold for +"multi-step" — a 3-step process may or may not warrant skill extraction. +Cannot detect procedures that should exist as skills but are simply absent +from the instruction file entirely. diff --git a/core/structure/reusable-skills-over-repeated-prompts/rule.yml b/core/structure/reusable-skills-over-repeated-prompts/rule.yml new file mode 100644 index 0000000..e8cb19c --- /dev/null +++ b/core/structure/reusable-skills-over-repeated-prompts/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.S.0012.check.0001" + message: "Multi-step procedure found inline" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(first .+ then .+ then|step [0-9]|1\\.|2\\.|3\\.)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/structure/reusable-skills-over-repeated-prompts/tests/fail/CLAUDE.md b/core/structure/reusable-skills-over-repeated-prompts/tests/fail/CLAUDE.md new file mode 100644 index 0000000..b863022 --- /dev/null +++ b/core/structure/reusable-skills-over-repeated-prompts/tests/fail/CLAUDE.md @@ -0,0 +1,17 @@ +# MyApp + +Project with inline procedures. + +## Deployment + +When deploying, first run the test suite, then build the Docker image, +then push to the registry, then update the Kubernetes deployment, +then verify the health checks pass. + +Step 1. Run tests +Step 2. Build Docker image +Step 3. Push to registry + +## Commands + +- `npm test` — run tests diff --git a/core/structure/reusable-skills-over-repeated-prompts/tests/pass/CLAUDE.md b/core/structure/reusable-skills-over-repeated-prompts/tests/pass/CLAUDE.md new file mode 100644 index 0000000..dc10ff0 --- /dev/null +++ b/core/structure/reusable-skills-over-repeated-prompts/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Project with skill-based workflows. + +## Skills + +- `/deploy` — see .claude/skills/deploy/SKILL.md for deployment procedure +- `/release` — see .claude/skills/release/SKILL.md for release process + +## Commands + +- `npm test` — run tests diff --git a/core/structure/scope-hierarchy-documented/rule.md b/core/structure/scope-hierarchy-documented/rule.md new file mode 100644 index 0000000..68af4e8 --- /dev/null +++ b/core/structure/scope-hierarchy-documented/rule.md @@ -0,0 +1,49 @@ +--- +id: "CORE:S:0008" +slug: scope-hierarchy-documented +title: Scope Hierarchy Documented +category: structure +type: deterministic +level: L4 +backed_by: +- claude-code-memory +- claude-code-settings +- codex-agent-loop +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0008:check:0001" + type: deterministic + negate: true + severity: medium +question: "Do the instruction files document or reference the scope precedence hierarchy?" +criteria: +- At least one instruction file contains a section or paragraph describing scope + precedence +- The documentation mentions override behavior (more specific overrides broader) +- Keywords indicating hierarchy are present (e.g., precedence, override, + hierarchy, scope, priority) +- The hierarchy documentation appears in a structurally prominent location + (heading or dedicated section) +--- + +# Scope Hierarchy Documented + +Instruction files in a multi-file system must document or respect the scope precedence hierarchy. + +## Pass / Fail + +**Pass:** A CLAUDE.md file contains a section titled "## Instruction Hierarchy" or +"## Scope Precedence" that explains: "Project-level rules in .claude/rules/ +override general guidance in this file. Local overrides in CLAUDE.local.md +take highest precedence." The hierarchy is explicitly stated. +**Fail:** A project has CLAUDE.md, three .claude/rules/ files, and nested CLAUDE.md +files in subdirectories. None of the files mention which takes precedence. +A rule in .claude/rules/style.md contradicts guidance in the root CLAUDE.md, +and there is no documentation of which instruction wins. + +## Limitations + +Pattern-based detection can only check for the presence of hierarchy-related +keywords and section headings. Cannot verify that the documented hierarchy +is correct or matches the agent runtime's actual precedence behavior. A file +that mentions "precedence" in an unrelated context may produce a false positive. diff --git a/core/structure/scope-hierarchy-documented/rule.yml b/core/structure/scope-hierarchy-documented/rule.yml new file mode 100644 index 0000000..8e4331b --- /dev/null +++ b/core/structure/scope-hierarchy-documented/rule.yml @@ -0,0 +1,9 @@ +rules: + - id: "CORE.S.0008.check.0001" + message: "Scope or hierarchy documentation found" + severity: WARNING + languages: [generic] + pattern-regex: "(?i)(scope|precedence|hierarchy|override|inherit|parent|child)" + paths: + include: + - "{{instruction_files}}" diff --git a/core/structure/scope-hierarchy-documented/tests/fail/CLAUDE.md b/core/structure/scope-hierarchy-documented/tests/fail/CLAUDE.md new file mode 100644 index 0000000..e86c7e2 --- /dev/null +++ b/core/structure/scope-hierarchy-documented/tests/fail/CLAUDE.md @@ -0,0 +1,8 @@ +# MyApp + +Monorepo with multiple CLAUDE.md files. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build diff --git a/core/structure/scope-hierarchy-documented/tests/pass/CLAUDE.md b/core/structure/scope-hierarchy-documented/tests/pass/CLAUDE.md new file mode 100644 index 0000000..f1c85e3 --- /dev/null +++ b/core/structure/scope-hierarchy-documented/tests/pass/CLAUDE.md @@ -0,0 +1,12 @@ +# MyApp + +Monorepo with instruction hierarchy. + +## Scope + +Root CLAUDE.md provides universal rules. Service-specific CLAUDE.md files override for their directory. +Child rules take precedence over parent rules when there is a conflict. + +## Commands + +- `npm test` — run tests diff --git a/core/structure/total-instruction-budget/rule.md b/core/structure/total-instruction-budget/rule.md new file mode 100644 index 0000000..3339519 --- /dev/null +++ b/core/structure/total-instruction-budget/rule.md @@ -0,0 +1,52 @@ +--- +id: "CORE:S:0006" +slug: total-instruction-budget +title: Total Instruction Budget +category: structure +type: mechanical +level: L2 +backed_by: +- codex-agent-loop +- codex-agents-md +- monorepo-claude-md-organization +targets: '{{instruction_files}}' +checks: +- id: "CORE:S:0006:check:0001" + type: mechanical + check: aggregate_byte_size + args: + pattern: "{{instruction_files}}" + max: 32768 + severity: high +question: "Does the combined size of all instruction files stay within the instruction + budget?" +criteria: +- The sum of byte sizes across all instruction files is at most 32,768 bytes (32 + KiB) +- All files resolved from the instruction_files template variable are included + in the sum +- The check aggregates across the full instruction file set, not per-file +--- + +# Total Instruction Budget + +The combined size of all instruction files must stay within the agent's instruction budget. + +## Pass / Fail + +**Pass:** A project has CLAUDE.md (8 KiB), .claude/rules/testing.md (2 KiB), and +.claude/rules/style.md (1.5 KiB). The combined total is 11.5 KiB, well +under the 32 KiB ceiling. Word count is approximately 2,000 words, under +the 10k word ideal. +**Fail:** A monorepo has a root CLAUDE.md (12 KiB), three nested CLAUDE.md files +(6 KiB each), and eight .claude/rules/ files (2 KiB each). The combined +total is 46 KiB, exceeding the 32 KiB Codex limit. The agent silently +stops loading files after the budget is exhausted. + +## Limitations + +The 32 KiB limit is Codex-specific; Claude Code does not enforce a hard +byte ceiling (though performance degrades). The check uses byte size as the +metric, but actual context consumption depends on tokenization. Cannot +predict which files the agent will drop when the budget is exceeded — that +is runtime-specific behavior. diff --git a/core/structure/total-instruction-budget/rule.yml b/core/structure/total-instruction-budget/rule.yml new file mode 100644 index 0000000..14ba58b --- /dev/null +++ b/core/structure/total-instruction-budget/rule.yml @@ -0,0 +1 @@ +rules: [] diff --git a/core/structure/total-instruction-budget/tests/fail/CLAUDE.md b/core/structure/total-instruction-budget/tests/fail/CLAUDE.md new file mode 100644 index 0000000..055773f --- /dev/null +++ b/core/structure/total-instruction-budget/tests/fail/CLAUDE.md @@ -0,0 +1,2083 @@ +# MyApp + +Extremely verbose instruction file that exceeds reasonable byte size budget. + +## Section 0: Configuration Area 0 + +This section describes detailed configuration and operational procedures for area 0 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_0_TIMEOUT`: Connection timeout for service 0 (default: 30s) +- `CONFIG_0_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_0_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_0_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 1: Configuration Area 1 + +This section describes detailed configuration and operational procedures for area 1 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_1_TIMEOUT`: Connection timeout for service 1 (default: 30s) +- `CONFIG_1_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_1_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_1_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 2: Configuration Area 2 + +This section describes detailed configuration and operational procedures for area 2 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_2_TIMEOUT`: Connection timeout for service 2 (default: 30s) +- `CONFIG_2_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_2_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_2_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 3: Configuration Area 3 + +This section describes detailed configuration and operational procedures for area 3 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_3_TIMEOUT`: Connection timeout for service 3 (default: 30s) +- `CONFIG_3_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_3_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_3_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 4: Configuration Area 4 + +This section describes detailed configuration and operational procedures for area 4 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_4_TIMEOUT`: Connection timeout for service 4 (default: 30s) +- `CONFIG_4_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_4_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_4_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 5: Configuration Area 5 + +This section describes detailed configuration and operational procedures for area 5 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_5_TIMEOUT`: Connection timeout for service 5 (default: 30s) +- `CONFIG_5_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_5_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_5_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 6: Configuration Area 6 + +This section describes detailed configuration and operational procedures for area 6 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_6_TIMEOUT`: Connection timeout for service 6 (default: 30s) +- `CONFIG_6_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_6_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_6_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 7: Configuration Area 7 + +This section describes detailed configuration and operational procedures for area 7 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_7_TIMEOUT`: Connection timeout for service 7 (default: 30s) +- `CONFIG_7_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_7_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_7_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 8: Configuration Area 8 + +This section describes detailed configuration and operational procedures for area 8 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_8_TIMEOUT`: Connection timeout for service 8 (default: 30s) +- `CONFIG_8_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_8_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_8_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 9: Configuration Area 9 + +This section describes detailed configuration and operational procedures for area 9 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_9_TIMEOUT`: Connection timeout for service 9 (default: 30s) +- `CONFIG_9_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_9_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_9_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 10: Configuration Area 10 + +This section describes detailed configuration and operational procedures for area 10 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_10_TIMEOUT`: Connection timeout for service 10 (default: 30s) +- `CONFIG_10_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_10_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_10_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 11: Configuration Area 11 + +This section describes detailed configuration and operational procedures for area 11 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_11_TIMEOUT`: Connection timeout for service 11 (default: 30s) +- `CONFIG_11_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_11_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_11_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 12: Configuration Area 12 + +This section describes detailed configuration and operational procedures for area 12 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_12_TIMEOUT`: Connection timeout for service 12 (default: 30s) +- `CONFIG_12_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_12_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_12_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 13: Configuration Area 13 + +This section describes detailed configuration and operational procedures for area 13 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_13_TIMEOUT`: Connection timeout for service 13 (default: 30s) +- `CONFIG_13_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_13_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_13_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 14: Configuration Area 14 + +This section describes detailed configuration and operational procedures for area 14 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_14_TIMEOUT`: Connection timeout for service 14 (default: 30s) +- `CONFIG_14_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_14_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_14_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 15: Configuration Area 15 + +This section describes detailed configuration and operational procedures for area 15 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_15_TIMEOUT`: Connection timeout for service 15 (default: 30s) +- `CONFIG_15_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_15_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_15_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 16: Configuration Area 16 + +This section describes detailed configuration and operational procedures for area 16 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_16_TIMEOUT`: Connection timeout for service 16 (default: 30s) +- `CONFIG_16_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_16_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_16_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 17: Configuration Area 17 + +This section describes detailed configuration and operational procedures for area 17 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_17_TIMEOUT`: Connection timeout for service 17 (default: 30s) +- `CONFIG_17_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_17_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_17_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 18: Configuration Area 18 + +This section describes detailed configuration and operational procedures for area 18 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_18_TIMEOUT`: Connection timeout for service 18 (default: 30s) +- `CONFIG_18_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_18_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_18_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 19: Configuration Area 19 + +This section describes detailed configuration and operational procedures for area 19 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_19_TIMEOUT`: Connection timeout for service 19 (default: 30s) +- `CONFIG_19_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_19_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_19_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 20: Configuration Area 20 + +This section describes detailed configuration and operational procedures for area 20 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_20_TIMEOUT`: Connection timeout for service 20 (default: 30s) +- `CONFIG_20_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_20_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_20_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 21: Configuration Area 21 + +This section describes detailed configuration and operational procedures for area 21 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_21_TIMEOUT`: Connection timeout for service 21 (default: 30s) +- `CONFIG_21_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_21_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_21_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 22: Configuration Area 22 + +This section describes detailed configuration and operational procedures for area 22 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_22_TIMEOUT`: Connection timeout for service 22 (default: 30s) +- `CONFIG_22_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_22_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_22_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 23: Configuration Area 23 + +This section describes detailed configuration and operational procedures for area 23 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_23_TIMEOUT`: Connection timeout for service 23 (default: 30s) +- `CONFIG_23_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_23_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_23_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 24: Configuration Area 24 + +This section describes detailed configuration and operational procedures for area 24 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_24_TIMEOUT`: Connection timeout for service 24 (default: 30s) +- `CONFIG_24_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_24_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_24_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 25: Configuration Area 25 + +This section describes detailed configuration and operational procedures for area 25 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_25_TIMEOUT`: Connection timeout for service 25 (default: 30s) +- `CONFIG_25_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_25_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_25_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 26: Configuration Area 26 + +This section describes detailed configuration and operational procedures for area 26 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_26_TIMEOUT`: Connection timeout for service 26 (default: 30s) +- `CONFIG_26_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_26_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_26_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 27: Configuration Area 27 + +This section describes detailed configuration and operational procedures for area 27 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_27_TIMEOUT`: Connection timeout for service 27 (default: 30s) +- `CONFIG_27_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_27_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_27_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 28: Configuration Area 28 + +This section describes detailed configuration and operational procedures for area 28 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_28_TIMEOUT`: Connection timeout for service 28 (default: 30s) +- `CONFIG_28_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_28_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_28_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 29: Configuration Area 29 + +This section describes detailed configuration and operational procedures for area 29 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_29_TIMEOUT`: Connection timeout for service 29 (default: 30s) +- `CONFIG_29_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_29_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_29_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 30: Configuration Area 30 + +This section describes detailed configuration and operational procedures for area 30 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_30_TIMEOUT`: Connection timeout for service 30 (default: 30s) +- `CONFIG_30_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_30_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_30_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 31: Configuration Area 31 + +This section describes detailed configuration and operational procedures for area 31 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_31_TIMEOUT`: Connection timeout for service 31 (default: 30s) +- `CONFIG_31_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_31_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_31_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 32: Configuration Area 32 + +This section describes detailed configuration and operational procedures for area 32 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_32_TIMEOUT`: Connection timeout for service 32 (default: 30s) +- `CONFIG_32_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_32_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_32_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 33: Configuration Area 33 + +This section describes detailed configuration and operational procedures for area 33 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_33_TIMEOUT`: Connection timeout for service 33 (default: 30s) +- `CONFIG_33_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_33_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_33_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 34: Configuration Area 34 + +This section describes detailed configuration and operational procedures for area 34 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_34_TIMEOUT`: Connection timeout for service 34 (default: 30s) +- `CONFIG_34_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_34_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_34_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 35: Configuration Area 35 + +This section describes detailed configuration and operational procedures for area 35 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_35_TIMEOUT`: Connection timeout for service 35 (default: 30s) +- `CONFIG_35_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_35_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_35_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 36: Configuration Area 36 + +This section describes detailed configuration and operational procedures for area 36 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_36_TIMEOUT`: Connection timeout for service 36 (default: 30s) +- `CONFIG_36_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_36_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_36_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 37: Configuration Area 37 + +This section describes detailed configuration and operational procedures for area 37 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_37_TIMEOUT`: Connection timeout for service 37 (default: 30s) +- `CONFIG_37_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_37_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_37_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 38: Configuration Area 38 + +This section describes detailed configuration and operational procedures for area 38 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_38_TIMEOUT`: Connection timeout for service 38 (default: 30s) +- `CONFIG_38_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_38_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_38_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 39: Configuration Area 39 + +This section describes detailed configuration and operational procedures for area 39 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_39_TIMEOUT`: Connection timeout for service 39 (default: 30s) +- `CONFIG_39_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_39_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_39_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 40: Configuration Area 40 + +This section describes detailed configuration and operational procedures for area 40 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_40_TIMEOUT`: Connection timeout for service 40 (default: 30s) +- `CONFIG_40_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_40_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_40_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 41: Configuration Area 41 + +This section describes detailed configuration and operational procedures for area 41 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_41_TIMEOUT`: Connection timeout for service 41 (default: 30s) +- `CONFIG_41_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_41_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_41_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 42: Configuration Area 42 + +This section describes detailed configuration and operational procedures for area 42 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_42_TIMEOUT`: Connection timeout for service 42 (default: 30s) +- `CONFIG_42_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_42_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_42_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 43: Configuration Area 43 + +This section describes detailed configuration and operational procedures for area 43 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_43_TIMEOUT`: Connection timeout for service 43 (default: 30s) +- `CONFIG_43_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_43_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_43_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 44: Configuration Area 44 + +This section describes detailed configuration and operational procedures for area 44 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_44_TIMEOUT`: Connection timeout for service 44 (default: 30s) +- `CONFIG_44_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_44_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_44_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 45: Configuration Area 45 + +This section describes detailed configuration and operational procedures for area 45 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_45_TIMEOUT`: Connection timeout for service 45 (default: 30s) +- `CONFIG_45_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_45_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_45_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 46: Configuration Area 46 + +This section describes detailed configuration and operational procedures for area 46 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_46_TIMEOUT`: Connection timeout for service 46 (default: 30s) +- `CONFIG_46_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_46_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_46_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 47: Configuration Area 47 + +This section describes detailed configuration and operational procedures for area 47 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_47_TIMEOUT`: Connection timeout for service 47 (default: 30s) +- `CONFIG_47_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_47_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_47_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 48: Configuration Area 48 + +This section describes detailed configuration and operational procedures for area 48 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_48_TIMEOUT`: Connection timeout for service 48 (default: 30s) +- `CONFIG_48_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_48_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_48_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 49: Configuration Area 49 + +This section describes detailed configuration and operational procedures for area 49 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_49_TIMEOUT`: Connection timeout for service 49 (default: 30s) +- `CONFIG_49_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_49_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_49_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 50: Configuration Area 50 + +This section describes detailed configuration and operational procedures for area 50 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_50_TIMEOUT`: Connection timeout for service 50 (default: 30s) +- `CONFIG_50_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_50_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_50_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 51: Configuration Area 51 + +This section describes detailed configuration and operational procedures for area 51 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_51_TIMEOUT`: Connection timeout for service 51 (default: 30s) +- `CONFIG_51_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_51_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_51_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 52: Configuration Area 52 + +This section describes detailed configuration and operational procedures for area 52 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_52_TIMEOUT`: Connection timeout for service 52 (default: 30s) +- `CONFIG_52_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_52_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_52_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 53: Configuration Area 53 + +This section describes detailed configuration and operational procedures for area 53 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_53_TIMEOUT`: Connection timeout for service 53 (default: 30s) +- `CONFIG_53_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_53_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_53_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 54: Configuration Area 54 + +This section describes detailed configuration and operational procedures for area 54 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_54_TIMEOUT`: Connection timeout for service 54 (default: 30s) +- `CONFIG_54_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_54_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_54_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 55: Configuration Area 55 + +This section describes detailed configuration and operational procedures for area 55 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_55_TIMEOUT`: Connection timeout for service 55 (default: 30s) +- `CONFIG_55_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_55_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_55_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 56: Configuration Area 56 + +This section describes detailed configuration and operational procedures for area 56 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_56_TIMEOUT`: Connection timeout for service 56 (default: 30s) +- `CONFIG_56_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_56_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_56_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 57: Configuration Area 57 + +This section describes detailed configuration and operational procedures for area 57 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_57_TIMEOUT`: Connection timeout for service 57 (default: 30s) +- `CONFIG_57_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_57_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_57_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 58: Configuration Area 58 + +This section describes detailed configuration and operational procedures for area 58 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_58_TIMEOUT`: Connection timeout for service 58 (default: 30s) +- `CONFIG_58_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_58_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_58_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 59: Configuration Area 59 + +This section describes detailed configuration and operational procedures for area 59 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_59_TIMEOUT`: Connection timeout for service 59 (default: 30s) +- `CONFIG_59_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_59_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_59_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 60: Configuration Area 60 + +This section describes detailed configuration and operational procedures for area 60 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_60_TIMEOUT`: Connection timeout for service 60 (default: 30s) +- `CONFIG_60_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_60_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_60_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 61: Configuration Area 61 + +This section describes detailed configuration and operational procedures for area 61 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_61_TIMEOUT`: Connection timeout for service 61 (default: 30s) +- `CONFIG_61_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_61_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_61_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 62: Configuration Area 62 + +This section describes detailed configuration and operational procedures for area 62 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_62_TIMEOUT`: Connection timeout for service 62 (default: 30s) +- `CONFIG_62_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_62_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_62_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 63: Configuration Area 63 + +This section describes detailed configuration and operational procedures for area 63 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_63_TIMEOUT`: Connection timeout for service 63 (default: 30s) +- `CONFIG_63_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_63_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_63_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 64: Configuration Area 64 + +This section describes detailed configuration and operational procedures for area 64 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_64_TIMEOUT`: Connection timeout for service 64 (default: 30s) +- `CONFIG_64_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_64_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_64_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 65: Configuration Area 65 + +This section describes detailed configuration and operational procedures for area 65 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_65_TIMEOUT`: Connection timeout for service 65 (default: 30s) +- `CONFIG_65_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_65_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_65_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 66: Configuration Area 66 + +This section describes detailed configuration and operational procedures for area 66 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_66_TIMEOUT`: Connection timeout for service 66 (default: 30s) +- `CONFIG_66_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_66_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_66_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 67: Configuration Area 67 + +This section describes detailed configuration and operational procedures for area 67 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_67_TIMEOUT`: Connection timeout for service 67 (default: 30s) +- `CONFIG_67_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_67_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_67_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 68: Configuration Area 68 + +This section describes detailed configuration and operational procedures for area 68 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_68_TIMEOUT`: Connection timeout for service 68 (default: 30s) +- `CONFIG_68_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_68_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_68_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 69: Configuration Area 69 + +This section describes detailed configuration and operational procedures for area 69 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_69_TIMEOUT`: Connection timeout for service 69 (default: 30s) +- `CONFIG_69_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_69_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_69_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 70: Configuration Area 70 + +This section describes detailed configuration and operational procedures for area 70 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_70_TIMEOUT`: Connection timeout for service 70 (default: 30s) +- `CONFIG_70_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_70_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_70_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 71: Configuration Area 71 + +This section describes detailed configuration and operational procedures for area 71 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_71_TIMEOUT`: Connection timeout for service 71 (default: 30s) +- `CONFIG_71_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_71_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_71_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 72: Configuration Area 72 + +This section describes detailed configuration and operational procedures for area 72 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_72_TIMEOUT`: Connection timeout for service 72 (default: 30s) +- `CONFIG_72_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_72_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_72_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 73: Configuration Area 73 + +This section describes detailed configuration and operational procedures for area 73 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_73_TIMEOUT`: Connection timeout for service 73 (default: 30s) +- `CONFIG_73_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_73_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_73_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 74: Configuration Area 74 + +This section describes detailed configuration and operational procedures for area 74 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_74_TIMEOUT`: Connection timeout for service 74 (default: 30s) +- `CONFIG_74_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_74_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_74_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 75: Configuration Area 75 + +This section describes detailed configuration and operational procedures for area 75 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_75_TIMEOUT`: Connection timeout for service 75 (default: 30s) +- `CONFIG_75_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_75_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_75_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 76: Configuration Area 76 + +This section describes detailed configuration and operational procedures for area 76 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_76_TIMEOUT`: Connection timeout for service 76 (default: 30s) +- `CONFIG_76_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_76_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_76_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 77: Configuration Area 77 + +This section describes detailed configuration and operational procedures for area 77 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_77_TIMEOUT`: Connection timeout for service 77 (default: 30s) +- `CONFIG_77_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_77_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_77_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 78: Configuration Area 78 + +This section describes detailed configuration and operational procedures for area 78 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_78_TIMEOUT`: Connection timeout for service 78 (default: 30s) +- `CONFIG_78_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_78_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_78_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 79: Configuration Area 79 + +This section describes detailed configuration and operational procedures for area 79 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_79_TIMEOUT`: Connection timeout for service 79 (default: 30s) +- `CONFIG_79_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_79_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_79_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 80: Configuration Area 80 + +This section describes detailed configuration and operational procedures for area 80 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_80_TIMEOUT`: Connection timeout for service 80 (default: 30s) +- `CONFIG_80_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_80_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_80_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 81: Configuration Area 81 + +This section describes detailed configuration and operational procedures for area 81 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_81_TIMEOUT`: Connection timeout for service 81 (default: 30s) +- `CONFIG_81_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_81_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_81_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 82: Configuration Area 82 + +This section describes detailed configuration and operational procedures for area 82 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_82_TIMEOUT`: Connection timeout for service 82 (default: 30s) +- `CONFIG_82_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_82_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_82_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 83: Configuration Area 83 + +This section describes detailed configuration and operational procedures for area 83 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_83_TIMEOUT`: Connection timeout for service 83 (default: 30s) +- `CONFIG_83_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_83_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_83_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 84: Configuration Area 84 + +This section describes detailed configuration and operational procedures for area 84 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_84_TIMEOUT`: Connection timeout for service 84 (default: 30s) +- `CONFIG_84_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_84_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_84_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 85: Configuration Area 85 + +This section describes detailed configuration and operational procedures for area 85 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_85_TIMEOUT`: Connection timeout for service 85 (default: 30s) +- `CONFIG_85_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_85_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_85_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 86: Configuration Area 86 + +This section describes detailed configuration and operational procedures for area 86 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_86_TIMEOUT`: Connection timeout for service 86 (default: 30s) +- `CONFIG_86_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_86_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_86_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 87: Configuration Area 87 + +This section describes detailed configuration and operational procedures for area 87 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_87_TIMEOUT`: Connection timeout for service 87 (default: 30s) +- `CONFIG_87_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_87_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_87_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 88: Configuration Area 88 + +This section describes detailed configuration and operational procedures for area 88 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_88_TIMEOUT`: Connection timeout for service 88 (default: 30s) +- `CONFIG_88_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_88_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_88_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 89: Configuration Area 89 + +This section describes detailed configuration and operational procedures for area 89 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_89_TIMEOUT`: Connection timeout for service 89 (default: 30s) +- `CONFIG_89_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_89_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_89_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 90: Configuration Area 90 + +This section describes detailed configuration and operational procedures for area 90 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_90_TIMEOUT`: Connection timeout for service 90 (default: 30s) +- `CONFIG_90_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_90_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_90_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 91: Configuration Area 91 + +This section describes detailed configuration and operational procedures for area 91 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_91_TIMEOUT`: Connection timeout for service 91 (default: 30s) +- `CONFIG_91_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_91_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_91_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 92: Configuration Area 92 + +This section describes detailed configuration and operational procedures for area 92 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_92_TIMEOUT`: Connection timeout for service 92 (default: 30s) +- `CONFIG_92_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_92_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_92_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 93: Configuration Area 93 + +This section describes detailed configuration and operational procedures for area 93 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_93_TIMEOUT`: Connection timeout for service 93 (default: 30s) +- `CONFIG_93_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_93_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_93_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 94: Configuration Area 94 + +This section describes detailed configuration and operational procedures for area 94 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_94_TIMEOUT`: Connection timeout for service 94 (default: 30s) +- `CONFIG_94_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_94_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_94_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 95: Configuration Area 95 + +This section describes detailed configuration and operational procedures for area 95 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_95_TIMEOUT`: Connection timeout for service 95 (default: 30s) +- `CONFIG_95_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_95_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_95_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 96: Configuration Area 96 + +This section describes detailed configuration and operational procedures for area 96 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_96_TIMEOUT`: Connection timeout for service 96 (default: 30s) +- `CONFIG_96_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_96_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_96_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 97: Configuration Area 97 + +This section describes detailed configuration and operational procedures for area 97 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_97_TIMEOUT`: Connection timeout for service 97 (default: 30s) +- `CONFIG_97_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_97_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_97_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 98: Configuration Area 98 + +This section describes detailed configuration and operational procedures for area 98 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_98_TIMEOUT`: Connection timeout for service 98 (default: 30s) +- `CONFIG_98_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_98_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_98_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 99: Configuration Area 99 + +This section describes detailed configuration and operational procedures for area 99 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_99_TIMEOUT`: Connection timeout for service 99 (default: 30s) +- `CONFIG_99_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_99_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_99_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 100: Configuration Area 100 + +This section describes detailed configuration and operational procedures for area 100 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_100_TIMEOUT`: Connection timeout for service 100 (default: 30s) +- `CONFIG_100_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_100_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_100_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 101: Configuration Area 101 + +This section describes detailed configuration and operational procedures for area 101 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_101_TIMEOUT`: Connection timeout for service 101 (default: 30s) +- `CONFIG_101_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_101_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_101_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 102: Configuration Area 102 + +This section describes detailed configuration and operational procedures for area 102 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_102_TIMEOUT`: Connection timeout for service 102 (default: 30s) +- `CONFIG_102_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_102_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_102_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 103: Configuration Area 103 + +This section describes detailed configuration and operational procedures for area 103 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_103_TIMEOUT`: Connection timeout for service 103 (default: 30s) +- `CONFIG_103_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_103_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_103_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 104: Configuration Area 104 + +This section describes detailed configuration and operational procedures for area 104 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_104_TIMEOUT`: Connection timeout for service 104 (default: 30s) +- `CONFIG_104_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_104_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_104_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 105: Configuration Area 105 + +This section describes detailed configuration and operational procedures for area 105 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_105_TIMEOUT`: Connection timeout for service 105 (default: 30s) +- `CONFIG_105_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_105_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_105_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 106: Configuration Area 106 + +This section describes detailed configuration and operational procedures for area 106 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_106_TIMEOUT`: Connection timeout for service 106 (default: 30s) +- `CONFIG_106_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_106_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_106_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 107: Configuration Area 107 + +This section describes detailed configuration and operational procedures for area 107 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_107_TIMEOUT`: Connection timeout for service 107 (default: 30s) +- `CONFIG_107_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_107_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_107_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 108: Configuration Area 108 + +This section describes detailed configuration and operational procedures for area 108 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_108_TIMEOUT`: Connection timeout for service 108 (default: 30s) +- `CONFIG_108_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_108_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_108_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 109: Configuration Area 109 + +This section describes detailed configuration and operational procedures for area 109 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_109_TIMEOUT`: Connection timeout for service 109 (default: 30s) +- `CONFIG_109_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_109_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_109_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 110: Configuration Area 110 + +This section describes detailed configuration and operational procedures for area 110 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_110_TIMEOUT`: Connection timeout for service 110 (default: 30s) +- `CONFIG_110_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_110_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_110_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 111: Configuration Area 111 + +This section describes detailed configuration and operational procedures for area 111 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_111_TIMEOUT`: Connection timeout for service 111 (default: 30s) +- `CONFIG_111_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_111_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_111_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 112: Configuration Area 112 + +This section describes detailed configuration and operational procedures for area 112 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_112_TIMEOUT`: Connection timeout for service 112 (default: 30s) +- `CONFIG_112_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_112_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_112_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 113: Configuration Area 113 + +This section describes detailed configuration and operational procedures for area 113 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_113_TIMEOUT`: Connection timeout for service 113 (default: 30s) +- `CONFIG_113_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_113_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_113_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 114: Configuration Area 114 + +This section describes detailed configuration and operational procedures for area 114 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_114_TIMEOUT`: Connection timeout for service 114 (default: 30s) +- `CONFIG_114_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_114_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_114_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 115: Configuration Area 115 + +This section describes detailed configuration and operational procedures for area 115 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_115_TIMEOUT`: Connection timeout for service 115 (default: 30s) +- `CONFIG_115_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_115_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_115_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 116: Configuration Area 116 + +This section describes detailed configuration and operational procedures for area 116 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_116_TIMEOUT`: Connection timeout for service 116 (default: 30s) +- `CONFIG_116_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_116_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_116_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 117: Configuration Area 117 + +This section describes detailed configuration and operational procedures for area 117 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_117_TIMEOUT`: Connection timeout for service 117 (default: 30s) +- `CONFIG_117_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_117_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_117_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 118: Configuration Area 118 + +This section describes detailed configuration and operational procedures for area 118 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_118_TIMEOUT`: Connection timeout for service 118 (default: 30s) +- `CONFIG_118_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_118_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_118_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 119: Configuration Area 119 + +This section describes detailed configuration and operational procedures for area 119 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_119_TIMEOUT`: Connection timeout for service 119 (default: 30s) +- `CONFIG_119_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_119_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_119_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 120: Configuration Area 120 + +This section describes detailed configuration and operational procedures for area 120 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_120_TIMEOUT`: Connection timeout for service 120 (default: 30s) +- `CONFIG_120_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_120_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_120_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 121: Configuration Area 121 + +This section describes detailed configuration and operational procedures for area 121 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_121_TIMEOUT`: Connection timeout for service 121 (default: 30s) +- `CONFIG_121_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_121_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_121_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 122: Configuration Area 122 + +This section describes detailed configuration and operational procedures for area 122 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_122_TIMEOUT`: Connection timeout for service 122 (default: 30s) +- `CONFIG_122_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_122_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_122_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 123: Configuration Area 123 + +This section describes detailed configuration and operational procedures for area 123 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_123_TIMEOUT`: Connection timeout for service 123 (default: 30s) +- `CONFIG_123_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_123_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_123_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 124: Configuration Area 124 + +This section describes detailed configuration and operational procedures for area 124 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_124_TIMEOUT`: Connection timeout for service 124 (default: 30s) +- `CONFIG_124_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_124_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_124_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 125: Configuration Area 125 + +This section describes detailed configuration and operational procedures for area 125 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_125_TIMEOUT`: Connection timeout for service 125 (default: 30s) +- `CONFIG_125_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_125_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_125_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 126: Configuration Area 126 + +This section describes detailed configuration and operational procedures for area 126 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_126_TIMEOUT`: Connection timeout for service 126 (default: 30s) +- `CONFIG_126_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_126_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_126_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 127: Configuration Area 127 + +This section describes detailed configuration and operational procedures for area 127 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_127_TIMEOUT`: Connection timeout for service 127 (default: 30s) +- `CONFIG_127_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_127_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_127_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 128: Configuration Area 128 + +This section describes detailed configuration and operational procedures for area 128 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_128_TIMEOUT`: Connection timeout for service 128 (default: 30s) +- `CONFIG_128_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_128_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_128_POOL_SIZE`: Connection pool size for database connections (default: 10) + + +## Section 129: Configuration Area 129 + +This section describes detailed configuration and operational procedures for area 129 of the project. +All team members must follow these guidelines when working in this domain. The configuration +parameters listed below are critical for maintaining system stability and performance. Deviations +from these standards require approval from the technical lead and must be documented in the +project decision log. Regular audits ensure compliance with these standards across all environments. + +### Parameters + +- `CONFIG_129_TIMEOUT`: Connection timeout for service 129 (default: 30s) +- `CONFIG_129_RETRIES`: Maximum retry attempts for transient failures (default: 3) +- `CONFIG_129_BUFFER`: Buffer size in bytes for streaming operations (default: 8192) +- `CONFIG_129_POOL_SIZE`: Connection pool size for database connections (default: 10) + diff --git a/core/structure/total-instruction-budget/tests/pass/CLAUDE.md b/core/structure/total-instruction-budget/tests/pass/CLAUDE.md new file mode 100644 index 0000000..b906a92 --- /dev/null +++ b/core/structure/total-instruction-budget/tests/pass/CLAUDE.md @@ -0,0 +1,16 @@ +# MyApp + +Collaboration platform built with React. + +## Commands + +- `npm test` — run tests +- `npm run build` — production build + +## Structure + +``` +src/api/ # API endpoints +src/models/ # Database models +tests/ # Test suite +``` diff --git a/docs/capability-levels.md b/docs/capability-levels.md index a04a8b7..bcd8e1e 100644 --- a/docs/capability-levels.md +++ b/docs/capability-levels.md @@ -10,10 +10,10 @@ L0 (Absent) means no instruction file exists — nothing to evaluate. Levels L1 |-------|------|-----------------|----------------| | **L1** | Basic | Reviewed, tracked instruction file | Customized (not raw `/init` output), version controlled | | **L2** | Scoped | Project-specific constraints | Size limits, core sections, content quality | -| **L3** | Structured | External references, organized content | @imports, heading hierarchy, single source of truth | +| **L3** | Structured | External references, organized content | @imports, multiple files, single source of truth | | **L4** | Abstracted | Path-scoped rules, context-aware loading | .claude/rules/, hierarchical memory | -| **L5** | Maintained | Map and index maintenance discipline | Staleness prevention, backbone completeness | -| **L6** | Adaptive | Map-driven navigation, contracts | YAML backbone, component-contract binding | +| **L5** | Maintained | Structural integrity, governance, navigation | Reference validation, org policy, backbone maps | +| **L6** | Adaptive | Dynamic context, extensibility, persistence | Skills, hooks, MCP servers, memory files | > **Note:** L1-L4 patterns are documented in official sources. L5-L6 patterns are community patterns (experimental tier) derived from enterprise software practices. @@ -27,49 +27,41 @@ L0 (Absent) means no instruction file exists — nothing to evaluate. Levels L1 - Version controlled (tracked in git) - **Risk:** File exists but may lack structure or project-specific content - **Fix:** Add core sections, constraints, and project description -- **Primary rules:** CLAUDE_M1, M1 ### Level 2: Scoped - Contains core sections: stack, commands, constraints -- 30-200 lines, project-specific content quality +- Concise and focused, project-specific content quality - MUST/MUST NOT with rationale - **Risk:** Token bloat, instruction dilution as file grows - **Fix:** Extract details to @imports -- **Primary rules:** S1, S2, S3, S4, C1, C3, C5 ### Level 3: Structured - Uses @imports to external documentation -- Root file focuses on pointers, not content +- Multiple instruction-related files - Single source of truth across files - **Risk:** Import references may become stale -- **Fix:** Implement .claude/rules/ for path-scoped loading -- **Primary rules:** C2, C4, E1, E2, M2 +- **Fix:** Implement path-scoped loading for different code areas ### Level 4: Abstracted -- Implements .claude/rules/ directory -- Path-scoped rules for different code areas -- Efficiency strategies documented (reading, memory, grep) -- Root file < 100 lines +- Implements path-scoped rules (e.g., `.claude/rules/` directory) +- Different instructions load based on which files the agent works with +- Root file stays lean - **Risk:** Complexity if not well-documented - **Fix:** Add governance processes for enterprise scale -- **Primary rules:** CLAUDE_S1, CLAUDE_S2 ### Level 5: Maintained -- Map staleness prevention enforced -- Backbone index kept complete and accurate -- Structural changes tracked and validated +- References resolve, indexes are current, no orphaned files +- Organization-level governance is deployed +- Structural maps guide the agent through the codebase - **Risk:** Index drift if maintenance discipline lapses -- **Fix:** Automate backbone sync checks in CI -- **Primary rules:** M3, M4 +- **Fix:** Automate validation checks in CI ### Level 6: Adaptive -- YAML backbone (`.reporails/backbone.yml`) as complete path index -- Navigation maps for components, platform, contracts -- Session start ritual: read maps before searching -- Component-contract binding for segment-aware loading +- Agent discovers and loads context based on current task +- Capabilities extended via plugins, tool servers, hooks +- State persists across sessions (memory files, learnings) - **Risk:** Map staleness; requires maintenance discipline - **Applicability:** See "When to Use Level 6" below -- **Primary rules:** Detection-only (backbone.yml present) --- @@ -91,30 +83,46 @@ L0 (Absent) means no instruction file exists — nothing to evaluate. Levels L1 ## Capability Assessment Matrix -| Criteria | Rule | L1 | L2 | L3 | L4 | L5 | L6 | -|----------|------|----|----|----|----|----|----| -| Manually reviewed | CLAUDE_M1 | + | + | + | + | + | + | -| Size limits | S1 | - | + | + | + | + | + | -| Progressive disclosure | S2 | - | + | + | + | + | + | -| No code snippets | S3 | - | + | + | + | + | + | -| Clear markdown structure | S4 | - | + | + | + | + | + | -| Core sections present | C1 | - | + | + | + | + | + | -| Has project description | C3 | - | + | + | + | + | + | -| Has version/date | C5 | - | + | + | + | + | + | -| Single source of truth | C2 | - | - | + | + | + | + | -| Links valid | C4 | - | - | + | + | + | + | -| Code block limit | E1 | - | - | + | + | + | + | -| Import count | E2 | - | - | + | + | + | + | -| No conflicting rules | M2 | - | - | + | + | + | + | -| Version controlled | M1 | + | + | + | + | + | + | -| Hierarchical memory | CLAUDE_S1 | - | - | - | + | + | + | -| Path-scoped rules | CLAUDE_S2 | - | - | - | + | + | + | -| Map staleness prevention | M3 | - | - | - | - | + | + | -| Backbone index completeness | M4 | - | - | - | - | + | + | - -**Legend:** `+` Required | `-` Not expected - -> **Note:** Additional recommended rules available in [reporails/recommended](https://github.com/reporails/recommended). +Capabilities are structural features detected in your project. A project must have at least one capability at every level from L1 through N to qualify as level N (cumulative). + +| Capability | Level | What It Detects | +|------------|-------|-----------------| +| `instruction_file` | L1 | Non-trivial (≥10 lines), tracked instruction file exists | +| `project_constraints` | L2 | Project-specific substance: language, framework, commands, constraints | +| `size_controlled` | L2 | Instruction file is concise, not bloated | +| `external_references` | L3 | Content references files outside the primary instruction file | +| `multiple_files` | L3 | More than one instruction-related file exists | +| `path_scoping` | L4 | Different instructions load based on working file location | +| `structural_integrity` | L5 | References resolve, indexes current, no orphaned files | +| `org_policy` | L5 | Organization-level governance deployed | +| `navigation` | L5 | Structural map provides O(1) lookup (backbone, component maps) | +| `dynamic_context` | L6 | Agent discovers context based on task, not just file location | +| `extensibility` | L6 | Plugins, tool servers, hooks extend agent capabilities | +| `state_persistence` | L6 | State persists across sessions (memory files, learnings) | + +**Detection order:** Capabilities are checked from L1 up. The project level is the highest N where at least one capability is detected at every level L1 through N. + +See `registry/capabilities.yml` for the machine-readable taxonomy and `registry/levels.yml` for level definitions. + +--- + +## How Rules Use Levels + +Rules and capabilities are **separate systems** connected only by the level identifier: + +- **Capabilities** are detected → determine your project's level +- **Rules** declare a concern level (e.g., `level: L2`) in their frontmatter +- A rule fires when `rule.level ≤ project_level` + +This means an L3 project is checked against all rules at L1, L2, and L3 — not just L3 rules. + +**47 rules** across 3 types: + +| Type | Count | Detection Method | LLM Cost | +|------|-------|------------------|----------| +| Mechanical | 22 | Python structural checks | None | +| Deterministic | 18 | OpenGrep pattern match | None | +| Semantic | 7 | OpenGrep gate + LLM evaluation | Per check | --- @@ -123,10 +131,10 @@ L0 (Absent) means no instruction file exists — nothing to evaluate. Levels L1 | Transition | Key Actions | |------------|-------------| | L1 → L2 | Add core sections, constraints, project description | -| L2 → L3 | Extract to @imports, remove code style rules | -| L3 → L4 | Implement .claude/rules/, configure hooks | -| L4 → L5 | Add map staleness prevention, backbone index completeness | -| L5 → L6 | Presence of backbone.yml triggers L6 detection | +| L2 → L3 | Extract to @imports, distribute across multiple files | +| L3 → L4 | Implement path-scoped rules, configure context-aware loading | +| L4 → L5 | Add structural validation, org policy, navigation maps | +| L5 → L6 | Add skills, hooks, MCP servers, persistent memory | --- @@ -147,25 +155,25 @@ L0 (Absent) means no instruction file exists — nothing to evaluate. Levels L1 **Score** and **Level** are independent metrics: -- **Level (L1-L6)**: Capability tier — determined by detected features +- **Level (L1-L6)**: Capability tier — determined by detected capabilities - **Score (0-10)**: Compliance — how well you follow rules at your level A simple instruction file (L2) can score 10/10 if it follows all L2 rules perfectly. ### Step 1: Detect Level -Level is determined by **features present**, not by score: +Level is determined by **capabilities present**, not by score: -| Feature | Detected Level | -|---------|---------------| -| backbone.yml present | L6 (Adaptive) | -| Map staleness + backbone index rules | L5 (Maintained) | -| `.claude/rules/` directory | L4 (Abstracted) | -| @imports or multiple instruction files | L3 (Structured) | -| Instruction file exists and customized | L2 (Scoped) | -| Instruction file exists (uncustomized) | L1 (Basic) | +| Capability Detected | Minimum Level | +|---------------------|--------------| +| `state_persistence`, `extensibility`, `dynamic_context` | L6 (Adaptive) | +| `structural_integrity`, `org_policy`, `navigation` | L5 (Maintained) | +| `path_scoping` | L4 (Abstracted) | +| `external_references`, `multiple_files` | L3 (Structured) | +| `project_constraints`, `size_controlled` | L2 (Scoped) | +| `instruction_file` | L1 (Basic) | -**Detection order:** Check from L6 down. First match = detected level. +**Assignment:** The project level is the highest N where at least one capability is detected at every level L1 through N. ### Step 2: Calculate Score (0-10) @@ -205,40 +213,6 @@ Friction estimates rework time from re-explanation loops: --- -## Rule Detection Types - -Rules are classified by detection method: - -| Type | Count | Detection Method | LLM Cost | -|------|-------|------------------|----------| -| Deterministic | 15 | OpenGrep pattern match | None | -| Semantic | 3 | OpenGrep gate + LLM evaluation | Per check | - -### Deterministic Rules (15) - -100% certainty via OpenGrep pattern matching. No LLM needed. - -### Semantic Rules (3) - -Two-stage validation: - -``` -OpenGrep pattern match (gate) - │ - ├── No match → Pass (zero LLM cost) - │ - └── Match → LLM evaluates question + criteria - │ - ├── Confirmed → Violation - └── Dismissed → Pass -``` - -Each semantic rule has: -- `question`: What to evaluate -- `criteria`: Pass/fail definition - ---- - ## Rule Tiers Rules are classified into tiers based on evidence backing. Tier is **derived** from backing source weights, not stored: @@ -255,11 +229,6 @@ Rule tier = core if max(backing_source_weights) >= 0.8 = experimental if max(backing_source_weights) < 0.8 ``` -**Examples:** -- Rule backed by Official (1.0) + Community (0.4) → **core** (max = 1.0) -- Rule backed by Research (0.8) → **core** (max = 0.8) -- Rule backed by Community (0.4) only → **experimental** (max = 0.4) - ### Tier Filtering Projects can filter rules by tier via `.reporails/config.yml`: @@ -301,4 +270,4 @@ This ensures core remains rock-solid while experimental patterns can mature thro | L1-L4 patterns | Official documentation (Anthropic, OpenAI, GitHub), community best practices | | L5-L6 patterns | Community patterns (experimental tier) | -See `docs/sources.yml` for full source registry with evidence chain. +See `docs/sources.yml` for full source registry. diff --git a/docs/methodology-thresholds.md b/docs/methodology-thresholds.md index 1494acd..0b08866 100644 --- a/docs/methodology-thresholds.md +++ b/docs/methodology-thresholds.md @@ -8,11 +8,9 @@ This document is the source of truth for Reporails threshold interpretations. Wh | Rule | Threshold | Source says | Our interpretation | |------|-----------|-------------|-------------------| -| S1 | 200 lines max | "< 300 lines is best" | Stricter threshold provides safety margin; 200 encourages @imports earlier | -| S3 | 10 lines max | "keep concise" | Code blocks should be examples, not implementations | -| E1 | 10 lines max | "keep concise" | Same as S3 — code blocks are examples | -| E2 | 10 imports max | "hierarchical structure" | Practical limit before import chains become confusing | -| C5 | Has version/date | — | Change tracking enables maintenance discipline | +| CORE:S:0005 | 300 lines max | "< 300 lines is best" | Per-file limit encourages @imports earlier | +| CORE:S:0006 | 32 KiB total | "hierarchical structure" | Total instruction budget across all files | +| CLAUDE:S:0002 | 5 hops max | "hierarchical structure" | Import chains beyond 5 hops become confusing | ## Rationale @@ -20,10 +18,10 @@ This document is the source of truth for Reporails threshold interpretations. Wh Sources provide general guidance. We provide enforcement. -"Keep files concise" doesn't fail a lint check. "Over 200 lines" does. +"Keep files concise" doesn't fail a lint check. "Over 300 lines" does. Our thresholds are: -- **Measurable** — OpenGrep can detect them +- **Measurable** — OpenGrep or mechanical checks can detect them - **Enforceable** — Clear pass/fail - **Conservative** — Better to split early than refactor later @@ -31,9 +29,9 @@ Our thresholds are: | Threshold | Derivation | |-----------|------------| -| 200 lines | ~150-200 instructions is frontier LLM attention limit (humanlayer research) | -| 10 lines code | Code blocks are examples; full implementations belong in actual code | -| 10 imports | Cognitive limit; deeper hierarchies need .claude/rules/ instead | +| 300 lines | ~150-300 instructions is frontier LLM attention limit (humanlayer research) | +| 32 KiB | Codex hard budget limit; effective ceiling for all agents | +| 5 hops | Cognitive limit; deeper chains need .claude/rules/ instead | ### Adjusting thresholds @@ -41,25 +39,13 @@ These are defaults. Users can override via `.reporails/config.yml`: ```yaml overrides: - S1-root-too-long: + CORE:S:0005: disabled: true # "I know my file is long" - C7-too-many-emphases: - severity: low # "I use emphasis differently" ``` -## Governance Best Practices - -Rules without external sources but based on enterprise patterns: - -| Rule | Pattern | Source | -|------|---------|--------| -| C5 | Version/date enables change tracking | Maintenance discipline | - -Governance rules have moved to [reporails/recommended](https://github.com/reporails/recommended). - ## Sources This document is cited by rules that use Reporails-defined thresholds: -- S1, S3, C5, E1, E2 +- CORE:S:0005, CORE:S:0006, CLAUDE:S:0002 For rules backed by external sources, see `docs/sources.yml`. diff --git a/docs/opengrep-guide.md b/docs/opengrep-guide.md index 12439bd..13286c9 100644 --- a/docs/opengrep-guide.md +++ b/docs/opengrep-guide.md @@ -22,8 +22,8 @@ Use `languages: [generic]` for CLAUDE.md and other instruction files: ```yaml rules: - - id: S1-root-too-long - message: "Root file exceeds 200 lines" + - id: CORE.S.0005.check.0001 + message: "Root file exceeds 300 lines" severity: ERROR languages: [generic] pattern-regex: "..." @@ -87,7 +87,7 @@ OpenGrep natively parses YAML. Use `languages: [yaml]` for frontmatter: ```yaml rules: - - id: S4-clear-structure + - id: CORE.S.0008.check.0001 message: "Rule file has path scoping" languages: [yaml] pattern: | @@ -167,7 +167,7 @@ Results passed to LLM: LLM evaluates only what OpenGrep couldn't determine ``` -**Example: C2 Single Source of Truth** +**Example: Single Source of Truth (CORE:C:0017)** OpenGrep can detect: - Duplicate section headings @@ -181,10 +181,10 @@ OpenGrep can't determine: **So you write both:** ```yaml -# C2-single-source-of-truth.md (frontmatter) +# core/content/repo-specific-content/rule.md (frontmatter) type: semantic checks: - - id: C2-duplicate-content + - id: CORE.C.0017.check.0001 name: Duplicate content indicators severity: high question: "Given what was found, is there contradictory duplicated content?" @@ -194,9 +194,9 @@ criteria: ``` ```yaml -# C2-single-source-of-truth.yml (OpenGrep patterns) +# core/content/repo-specific-content/rule.yml (OpenGrep patterns) rules: - - id: C2-duplicate-content + - id: CORE.C.0017.check.0001 message: "Potential duplicate content found" severity: WARNING languages: [generic] @@ -229,4 +229,4 @@ opengrep scan --config your-rule.yml --target test-file.md - [OpenGrep GitHub](https://github.com/opengrep/opengrep) - [Semgrep Generic Pattern Matching](https://semgrep.dev/docs/writing-rules/generic-pattern-matching) -- [Semgrep Pattern Syntax](https://semgrep.dev/docs/writing-rules/pattern-syntax) \ No newline at end of file +- [Semgrep Pattern Syntax](https://semgrep.dev/docs/writing-rules/pattern-syntax) diff --git a/docs/rule-template.md b/docs/rule-template.md index 98080dc..4481e9e 100644 --- a/docs/rule-template.md +++ b/docs/rule-template.md @@ -1,181 +1,69 @@ -# Rule Template +# Rule Body Template -Guide for contributors adding new rules to `core/` or `agents/{agent}/rules/`. +This template defines the body format for rule.md files. +Structured fields from rule skeletons fill the placeholders below. --- -## Quick Start +## Body Format (below YAML frontmatter) -Copy this template and fill in the fields: +```markdown +# {title} -```yaml ---- -id: S1 -title: Size Limits -category: structure -type: deterministic -checks: - - id: S1-root-too-long - name: Root file > 200 lines - severity: critical - pattern_confidence: very_high -sources: - - "https://docs.anthropic.com/en/docs/claude-code/best-practices" -see_also: [M7, C1] ---- - -# Size Limits - -Prevents instruction degradation from token bloat. - -## Why This Matters - -One sentence explaining the impact of violating this rule. - -## Pattern - -**Good:** Root file under 100 lines with @imports -**Bad:** 300-line monolithic CLAUDE.md -``` - ---- - -## Rule ID Convention +{statement} -| Scope | Pattern | Example | -|-------|---------|---------| -| Core | `{category}{number}` | `S1`, `C2`, `M4` | -| Agent | `{AGENT}_{category}{number}` | `CLAUDE_S1`, `COPILOT_E1` | -| Custom | `{PREFIX}_{category}{number}` | `ACME_S1`, `MYTEAM_M1` | +## Pass / Fail -**Categories:** -- `S` = Structure -- `C` = Content -- `E` = Efficiency -- `M` = Maintenance +**Pass:** {pass_example} +**Fail:** {fail_example} -**Agent prefixes (reserved):** CLAUDE, COPILOT, CODEX, CURSOR, WINDSURF, CLINE, AIDER, CONTINUE +## Limitations ---- - -## Rule Types - -### Deterministic - -OpenGrep decides. No LLM involved. - -```yaml -type: deterministic -checks: - - id: S1-root-too-long - name: Root file > 200 lines - severity: critical - pattern_confidence: very_high +{limitations} ``` -**You must also create a matching `.yml` file** with OpenGrep patterns: +## Semantic Rule Additions -```yaml -# S1-size-limits.yml -rules: - - id: S1-root-too-long - message: "Root file exceeds 200 lines" - severity: ERROR - languages: [generic] - pattern-regex: "..." - paths: - include: - - "{{instruction_files}}" -``` - -### Semantic - -OpenGrep runs first, LLM evaluates what patterns can't determine. +For semantic rules, `question` and `criteria` are added to the YAML frontmatter +(machine-parseable for CLI handoff to the coding agent): ```yaml -type: semantic -checks: - - id: C2-duplicate-content - name: Duplicate content indicators - severity: high - pattern_confidence: low -question: "Given what was found, is there contradictory duplicated content?" +question: "Given the matched content, are there vague or aspirational instructions?" criteria: - - No contradictory instructions across files - - Single authoritative source for each constraint -``` - -**Semantic rules also need a `.yml` file** — OpenGrep catches what it can, LLM fills gaps. - ---- - -## Severity Levels - -| Severity | When to use | -|----------|-------------| -| `critical` | Causes rework loops, major time waste | -| `high` | Causes clarification loops | -| `medium` | Causes brief confusion | -| `low` | Minor friction | - ---- - -## File Structure - -Each rule lives in its own directory with tests: - -``` -core/ - structure/ - S1-size-limits/ - S1-size-limits.md # Rule definition (frontmatter + docs) - S1-size-limits.yml # OpenGrep patterns - tests/ - fail.md # Should trigger (true positive) - pass.md # Should not trigger (true negative) -``` - -**Directory:** `{id}-{slug}/` -**Files:** `{id}-{slug}.md` and `{id}-{slug}.yml` -**Tests:** `tests/fail.md` and `tests/pass.md` - -**The `checks[].id` in `.md` must match `rules[].id` in `.yml`** - ---- - -## Sources - -Link to supporting references (official docs, articles, research): - -```yaml -sources: - - "https://docs.anthropic.com/en/docs/claude-code/best-practices" - - "https://dev.to/author/relevant-article" + - Each instruction targets a specific observed behavior + - No vague qualifiers like "properly" or "well" ``` -Good sources: -- Official agent documentation -- Well-researched articles -- Community best practices with evidence - ---- - -## Checklist Before Submitting - -- [ ] ID follows convention (category + number, or AGENT_category + number) -- [ ] ID doesn't collide with existing rules -- [ ] Frontmatter parses as valid YAML -- [ ] `.yml` file exists with matching check IDs -- [ ] Type is correct (deterministic or semantic) -- [ ] If semantic: includes `question` + `criteria` -- [ ] Sources are URLs, not numbers -- [ ] `see_also` references valid rule IDs -- [ ] Title is max 64 characters -- [ ] Body content is concise (< 40 lines) -- [ ] `pattern_confidence` assessed for each check - ---- - -## Full Schema Reference - -See `schemas/rule.schema.yml` for the complete machine-readable schema. \ No newline at end of file +These fields are NOT rendered into the body — they stay in frontmatter for the CLI +to extract and pass to the evaluating agent. + +## Field Sources + +| Placeholder | Skeleton field | Required | +|-------------|---------------|----------| +| `{title}` | `title` | Always | +| `{statement}` | `statement` | Always | +| `{pass_example}` | `pass_example` | Always | +| `{fail_example}` | `fail_example` | Always | +| `{limitations}` | `limitations` | Always | +| `question` | `question` | Semantic only | +| `criteria` | `criteria` | Semantic only | + +## Type-Specific Guidance + +### Mechanical rules +- `statement` asserts a structural property: "File X must exist", "File must be under N lines" +- `pass_example` / `fail_example` describe file system state, not content +- `limitations`: what structural checks miss (e.g., "cannot assess content quality") + +### Deterministic rules +- `statement` asserts a pattern presence or absence +- `pass_example` / `fail_example` describe content patterns +- `limitations`: what patterns can't catch (e.g., "regex can't distinguish code blocks from prose") + +### Semantic rules +- `statement` asserts a quality property +- `pass_example` / `fail_example` describe content characteristics +- `question` is the LLM evaluation prompt — must be answerable from the matched content +- `criteria` are independently assessable rubric items +- `limitations`: what even LLM evaluation can't reliably determine diff --git a/docs/sources.yml b/docs/sources.yml index 43146d2..6cea48b 100644 --- a/docs/sources.yml +++ b/docs/sources.yml @@ -1,311 +1,84 @@ -# Source Registry with Evidence Claims -# Schema: schemas/sources.schema.yml (v3) -# -# Each source contains specific claims that back specific rules. -# This creates an auditable evidence chain: source -> claim -> rule -# -# Tier derivation (NOT stored, computed from weights): -# - core: max(backing_weights) >= 0.8 (official or research) -# - experimental: max(backing_weights) < 0.8 (community only) - -generic: +# Source Registry — Core Package +# Schema: schemas/sources.schema.yml - id: agents-md-spec - title: AGENTS.md Specification (Linux Foundation) url: https://agents.md/ type: official weight: 1.0 - accessed: '2026-01-30' - claims: - - id: readme-for-agents - text: Think of AGENTS.md as a README for agents - quote: true - section: Introduction - rules: [C3] - - id: root-placement - text: Create an AGENTS.md file at the root of the repository - quote: true - section: Getting Started - rules: [S1, C1] - - id: standard-markdown - text: AGENTS.md is just standard Markdown. Use any headings you like - quote: true - section: FAQ - rules: [S4] - - id: no-required-fields - text: No required fields exist - file format is flexible - section: FAQ - rules: [C1] - - id: nested-monorepo - text: Create nested AGENTS.md files for subprojects in monorepos - section: Monorepos - rules: [S2, CLAUDE_S1] - - id: nearest-precedence - text: Agents automatically read the nearest file in the directory tree, so the closest one takes precedence - quote: true - section: Monorepos - rules: [S2, CLAUDE_S2] - - id: executable-commands - text: Agents will attempt to execute relevant programmatic checks and fix failures before finishing the task when commands - are listed - quote: true - section: FAQ - rules: [C1] - - id: living-document - text: Treat AGENTS.md as living documentation that can be updated anytime - section: Maintenance - rules: [M1] - - id: recommended-sections - text: 'Popular sections include: project overview, build/test commands, code style, testing, security, commit/PR guidelines, - deployment' - section: How to use - rules: [C1, C3] -- id: instruction-limits-principles - url: https://www.humanlayer.dev/blog/writing-a-good-claude-md - type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: instruction-capacity - text: Frontier LLMs follow ~150-200 instructions with reasonable consistency - quote: true - rules: [S1] - - id: line-limit - text: Less than 300 lines is optimal; shorter performs better - rules: [S1] - - id: less-is-more - text: Less instructions is more - excessive instructions degrade quality uniformly - rules: [S1] - - id: progressive-files - text: Separate task-specific instructions into discrete markdown files - rules: [S2] -- id: spec-writing-for-agents - url: https://addyosmani.com/blog/good-spec/ + title: Agents.md Specification +- id: claude-code-issue-13579 + url: https://github.com/anthropics/claude-code/issues/13579 type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: commands-early - text: Put executable commands early - full commands with flags - quote: true - rules: [C1] - - id: code-snippet-beats-prose - text: One real code snippet showing your style beats three paragraphs - quote: true - rules: [S3] - - id: curse-of-instructions - text: Performance degrades when too many rules compete for attention - rules: [S1] - - id: modularity - text: Break specs into focused sections rather than monolithic prompts - rules: [S2] - -claude: + weight: 0.6 + title: 'Claude Code Issue #13579 - Token Waste' - id: claude-code-memory url: https://code.claude.com/docs/en/memory type: official weight: 1.0 - accessed: '2026-01-30' - claims: - - id: memory-hierarchy - text: 'Four memory locations in hierarchical structure: managed, project, rules, user' - section: Determine memory type - rules: [CLAUDE_S1] - - id: rules-directory - text: Use .claude/rules/ for modular, topic-specific project instructions - quote: true - section: Modular rules - rules: [CLAUDE_S1, CLAUDE_S2] - - id: path-scoped-rules - text: Rules can be scoped to specific files using YAML frontmatter with paths field - section: Path-specific rules - rules: [CLAUDE_S2] - - id: imports-syntax - text: CLAUDE.md files can import additional files using @path/to/import syntax - section: CLAUDE.md imports - rules: [S2, C4] - - id: import-max-depth - text: Imported files can recursively import with max-depth of 5 hops - section: CLAUDE.md imports - rules: [E2] - - id: recursive-discovery - text: Claude reads memories recursively from cwd up to root - section: How Claude looks up memories - rules: [S2] - - id: use-structure - text: Format memories as bullet points grouped under descriptive headings - section: Memory best practices - rules: [S4, C1] - - id: review-periodically - text: Review memories periodically as your project evolves - section: Memory best practices - rules: [C5] - - id: keep-rules-focused - text: 'Keep rules focused: Each file should cover one topic' - quote: true - section: Best practices - rules: [C2, M2] + title: Claude Code Memory Documentation - id: claude-code-settings url: https://code.claude.com/docs/en/settings type: official weight: 1.0 - accessed: '2026-01-30' - claims: - - id: rules-dir-config - text: .claude/rules/ directory configuration for path scoping - rules: [CLAUDE_S1, CLAUDE_S2] -- id: using-claude-md-files - url: https://claude.com/blog/using-claude-md-files + title: Claude Code Settings Documentation +- id: claude-md-guide + url: https://www.builder.io/blog/claude-md-guide + type: community + weight: 0.6 + title: Claude.md Guide - Builder.io +- id: claude-md-optimization-study + url: + https://arize.com/blog/claude-md-best-practices-learned-from-optimizing-claude-code-with-prompt-learning/ + type: research + weight: 0.8 + title: Claude.md Best Practices - Arize +- id: codex-agent-loop + url: https://openai.com/index/unrolling-the-codex-agent-loop/ type: official weight: 1.0 - accessed: '2026-01-30' - claims: - - id: usage-patterns - text: CLAUDE.md usage patterns and practical examples - rules: [C1, C3] - - id: customized-content - text: Customize CLAUDE.md with project-specific content - rules: [CLAUDE_M1] -- id: anthropic-teams-claude-code - url: https://claude.com/blog/how-anthropic-teams-use-claude-code + title: Unrolling the Codex Agent Loop +- id: codex-agents-md + url: https://developers.openai.com/codex/guides/agents-md type: official weight: 1.0 - accessed: '2026-01-30' - claims: - - id: team-onboarding - text: New hires feed Claude codebase to get productive quickly via CLAUDE.md files - rules: [C3] -- id: claude-code-issue-13579 - url: https://github.com/anthropics/claude-code/issues/13579 - type: research - weight: 0.8 - accessed: '2026-01-30' - claims: - - id: token-waste-measured - text: 700K+ tokens wasted across 2M token project from 7 patterns - section: Analysis Results - rules: [S1] -- id: claude-md-optimization-study - url: https://arize.com/blog/claude-md-best-practices-learned-from-optimizing-claude-code-with-prompt-learning/ - type: research - weight: 0.8 - accessed: '2026-01-30' - claims: - - id: optimization-improvement - text: +5.19% general improvement, +10.87% repo-specific from optimization - rules: [S1, C1] -- id: monorepo-claude-md-organization - url: https://dev.to/anvodev/how-i-organized-my-claudemd-in-a-monorepo-with-too-many-contexts-37k7 + title: Codex Agents.md Guide +- id: dometrain-claude-md-guide + url: https://dometrain.com/blog/creating-the-perfect-claudemd-for-claude-code/ type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: reduction-achieved - text: Reduced 47k to 9k words (~80%) through hierarchical structure - rules: [S1, S2] - - id: service-specific-files - text: Use service-specific instruction files in monorepos - rules: [S2] + weight: 0.6 + title: Creating the Perfect CLAUDE.md - Dometrain - id: enterprise-claude-usage url: https://blog.sshh.io/p/how-i-use-every-claude-code-feature type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: kb-limit - text: 13KB limit observed for effective instruction following - rules: [S1] -- id: claude-md-guide - url: https://www.builder.io/blog/claude-md-guide - type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: file-placement - text: CLAUDE.md placement affects scope and team access - rules: [S2, M1] - - id: practical-examples - text: Include practical examples in instruction files - rules: [C1] -- id: rules-directory-mechanics - url: https://claudefa.st/blog/guide/mechanics/rules-directory + weight: 0.6 + title: How I Use Every Claude Code Feature +- id: instruction-limits-principles + url: https://www.humanlayer.dev/blog/writing-a-good-claude-md type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: rules-mechanics - text: .claude/rules/ mechanics with path scoping and YAML frontmatter - rules: [CLAUDE_S1, CLAUDE_S2] - - id: loading-behavior - text: Rules load based on path matching during file operations - rules: [CLAUDE_S2] -- id: dometrain-claude-md-guide - url: https://dometrain.com/blog/creating-the-perfect-claudemd-for-claude-code/ + weight: 0.6 + title: Writing a Good Claude.md - HumanLayer +- id: monorepo-claude-md-organization + url: + https://dev.to/anvodev/how-i-organized-my-claudemd-in-a-monorepo-with-too-many-contexts-37k7 type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: lazy-loading-context - text: Break lengthy standards into separate files rather than embedding everything - reference external files to load - context on demand - section: Context Window Efficiency - rules: [S2] - - id: domain-terminology - text: Document architecture patterns, file structure, and domain terminology explicitly so agents avoid guessing - section: Architecture Section Requirements - rules: [C1, C3] - - id: command-specificity - text: Include specific flags and parameters in commands - omitting arguments causes agents to run defaults which fail - section: Terminal Commands Documentation - rules: [C1] - - id: duplicate-instruction-waste - text: Duplicate instructions add little value and use unnecessary context - quote: true - section: Context Window Efficiency - rules: [C2] - - id: living-document-updates - text: Update instruction file when noticing repeated agent errors - version control for team consistency - section: Living Document Approach - rules: [M1] + weight: 0.6 + title: Monorepo Claude.md Organization - id: osmani-ai-coding-workflow url: https://addyosmani.com/blog/ai-coding-workflow/ + type: research + weight: 0.8 + title: AI-Assisted Coding Workflow - Addy Osmani +- id: rules-directory-mechanics + url: https://claudefa.st/blog/guide/mechanics/rules-directory type: community - weight: 0.4 - accessed: '2026-01-30' - claims: - - id: planning-before-coding - text: Brainstorm a detailed specification with the AI, then outline a step-by-step plan, before writing any actual code - quote: true - section: Planning & Specification - rules: [C1] - - id: commit-savepoints - text: Commit early and often as save points - never commit code you can't explain - section: Version Control Discipline - rules: [M1] - -codex: -- id: codex-agents-md - url: https://developers.openai.com/codex/guides/agents-md - type: official - weight: 1.0 - accessed: '2026-01-30' - claims: - - id: size-limit-32kb - text: Codex stops adding files once combined size reaches 32 KiB - quote: true - rules: [S1] - - id: discovery-order - text: 'Discovery follows: global scope, then project scope from root to cwd' - quote: true - rules: [S2] -- id: codex-agent-loop - title: Unrolling the Codex agent loop - url: https://openai.com/index/unrolling-the-codex-agent-loop/ + weight: 0.6 + title: Rules Directory Mechanics - ClaudeFast +- id: spec-writing-for-agents + url: https://addyosmani.com/blog/good-spec/ + type: research + weight: 0.8 + title: Writing Good Specs for AI Agents - Addy Osmani +- id: using-claude-md-files + url: https://claude.com/blog/using-claude-md-files type: official weight: 1.0 - accessed: '2026-01-30' - claims: - - id: cascading-later-wins - text: Files closer to current directory override earlier guidance because they appear later in the combined prompt - quote: true - section: Cascading Behavior - rules: [S2] + title: Using CLAUDE.md Files - Anthropic diff --git a/levels.yml b/levels.yml deleted file mode 100644 index 5dadcac..0000000 --- a/levels.yml +++ /dev/null @@ -1,40 +0,0 @@ -# Canonical level definitions for the Reporails framework. -# Source of truth: docs/capability-levels.md (Capability Assessment Matrix) -# -# CLI consumers should prefer this file over any bundled copy. - -levels: - L0: - name: Absent - description: No instruction file - rules: [] - - L1: - name: Basic - description: Instruction file exists, reviewed, has basic content - rules: [CLAUDE_M1, M1] - - L2: - name: Scoped - description: Project-specific constraints, size limits, content quality - rules: [S1, S2, S3, S4, C1, C3, C5] - - L3: - name: Structured - description: Clear sections, external references, organized content - rules: [C2, C4, E1, E2, M2] - - L4: - name: Abstracted - description: Rules directory, path-scoped loading - rules: [CLAUDE_S1, CLAUDE_S2] - - L5: - name: Maintained - description: Map and index maintenance discipline - rules: [M3, M4] - - L6: - name: Adaptive - description: Backbone-driven navigation, contracts (detection-only) - rules: [] diff --git a/registry/capabilities.yml b/registry/capabilities.yml new file mode 100644 index 0000000..b2ffb07 --- /dev/null +++ b/registry/capabilities.yml @@ -0,0 +1,98 @@ +# Universal capability taxonomy +version: 1 + +capabilities: + # L1 — Does guidance exist? + - id: instruction_file + level: L1 + description: > + An instruction file exists in a recognized location, + is tracked in version control, and meets a minimum + content threshold (≥10 lines). The agent has access + to non-trivial, committed, project-specific guidance. + threshold: + min_lines: 10 + + # L2 — Is the guidance useful and focused? + - id: project_constraints + level: L2 + description: > + The instruction file contains project-specific substance: + language, framework, commands, explicit constraints. + Not boilerplate or unreviewed auto-generated content. + threshold: + min_sections: 2 + has_any_of: + - explicit_constraints + - commands + - recognized_sections + + - id: size_controlled + level: L2 + description: > + The instruction file is concise. Not bloated with + duplicated content, embedded code, or style rules. + + # L3 — Is the guidance organized and modular? + - id: external_references + level: L3 + description: > + The instruction system references content that lives + outside the primary instruction file. Content is not + duplicated — single source of truth is maintained. + + - id: multiple_files + level: L3 + description: > + More than one instruction-related file exists. + Guidance is distributed across files by concern. + + # L4 — Does guidance adapt to code context? + - id: path_scoping + level: L4 + description: > + Different instructions load based on which files the + agent is working with. Context-aware rule loading. + + # L5 — Is the guidance system structurally sound? + - id: structural_integrity + level: L5 + description: > + References resolve, indexes are current, no orphaned + files or dead links. The instruction system is + internally consistent and validated. + + - id: org_policy + level: L5 + description: > + Organization-level governance is deployed. Instruction + policies are managed above the project level. + + - id: navigation + level: L5 + description: > + A structural map guides the agent through the codebase. + Backbone files, component maps, or contract registries + provide O(1) lookup instead of search. + + # L6 — Does the agent dynamically discover and extend? + - id: dynamic_context + level: L6 + description: > + The agent discovers and loads relevant context based + on the current task, not just file location. Skills, + prompt templates, or task-triggered loading. + + - id: extensibility + level: L6 + description: > + The agent's capabilities are extended beyond reading + instruction files. Plugins, tool servers, hooks, + or external integrations add new actions. + + - id: state_persistence + level: L6 + description: > + The agent maintains state across sessions. Memory files, + learnings, or accumulated context persist beyond the + current conversation and inform future interactions. diff --git a/registry/coordinate-map.yml b/registry/coordinate-map.yml new file mode 100644 index 0000000..7f33144 --- /dev/null +++ b/registry/coordinate-map.yml @@ -0,0 +1,60 @@ +# Slug → coordinate mapping +version: 1 + +core: + structure: + instruction-file-exists: "CORE:S:0001" + instruction-file-is-markdown: "CORE:S:0002" + instruction-file-version-controlled: "CORE:S:0003" + no-sensitive-information: "CORE:S:0004" + instruction-file-size-limit: "CORE:S:0005" + total-instruction-budget: "CORE:S:0006" + decomposed-instruction-system: "CORE:S:0007" + scope-hierarchy-documented: "CORE:S:0008" + local-files-not-committed: "CORE:S:0009" + cross-agent-compatibility: "CORE:S:0010" + mcp-servers-documented: "CORE:S:0011" + reusable-skills-over-repeated-prompts: "CORE:S:0012" + content: + has-project-description: "CORE:C:0001" + has-project-structure: "CORE:C:0002" + has-commands: "CORE:C:0003" + has-testing-conventions: "CORE:C:0004" + has-boundaries: "CORE:C:0005" + specificity-over-vagueness: "CORE:C:0006" + universal-content-only: "CORE:C:0007" + has-style-conventions: "CORE:C:0009" + has-constraints-and-pitfalls: "CORE:C:0010" + has-workflow-instructions: "CORE:C:0011" + has-domain-terminology: "CORE:C:0012" + structured-sections: "CORE:C:0015" + persist-critical-constraints: "CORE:C:0016" + repo-specific-content: "CORE:C:0017" + hierarchical-summary: "CORE:C:0019" + ask-not-guess: "CORE:C:0022" + explain-reasoning: "CORE:C:0023" + provides-pattern-examples: "CORE:C:0025" + efficiency: {} + maintenance: {} + governance: {} + +agents: + claude: + claude-md-file-placement: "CLAUDE:S:0001" + import-depth-within-limit: "CLAUDE:S:0002" + rules-directory-structure: "CLAUDE:S:0003" + path-targeting-syntax: "CLAUDE:S:0004" + child-files-scoped: "CLAUDE:S:0005" + skills-and-subagents-documented: "CLAUDE:S:0008" + project-rules-override-user: "CLAUDE:S:0009" + settings-files-at-correct-locations: "CLAUDE:S:0010" + sensitive-files-denied: "CLAUDE:S:0011" + memory-file-within-200-lines: "CLAUDE:S:0012" + codex: + agents-md-file-placement: "CODEX:S:0001" + agents-md-override-mechanics: "CODEX:S:0002" + instruction-size-within-32kib: "CODEX:S:0003" + recognized-filenames-only: "CODEX:S:0004" + nested-files-for-subprojects: "CODEX:S:0005" + global-agents-md-exists: "CODEX:S:0006" + skills-within-instruction-budget: "CODEX:S:0007" diff --git a/registry/levels.yml b/registry/levels.yml new file mode 100644 index 0000000..eef1b37 --- /dev/null +++ b/registry/levels.yml @@ -0,0 +1,50 @@ +# Level definitions +version: 1 + +levels: + L0: + name: Absent + description: "No instruction file exists" + capabilities: [] + + L1: + name: Basic + description: "A non-trivial, tracked instruction file exists" + capabilities: + - instruction_file + + L2: + name: Scoped + description: "Project-specific constraints defined, file is focused" + capabilities: + - project_constraints + - size_controlled + + L3: + name: Structured + description: "Guidance is modular with external references" + capabilities: + - external_references + - multiple_files + + L4: + name: Abstracted + description: "Instructions adapt based on code location" + capabilities: + - path_scoping + + L5: + name: Maintained + description: "Instruction system is structurally sound, governed, and navigable" + capabilities: + - structural_integrity + - org_policy + - navigation + + L6: + name: Adaptive + description: "Agent dynamically discovers context and extends capabilities" + capabilities: + - dynamic_context + - extensibility + - state_persistence diff --git a/registry/tombstones.yml b/registry/tombstones.yml new file mode 100644 index 0000000..bfada1f --- /dev/null +++ b/registry/tombstones.yml @@ -0,0 +1,4 @@ +# Dead coordinate slots — never reused +version: 1 + +tombstones: [] diff --git a/runtime/Dockerfile b/runtime/Dockerfile new file mode 100644 index 0000000..cb7827e --- /dev/null +++ b/runtime/Dockerfile @@ -0,0 +1,22 @@ +FROM python:3.12-slim + +# Install opengrep via install script +RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \ + && curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash \ + && apt-get purge -y curl \ + && apt-get autoremove -y \ + && rm -rf /var/lib/apt/lists/* + +# Symlink opengrep onto PATH +RUN ln -s "$(find /root/.opengrep -name opengrep -type f | head -1)" /usr/local/bin/opengrep + +# Install Python dependencies +COPY requirements.txt /runtime/requirements.txt +RUN pip install --no-cache-dir -r /runtime/requirements.txt + +# Copy runtime code +COPY test-runner.py /runtime/test-runner.py +COPY checks.py /runtime/checks.py + +WORKDIR /rules +ENTRYPOINT ["python", "/runtime/test-runner.py"] diff --git a/runtime/README.md b/runtime/README.md new file mode 100644 index 0000000..427b232 --- /dev/null +++ b/runtime/README.md @@ -0,0 +1,96 @@ +# Reporails Rule Test Harness + +Contributor-facing test harness for validating rule implementations against test fixtures. + +## Quick Start + +```bash +# Build the test image +docker compose -f runtime/docker-compose.yml build + +# Run all rules +docker compose -f runtime/docker-compose.yml run test + +# Run one rule by coordinate +docker compose -f runtime/docker-compose.yml run test --rule CORE:S:0001 + +# Run one category +docker compose -f runtime/docker-compose.yml run test core/structure/ + +# Use a different agent's config for var resolution +docker compose -f runtime/docker-compose.yml run test --agent codex + +# Verbose output (shows OpenGrep output) +docker compose -f runtime/docker-compose.yml run test --verbose +``` + +## Fixture Format + +Each rule has `tests/pass/` and `tests/fail/` directories that simulate mini project roots: + +``` +{rule-dir}/tests/ + pass/ # Simulated project that PASSES this rule + CLAUDE.md # (or whatever files the rule targets) + fail/ # Simulated project that FAILS this rule + CLAUDE.md # (content/structure that triggers violation) +``` + +### Writing Fixtures + +1. Look at the rule's `targets:` field — it tells you what files the rule scans +2. Resolve template vars: `{{main_instruction_file}}` → `CLAUDE.md` (for claude agent) +3. Create those files inside `tests/pass/` and `tests/fail/` +4. Pass fixture: content that should NOT trigger the rule +5. Fail fixture: content that SHOULD trigger the rule + +### Example: Mechanical Rule (file_exists) + +``` +instruction-file-exists/tests/ + pass/ + CLAUDE.md # File exists → check passes + fail/ + .gitkeep # No instruction file → check fails +``` + +### Example: Deterministic Rule (OpenGrep pattern) + +``` +has-project-description/tests/ + pass/ + CLAUDE.md # Starts with heading + description → 0 findings + fail/ + CLAUDE.md # Starts with commands, no description → 1+ findings +``` + +## Check Types + +| Type | Engine | Pass fixture | Fail fixture | +|------|--------|-------------|-------------| +| Mechanical | Python (`checks.py`) | Check passes | Check fails | +| Deterministic | OpenGrep via `rule.yml` | 0 findings | 1+ findings | +| Semantic | Pre-checks only | Skipped (no LLM) | Skipped (no LLM) | + +## Template Variables + +Variables like `{{instruction_files}}` resolve from agent config files (`agents/{agent}/config.yml`). Default agent is `claude`. + +| Variable | Claude value | Codex value | +|----------|-------------|-------------| +| `{{main_instruction_file}}` | `**/CLAUDE.md` | `**/AGENTS.md` | +| `{{instruction_files}}` | `**/CLAUDE.md`, `.claude/rules/**/*.md` | `**/AGENTS.md`, `**/AGENTS.override.md` | +| `{{rules_dir}}` | `.claude/rules` | — | +| `{{skills_dir}}` | `.claude/skills` | — | + +## Graceful Degradation + +- `checks: []` → reported as "not implemented" (skipped) +- `rules: []` in rule.yml → deterministic checks fail (no patterns) +- Empty fixture directories → reported as "no fixtures" (skipped) +- Unknown check type → warning, skipped + +## Exit Codes + +- `0` — all implemented rules passed +- `1` — one or more rules failed diff --git a/runtime/checks.py b/runtime/checks.py new file mode 100644 index 0000000..191d17b --- /dev/null +++ b/runtime/checks.py @@ -0,0 +1,417 @@ +"""Mechanical check implementations for the reporails test harness. + +Each check receives: + root: Path to the fixture directory (simulated project root) + args: Check-specific arguments from rule.md frontmatter + vars: Resolved template variables from agent config + +Returns a CheckResult indicating pass/fail. +""" + +import glob as globmod +import re +from dataclasses import dataclass, field +from pathlib import Path + + +@dataclass +class CheckResult: + passed: bool + message: str + findings_count: int = 0 + + +def _resolve_path(template: str, vars: dict) -> str: + """Resolve template variables in a path string.""" + result = template + for key, value in vars.items(): + placeholder = "{{" + key + "}}" + if placeholder in result: + if isinstance(value, list): + result = result.replace(placeholder, value[0] if value else "") + else: + result = result.replace(placeholder, str(value)) + return result + + +def _resolve_glob_targets(pattern: str, root: Path) -> list[Path]: + """Resolve a glob pattern relative to root, returning matching paths.""" + resolved = str(root / pattern) + return [Path(p) for p in globmod.glob(resolved, recursive=True)] + + +def file_exists(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that at least one file matching the target pattern exists.""" + path_pattern = args.get("path", "") + if not path_pattern: + # Fall back to checking for any instruction files via vars + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + if matches: + return CheckResult(passed=True, message=f"Found: {matches[0].name}") + return CheckResult(passed=False, message="No instruction files found") + + resolved = _resolve_path(path_pattern, vars) + matches = _resolve_glob_targets(resolved, root) + if matches: + return CheckResult(passed=True, message=f"Found: {matches[0].name}") + return CheckResult(passed=False, message=f"File not found: {resolved}") + + +def directory_exists(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that a directory exists.""" + path = _resolve_path(args.get("path", ""), vars) + target = root / path + if target.is_dir(): + return CheckResult(passed=True, message=f"Directory exists: {path}") + return CheckResult(passed=False, message=f"Directory not found: {path}") + + +def directory_contains(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that a directory contains at least min_count files matching a pattern.""" + path = _resolve_path(args.get("path", ""), vars) + pattern = args.get("pattern", "*") + min_count = args.get("min", 1) + target = root / path + if not target.is_dir(): + return CheckResult(passed=False, message=f"Directory not found: {path}") + matches = list(target.glob(pattern)) + if len(matches) >= min_count: + return CheckResult(passed=True, message=f"Found {len(matches)} file(s) in {path}") + return CheckResult(passed=False, message=f"Found {len(matches)} file(s) in {path}, need {min_count}") + + +def git_tracked(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that files are git-tracked. In test fixtures, checks for .git marker.""" + # In fixture context, only check for a .git directory/file within root. + # .git_marker is an alternative because git cannot track paths named .git. + if (root / ".git").exists() or (root / ".git_marker").exists(): + return CheckResult(passed=True, message="Git repository detected") + return CheckResult(passed=False, message="Not a git repository") + + +def frontmatter_key(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that files have specific YAML frontmatter keys.""" + import frontmatter as fm + + key = args.get("key", "") + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + + path_pattern = args.get("path", "") + if path_pattern: + patterns = [_resolve_path(path_pattern, vars)] + + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + for match in matches: + try: + post = fm.load(str(match)) + if key in post.metadata: + return CheckResult(passed=True, message=f"Key '{key}' found in {match.name}") + except Exception: + continue + + return CheckResult(passed=False, message=f"Frontmatter key '{key}' not found") + + +def file_count(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that file count is within bounds.""" + pattern = args.get("pattern", "**/*") + min_count = args.get("min", 0) + max_count = args.get("max", float("inf")) + + resolved = _resolve_path(pattern, vars) + matches = _resolve_glob_targets(resolved, root) + # Filter to files only + files = [m for m in matches if m.is_file()] + count = len(files) + + if min_count <= count <= max_count: + return CheckResult(passed=True, message=f"File count {count} within [{min_count}, {max_count}]") + return CheckResult(passed=False, message=f"File count {count} outside [{min_count}, {max_count}]") + + +def line_count(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that file line count is within bounds.""" + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + + path_pattern = args.get("path", "") + if path_pattern: + patterns = [_resolve_path(path_pattern, vars)] + + max_lines = args.get("max", float("inf")) + min_lines = args.get("min", 0) + + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + for match in matches: + if not match.is_file(): + continue + try: + count = len(match.read_text().splitlines()) + if count > max_lines: + return CheckResult( + passed=False, + message=f"{match.name}: {count} lines exceeds max {max_lines}", + ) + if count < min_lines: + return CheckResult( + passed=False, + message=f"{match.name}: {count} lines below min {min_lines}", + ) + except Exception as e: + return CheckResult(passed=False, message=f"Error reading {match.name}: {e}") + + return CheckResult(passed=True, message=f"Line counts within bounds") + + +def byte_size(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that file size is within bounds.""" + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + + path_pattern = args.get("path", "") + if path_pattern: + patterns = [_resolve_path(path_pattern, vars)] + + max_bytes = args.get("max", float("inf")) + min_bytes = args.get("min", 0) + + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + for match in matches: + if not match.is_file(): + continue + size = match.stat().st_size + if size > max_bytes: + return CheckResult(passed=False, message=f"{match.name}: {size} bytes exceeds max {max_bytes}") + if size < min_bytes: + return CheckResult(passed=False, message=f"{match.name}: {size} bytes below min {min_bytes}") + + return CheckResult(passed=True, message="File sizes within bounds") + + +def path_resolves(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that referenced paths in files actually resolve.""" + # This checks that paths mentioned in instruction files point to real locations + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + + path_pattern = args.get("path", "") + if path_pattern: + patterns = [_resolve_path(path_pattern, vars)] + + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + if matches: + return CheckResult(passed=True, message="Target paths exist") + + return CheckResult(passed=False, message="No matching paths found") + + +def extract_imports(root: Path, args: dict, vars: dict) -> CheckResult: + """Check for @import references in instruction files.""" + import re + + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + + path_pattern = args.get("path", "") + if path_pattern: + patterns = [_resolve_path(path_pattern, vars)] + + imports_found = [] + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + for match in matches: + if not match.is_file(): + continue + try: + content = match.read_text() + # Match @path/to/file patterns + found = re.findall(r'@[\w./-]+', content) + imports_found.extend(found) + except Exception: + continue + + if imports_found: + return CheckResult(passed=True, message=f"Found {len(imports_found)} import(s)") + return CheckResult(passed=False, message="No imports found") + + +def aggregate_byte_size(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that the total byte size of all matching files is within bounds.""" + pattern = args.get("pattern", "**/*") + max_bytes = args.get("max", float("inf")) + + resolved = _resolve_path(pattern, vars) + matches = _resolve_glob_targets(resolved, root) + files = [m for m in matches if m.is_file()] + total = sum(f.stat().st_size for f in files) + + if total <= max_bytes: + return CheckResult(passed=True, message=f"Total {total} bytes within limit {max_bytes}") + return CheckResult(passed=False, message=f"Total {total} bytes exceeds max {max_bytes}") + + +def import_depth(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that @import reference chains do not exceed max depth.""" + max_depth = args.get("max", 5) + patterns = vars.get("instruction_files", []) + if isinstance(patterns, str): + patterns = [patterns] + + path_pattern = args.get("path", "") + if path_pattern: + patterns = [_resolve_path(path_pattern, vars)] + + def follow_chain(filepath: Path, visited: set, depth: int) -> int: + if filepath in visited or not filepath.is_file(): + return depth + visited.add(filepath) + try: + content = filepath.read_text() + except Exception: + return depth + refs = re.findall(r'@([\w./-]+)', content) + max_d = depth + for ref in refs: + target = filepath.parent / ref + if target.is_file(): + max_d = max(max_d, follow_chain(target, visited, depth + 1)) + return max_d + + for pattern in patterns: + matches = _resolve_glob_targets(pattern, root) + for match in matches: + if not match.is_file(): + continue + deepest = follow_chain(match, set(), 0) + if deepest > max_depth: + return CheckResult( + passed=False, + message=f"{match.name}: import depth {deepest} exceeds max {max_depth}", + ) + + return CheckResult(passed=True, message=f"Import depth within limit ({max_depth})") + + +def directory_file_types(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that all files in a directory match the allowed extension list.""" + path = _resolve_path(args.get("path", ""), vars) + extensions = args.get("extensions", []) + target = root / path + + if not target.is_dir(): + return CheckResult(passed=True, message=f"Directory not found: {path} (OK if optional)") + + bad_files = [] + for f in target.iterdir(): + if f.is_file() and f.suffix not in extensions: + bad_files.append(f.name) + + if bad_files: + return CheckResult( + passed=False, + message=f"Non-{extensions} files in {path}: {', '.join(bad_files[:5])}", + ) + return CheckResult(passed=True, message=f"All files in {path} match {extensions}") + + +def frontmatter_valid_glob(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that YAML frontmatter paths: entries use valid glob syntax.""" + import frontmatter as fm + + path = _resolve_path(args.get("path", ""), vars) + target = root / path + + if not target.is_dir(): + return CheckResult(passed=True, message=f"Directory not found: {path} (OK if optional)") + + for f in target.iterdir(): + if not f.is_file() or f.suffix != ".md": + continue + try: + post = fm.load(str(f)) + paths = post.metadata.get("globs", post.metadata.get("paths", [])) + if isinstance(paths, str): + paths = [paths] + for p in paths: + if not isinstance(p, str): + return CheckResult( + passed=False, + message=f"{f.name}: non-string path entry: {p}", + ) + # Check for obviously broken glob syntax + if p.count("[") != p.count("]"): + return CheckResult( + passed=False, + message=f"{f.name}: unbalanced brackets in glob: {p}", + ) + except Exception: + continue + + return CheckResult(passed=True, message="All frontmatter path entries valid") + + +def content_absent(root: Path, args: dict, vars: dict) -> CheckResult: + """Check that a regex pattern does NOT appear in any matching files. Pass=absent.""" + pattern = args.get("pattern", "") + if not pattern: + return CheckResult(passed=False, message="content_absent: no pattern specified") + + file_patterns = vars.get("instruction_files", []) + if isinstance(file_patterns, str): + file_patterns = [file_patterns] + + path_pattern = args.get("path", "") + if path_pattern: + file_patterns = [_resolve_path(path_pattern, vars)] + + compiled = re.compile(pattern) + for fp in file_patterns: + matches = _resolve_glob_targets(fp, root) + for match in matches: + if not match.is_file(): + continue + try: + content = match.read_text() + if compiled.search(content): + return CheckResult( + passed=False, + message=f"{match.name}: forbidden pattern found: {pattern}", + ) + except Exception: + continue + + return CheckResult(passed=True, message="Forbidden pattern not found") + + +# Registry of mechanical checks +MECHANICAL_CHECKS = { + "file_exists": file_exists, + "directory_exists": directory_exists, + "directory_contains": directory_contains, + "git_tracked": git_tracked, + "frontmatter_key": frontmatter_key, + "file_count": file_count, + "line_count": line_count, + "byte_size": byte_size, + "path_resolves": path_resolves, + "extract_imports": extract_imports, + "aggregate_byte_size": aggregate_byte_size, + "import_depth": import_depth, + "directory_file_types": directory_file_types, + "frontmatter_valid_glob": frontmatter_valid_glob, + "content_absent": content_absent, +} diff --git a/runtime/docker-compose.yml b/runtime/docker-compose.yml new file mode 100644 index 0000000..73ad606 --- /dev/null +++ b/runtime/docker-compose.yml @@ -0,0 +1,8 @@ +services: + test: + build: + context: . + volumes: + - ..:/rules:ro + - ../../recommended:/recommended:ro + working_dir: /rules diff --git a/runtime/requirements.txt b/runtime/requirements.txt new file mode 100644 index 0000000..9342340 --- /dev/null +++ b/runtime/requirements.txt @@ -0,0 +1,2 @@ +pyyaml>=6.0 +python-frontmatter>=1.0 diff --git a/runtime/test-runner.py b/runtime/test-runner.py new file mode 100644 index 0000000..4448ed5 --- /dev/null +++ b/runtime/test-runner.py @@ -0,0 +1,497 @@ +#!/usr/bin/env python3 +"""Contributor test harness for reporails rules. + +Discovers rules, runs their checks against test fixtures, reports pass/fail. +Does NOT compute scores, levels, or invoke LLMs. +""" + +import argparse +import json +import os +import subprocess +import sys +import tempfile +from dataclasses import dataclass, field +from pathlib import Path + +import frontmatter +import yaml + +from checks import MECHANICAL_CHECKS, CheckResult + + +@dataclass +class RuleInfo: + id: str + slug: str + title: str + category: str + rule_type: str + level: str + targets: str + checks: list + rule_dir: Path + rule_yml: Path + + @property + def has_checks(self) -> bool: + return len(self.checks) > 0 + + @property + def has_pass_fixture(self) -> bool: + return (self.rule_dir / "tests" / "pass").is_dir() and any( + (self.rule_dir / "tests" / "pass").iterdir() + ) + + @property + def has_fail_fixture(self) -> bool: + return (self.rule_dir / "tests" / "fail").is_dir() and any( + (self.rule_dir / "tests" / "fail").iterdir() + ) + + +@dataclass +class CheckRun: + check_id: str + check_type: str + fixture: str # "pass" or "fail" + passed: bool + message: str + + +@dataclass +class RuleResult: + rule: RuleInfo + status: str # "passed", "failed", "not_implemented", "no_fixtures", "skipped" + check_runs: list = field(default_factory=list) + messages: list = field(default_factory=list) + + +def load_agent_config(rules_root: Path, agent: str) -> dict: + """Load agent config and build template var map.""" + config_path = rules_root / "agents" / agent / "config.yml" + if not config_path.exists(): + print(f"Warning: agent config not found: {config_path}", file=sys.stderr) + return {} + with open(config_path) as f: + config = yaml.safe_load(f) + return config.get("vars", {}) + + +def resolve_var(template: str, agent_vars: dict) -> list[str]: + """Resolve a template variable like {{instruction_files}} to its values.""" + if not template.startswith("{{") or not template.endswith("}}"): + return [template] + var_name = template[2:-2] + value = agent_vars.get(var_name, template) + if isinstance(value, list): + return value + return [value] + + +def _scan_root(root: Path) -> list[Path]: + """Find all rule directories under a single root (core/ + agents/*/rules/).""" + dirs = [] + + core_dir = root / "core" + if core_dir.exists(): + for category_dir in sorted(core_dir.iterdir()): + if category_dir.is_dir(): + for slug_dir in sorted(category_dir.iterdir()): + if slug_dir.is_dir(): + dirs.append(slug_dir) + + agents_dir = root / "agents" + if agents_dir.exists(): + for agent_dir in sorted(agents_dir.iterdir()): + rules_subdir = agent_dir / "rules" + if rules_subdir.is_dir(): + for slug_dir in sorted(rules_subdir.iterdir()): + if slug_dir.is_dir(): + dirs.append(slug_dir) + + return dirs + + +def discover_rules(rules_root: Path, filter_path: str = None, filter_rule: str = None, + package_roots: list[Path] = None) -> list[RuleInfo]: + """Walk core/ and agents/*/rules/ for rule.md files across all roots.""" + rules = [] + + # Build (root, slug_dir) pairs from primary root + any package roots + all_roots = [rules_root] + (package_roots or []) + search_pairs = [] + for root in all_roots: + for slug_dir in _scan_root(root): + search_pairs.append((root, slug_dir)) + + for root, slug_dir in search_pairs: + rule_md = slug_dir / "rule.md" + rule_yml = slug_dir / "rule.yml" + if not rule_md.exists(): + continue + + # Apply path filter (relative to the owning root) + if filter_path: + rel = str(slug_dir.relative_to(root)) + if not rel.startswith(filter_path.rstrip("/")): + continue + + post = frontmatter.load(str(rule_md)) + meta = post.metadata + + rule_id = meta.get("id", "") + + # Apply rule ID filter + if filter_rule and rule_id != filter_rule: + continue + + rules.append(RuleInfo( + id=rule_id, + slug=meta.get("slug", ""), + title=meta.get("title", ""), + category=meta.get("category", ""), + rule_type=meta.get("type", ""), + level=meta.get("level", ""), + targets=meta.get("targets", ""), + checks=meta.get("checks", []), + rule_dir=slug_dir, + rule_yml=rule_yml, + )) + + return rules + + +def run_mechanical_check(check: dict, fixture_root: Path, agent_vars: dict) -> CheckResult: + """Run a single mechanical check against a fixture directory.""" + check_name = check.get("check", "") + args = check.get("args", {}) + + if check_name not in MECHANICAL_CHECKS: + return CheckResult(passed=False, message=f"Unknown mechanical check: {check_name}") + + result = MECHANICAL_CHECKS[check_name](fixture_root, args, agent_vars) + if args.get("negate"): + result = CheckResult(passed=not result.passed, message=result.message) + return result + + +def _resolve_vars_in_rule(rule: dict, agent_vars: dict) -> dict: + """Recursively resolve {{var}} placeholders in an OpenGrep rule dict.""" + import copy + rule = copy.deepcopy(rule) + + def resolve(value): + if isinstance(value, str): + for key, val in agent_vars.items(): + placeholder = "{{" + key + "}}" + if placeholder in value: + # If the entire string is a placeholder and val is a list, + # return the list (for paths.include expansion) + if value == placeholder and isinstance(val, list): + return val + if isinstance(val, list): + value = value.replace(placeholder, val[0] if val else "") + else: + value = value.replace(placeholder, str(val)) + return value + if isinstance(value, list): + expanded = [] + for item in value: + resolved = resolve(item) + if isinstance(resolved, list): + expanded.extend(resolved) + else: + expanded.append(resolved) + return expanded + if isinstance(value, dict): + return {k: resolve(v) for k, v in value.items()} + return value + + return resolve(rule) + + +def run_opengrep_check(rule_yml: Path, fixture_root: Path, check: dict, verbose: bool = False, agent_vars: dict = None) -> CheckResult: + """Run OpenGrep against a fixture directory for a deterministic check.""" + if not rule_yml.exists(): + return CheckResult(passed=False, message=f"rule.yml not found: {rule_yml}") + + with open(rule_yml) as f: + yml_content = yaml.safe_load(f) + + yml_rules = yml_content.get("rules", []) + if not yml_rules: + return CheckResult(passed=False, message="rule.yml has no patterns (rules: [])") + + # Find the matching rule entry by check ID + # rule.md uses colon format (CORE:S:0001:check:0001) + # rule.yml uses dot format (CORE.S.0001.check.0001) for OpenGrep compatibility + check_id = check.get("id", "") + check_id_dotted = check_id.replace(":", ".") + matching_rule = None + for r in yml_rules: + if r.get("id") == check_id_dotted: + matching_rule = r + break + + # If no exact match, use first rule (single-pattern rules) + if matching_rule is None and len(yml_rules) == 1: + matching_rule = yml_rules[0] + + if matching_rule is None: + return CheckResult( + passed=False, + message=f"No OpenGrep pattern found for check {check_id} in rule.yml", + ) + + # Resolve template variables in the rule + if agent_vars: + matching_rule = _resolve_vars_in_rule(matching_rule, agent_vars) + + # Write a temp rule file with just this pattern + with tempfile.NamedTemporaryFile(mode="w", suffix=".yml", delete=False) as tmp: + yaml.dump({"rules": [matching_rule]}, tmp) + tmp_path = tmp.name + + try: + result = subprocess.run( + ["opengrep", "scan", "--config", tmp_path, "--json", str(fixture_root)], + capture_output=True, + text=True, + timeout=30, + ) + + if verbose: + print(f" opengrep stdout: {result.stdout[:500]}", file=sys.stderr) + if result.stderr: + print(f" opengrep stderr: {result.stderr[:500]}", file=sys.stderr) + + # Parse JSON output for findings + try: + output = json.loads(result.stdout) if result.stdout.strip() else {} + except json.JSONDecodeError: + # opengrep may output non-JSON on error + if result.returncode != 0: + return CheckResult( + passed=False, + message=f"OpenGrep error (exit {result.returncode}): {result.stderr[:200]}", + ) + output = {} + + findings = output.get("results", []) + return CheckResult( + passed=True, + message=f"{len(findings)} finding(s)", + findings_count=len(findings), + ) + except FileNotFoundError: + return CheckResult(passed=False, message="opengrep not found — run inside Docker") + except subprocess.TimeoutExpired: + return CheckResult(passed=False, message="OpenGrep timed out (30s)") + finally: + os.unlink(tmp_path) + + +def run_rule(rule: RuleInfo, agent_vars: dict, verbose: bool = False) -> RuleResult: + """Run all checks for a rule against its fixtures.""" + result = RuleResult(rule=rule, status="passed") + + if not rule.has_checks: + result.status = "not_implemented" + result.messages.append("checks: [] — not implemented") + return result + + if not rule.has_pass_fixture and not rule.has_fail_fixture: + result.status = "no_fixtures" + result.messages.append("No test fixtures (tests/pass/ or tests/fail/ empty)") + return result + + pass_dir = rule.rule_dir / "tests" / "pass" + fail_dir = rule.rule_dir / "tests" / "fail" + + # Track whether at least one check detects a violation on the fail fixture. + # Multi-check rules may have some checks pass and others fail on the fail + # fixture — that's expected. Only require at least one violation detected. + fail_violation_found = False + + for check in rule.checks: + check_id = check.get("id", "unknown") + check_type = check.get("type", "unknown") + negate = check.get("negate", False) + + # === Pass fixture: ALL checks must pass (no violations) === + if rule.has_pass_fixture: + if check_type == "mechanical": + cr = run_mechanical_check(check, pass_dir, agent_vars) + passed = cr.passed + run = CheckRun(check_id, check_type, "pass", passed, cr.message) + elif check_type == "deterministic": + cr = run_opengrep_check(rule.rule_yml, pass_dir, check, verbose, agent_vars) + if negate: + # Negated: findings = desired content exists = pass + passed = cr.passed and cr.findings_count > 0 + else: + # Normal: 0 findings = no violations = pass + passed = cr.passed and cr.findings_count == 0 + run = CheckRun(check_id, check_type, "pass", passed, cr.message) + elif check_type == "semantic": + # Semantic checks: only validate that pre-checks ran + run = CheckRun(check_id, check_type, "pass", True, "semantic — skipped (no LLM)") + passed = True + else: + run = CheckRun(check_id, check_type, "pass", False, f"unknown check type: {check_type}") + passed = False + + result.check_runs.append(run) + if not passed: + result.status = "failed" + + # === Fail fixture: at least ONE check must detect a violation === + if rule.has_fail_fixture: + if check_type == "mechanical": + cr = run_mechanical_check(check, fail_dir, agent_vars) + violation = not cr.passed + msg = cr.message + run = CheckRun(check_id, check_type, "fail", True, msg) + elif check_type == "deterministic": + cr = run_opengrep_check(rule.rule_yml, fail_dir, check, verbose, agent_vars) + if negate: + # Negated: 0 findings = desired content missing = violation + violation = cr.passed and cr.findings_count == 0 + msg = cr.message + else: + # Normal: 1+ findings = violations found + violation = cr.passed and cr.findings_count > 0 + msg = cr.message + run = CheckRun(check_id, check_type, "fail", True, msg) + elif check_type == "semantic": + run = CheckRun(check_id, check_type, "fail", True, "semantic — skipped (no LLM)") + violation = False + else: + run = CheckRun(check_id, check_type, "fail", False, f"unknown check type: {check_type}") + violation = False + + if violation: + fail_violation_found = True + result.check_runs.append(run) + + # After all checks: fail fixture must have triggered at least one violation + if rule.has_fail_fixture and not fail_violation_found: + result.status = "failed" + result.messages.append("Fail fixture: no check detected a violation") + + return result + + +def print_results(results: list[RuleResult], verbose: bool = False): + """Print test results summary.""" + passed = [r for r in results if r.status == "passed"] + failed = [r for r in results if r.status == "failed"] + not_impl = [r for r in results if r.status == "not_implemented"] + no_fix = [r for r in results if r.status == "no_fixtures"] + skipped = [r for r in results if r.status == "skipped"] + + print() + print("=" * 60) + print("REPORAILS RULE TEST RESULTS") + print("=" * 60) + print() + + # Print failures first + if failed: + print("FAILURES:") + print("-" * 40) + for r in failed: + print(f" FAIL {r.rule.id} ({r.rule.slug})") + for run in r.check_runs: + status = "PASS" if run.passed else "FAIL" + print(f" [{status}] {run.check_id} ({run.check_type}, {run.fixture} fixture): {run.message}") + print() + + # Print passes + if passed and verbose: + print("PASSES:") + print("-" * 40) + for r in passed: + print(f" PASS {r.rule.id} ({r.rule.slug})") + for run in r.check_runs: + print(f" [PASS] {run.check_id} ({run.check_type}, {run.fixture} fixture): {run.message}") + print() + + # Summary + print("SUMMARY:") + print("-" * 40) + print(f" Passed: {len(passed)}") + print(f" Failed: {len(failed)}") + print(f" Not implemented: {len(not_impl)}") + print(f" No fixtures: {len(no_fix)}") + if skipped: + print(f" Skipped: {len(skipped)}") + print(f" Total: {len(results)}") + print() + + if not_impl: + print(f"Not implemented ({len(not_impl)}):") + for r in not_impl: + print(f" - {r.rule.id} {r.rule.slug}") + print() + + return len(failed) + + +def main(): + parser = argparse.ArgumentParser( + description="Test harness for reporails rules", + epilog="Examples:\n" + " python test-runner.py # All rules\n" + " python test-runner.py core/structure/ # One category\n" + " python test-runner.py --rule CORE:S:0001 # One rule by coordinate\n" + " python test-runner.py --agent codex # Use codex vars\n" + " python test-runner.py --verbose # Show OpenGrep output\n", + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + parser.add_argument("path", nargs="?", default=None, help="Filter by path prefix (e.g., core/structure/)") + parser.add_argument("--rule", "-r", default=None, help="Filter by rule coordinate (e.g., CORE:S:0001)") + parser.add_argument("--agent", "-a", default="claude", help="Agent config for var resolution (default: claude)") + parser.add_argument("--verbose", "-v", action="store_true", help="Show detailed output") + parser.add_argument("--rules-root", default=".", help="Path to rules repo root (default: .)") + parser.add_argument("--package", "-p", action="append", default=[], help="Additional package root(s) to scan (e.g., /recommended)") + + args = parser.parse_args() + rules_root = Path(args.rules_root).resolve() + package_roots = [Path(p).resolve() for p in args.package] + + # Load agent config (always from primary rules root) + agent_vars = load_agent_config(rules_root, args.agent) + if args.verbose: + print(f"Agent: {args.agent}", file=sys.stderr) + print(f"Vars: {agent_vars}", file=sys.stderr) + if package_roots: + print(f"Packages: {[str(p) for p in package_roots]}", file=sys.stderr) + + # Discover rules + rules = discover_rules(rules_root, filter_path=args.path, filter_rule=args.rule, + package_roots=package_roots) + if not rules: + print("No rules found.", file=sys.stderr) + sys.exit(1) + + print(f"Discovered {len(rules)} rule(s)") + + # Run checks + results = [] + for rule in rules: + result = run_rule(rule, agent_vars, verbose=args.verbose) + results.append(result) + + # Progress indicator + icon = {"passed": ".", "failed": "F", "not_implemented": "-", "no_fixtures": "?", "skipped": "S"} + print(icon.get(result.status, "?"), end="", flush=True) + + # Print results + fail_count = print_results(results, verbose=args.verbose) + sys.exit(1 if fail_count > 0 else 0) + + +if __name__ == "__main__": + main() diff --git a/schemas/agent.schema.yml b/schemas/agent.schema.yml index dcebd38..5412987 100644 --- a/schemas/agent.schema.yml +++ b/schemas/agent.schema.yml @@ -1,242 +1,116 @@ -# Schema definition for agent configuration -# Used by: ails validate, agents, contributors +# Agent configuration schema +version: "0.1.0" -version: "0.0.2" - -# Migration from v1: -# - Clarified: agent rules use SEPARATE namespace (CLAUDE_S1 ≠ override of S1) -# - Added: pattern_overrides folder for modifying core patterns -# - Clarified: config overrides are severity-only; pattern changes use files - -# ============================================================================= -# AGENT CONFIG -# ============================================================================= -# Each agent defines: -# - Identity (agent, prefix, name) -# - File patterns (vars) -# - What core rules don't apply (excludes) -# - Severity adjustments (overrides in config) -# - Pattern modifications (overrides/ folder) -# ============================================================================= - -# Reference: reserved_agent_prefixes defined in rule.schema.yml -# Agents must use a prefix from that list. +# Simplified from v0.0.2: removed pattern_overrides. +# instruction_files patterns live here (moved from project config). fields: agent: required: true type: string pattern: "^[a-z]+$" - description: "Agent identifier (lowercase)" + description: "Agent identifier. Uppercase = coordinate registry prefix." - prefix: + version: required: true type: string + pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$" + description: "Semver version of this agent configuration" + + prefix: + required: false + type: string pattern: "^[A-Z]+$" - description: "Rule ID prefix for agent-specific rules. Must be in reserved_agent_prefixes (see rule.schema.yml)" + description: "Uppercase agent prefix for coordinate namespacing (e.g., CLAUDE, CODEX)" name: - required: true + required: false type: string - max_length: 64 - description: "Human-readable agent name (max 64 chars)" + description: "Human-readable display name for the agent" vars: required: true type: object - description: "Template variables for rule patterns. Universal vars required, agent-specific optional." + description: "Template variables resolved by CLI for rule targets and capability detection" properties: - # Universal variables (REQUIRED for all agents) main_instruction_file: required: true - type: array - items: - type: string - description: "Primary instruction file(s) — document-level rules check only these" + type: + oneOf: [string, array] + description: "Primary instruction file glob(s) (e.g., '**/CLAUDE.md' or list)" instruction_files: required: true - type: array - items: - type: string - description: "All instruction files (main + supplementary) — content rules check all" - # Agent-specific variables (optional, only if agent supports the feature) + type: + oneOf: [string, array] + description: "All instruction files glob(s) (main + nested)" supplementary_files: required: false - type: array - items: - type: string - description: "Rule snippet files (excludes main) — for agents with rules directory" + type: + oneOf: [string, array] + description: "Rule snippet files, excluding main instruction file" rules_dir: required: false type: string - description: "Rules directory path — for agents with hierarchical rules" + description: "Path-scoped rules directory" skills_dir: required: false type: string - description: "Skills directory path — for agents with skills support" + description: "Skills directory path" additionalProperties: type: string - description: "Additional agent-specific variables" + description: "Agent-specific vars (e.g., settings_file, mcp_config, memory_dir)" excludes: required: false type: array + description: "Glob patterns to exclude from all rule target resolution" items: type: string - pattern: "^[SCEGM][0-9]+$" - description: "Core rule IDs that don't apply to this agent" overrides: required: false type: object - description: "Per-check SEVERITY overrides in config (key = check ID). For pattern changes, use overrides/ folder." + description: "Per-rule severity overrides keyed by coordinate (e.g., RRAILS:C:0008)" additionalProperties: type: object properties: severity: - type: enum - values: [critical, high, medium, low] - description: "Override default severity" - disabled: - type: boolean - description: "Disable this check for this agent" - -# ============================================================================= -# PATTERN OVERRIDES (FILE-BASED) -# ============================================================================= -# For modifying core rule PATTERNS (not just severity), use override files: -# -# agents/{agent}/overrides/{rule_id}.yml -# -# Override files are MERGED with core rules at check-level: -# - Check in override replaces core check entirely -# - Check with `disabled: true` is removed from final -# - Checks not mentioned inherit from core -# -# Example: agents/claude/overrides/S1.yml -# rules: -# - id: S1-root-too-long -# message: "Root file exceeds Claude's 300 line limit" -# severity: WARNING -# languages: [generic] -# pattern-regex: "(?s)(?:[^\\n]*\\n){300,}" # changed threshold -# -# - id: S1-many-sections -# disabled: true # opt out this check for Claude -# -# Merge resolution: -# 1. Load core/{category}/{rule}/*.yml -# 2. If agents/{agent}/overrides/{rule_id}.yml exists: -# - For each check in override: replace or disable -# - Checks not in override: keep from core -# 3. Result: single merged ruleset for OpenGrep -# -# ============================================================================= - -# ============================================================================= -# VALIDATION -# ============================================================================= + type: string + enum: [low, medium, high] validation: - # Identity - - rule: "agent must be lowercase letters only" - - rule: "prefix must be UPPERCASE letters only" - - rule: "prefix must be in reserved_agent_prefixes (see rule.schema.yml)" - - # Vars - Universal (required) - - rule: "vars.main_instruction_file is required" - - rule: "vars.instruction_files is required" - - # Vars - Agent-specific (optional) - - rule: "supplementary_files, rules_dir, skills_dir only needed if agent supports them" - - # Excludes - - rule: "excludes items must be valid core rule IDs" - - # Config Overrides (severity only) - - rule: "overrides keys must be valid check IDs" - - rule: "overrides severity must be valid severity value" - - rule: "overrides in config.yml are for severity changes only" - - # Pattern Overrides (file-based) - - rule: "pattern override files go in agents/{agent}/overrides/{rule_id}.yml" - - rule: "override file check IDs must match core rule check IDs" - - rule: "override checks with disabled: true are removed from final ruleset" - -# ============================================================================= -# EXAMPLES -# ============================================================================= + - rule: "agent uppercase must be in reserved_agent_prefixes (see rule.schema.yml)" examples: claude: | - # Full-featured agent with rules directory agent: claude - prefix: CLAUDE - name: Claude Code - + version: "0.1.0" vars: - # Universal (required) - main_instruction_file: - - "**/CLAUDE.md" - instruction_files: - - "**/CLAUDE.md" - - ".claude/rules/**/*.md" - # Agent-specific (Claude supports rules directory) - supplementary_files: - - ".claude/rules/**/*.md" + main_instruction_file: "**/CLAUDE.md" + instruction_files: "**/CLAUDE.md" + supplementary_files: ".claude/rules/**/*.md" rules_dir: ".claude/rules" skills_dir: ".claude/skills" - - # Severity adjustments (pattern unchanged) - overrides: - E2-too-many-imports: - severity: medium + settings_file: ".claude/settings.json" + mcp_config: ".mcp.json" + memory_dir: "memory" + excludes: + - "node_modules/**" + - ".git/**" + - "archive/**" copilot: | - # Minimal agent with single file agent: copilot - prefix: COPILOT - name: GitHub Copilot - + version: "0.1.0" vars: - # Universal only — no rules directory support - main_instruction_file: - - ".github/copilot-instructions.md" - instruction_files: - - ".github/copilot-instructions.md" - - # No excludes — all core rules (S1-S4, C1-C5, E1-E2, M1-M4) apply + main_instruction_file: ".github/copilot-instructions.md" + instruction_files: ".github/copilot-instructions.md" cursor: | - # Agent with rules directory support agent: cursor - prefix: CURSOR - name: Cursor - + version: "0.1.0" vars: - main_instruction_file: - - "**/.cursorrules" - instruction_files: - - "**/.cursorrules" - - ".cursor/rules/**/*.md" - supplementary_files: - - ".cursor/rules/**/*.md" + main_instruction_file: "**/.cursorrules" + instruction_files: "**/.cursorrules" + supplementary_files: ".cursor/rules/**/*.md" rules_dir: ".cursor/rules" - - pattern_override: | - # Example: Override core S1 patterns for an agent - # File: agents/myagent/overrides/S1.yml - - rules: - # Replace this check with different threshold - - id: S1-root-too-long - message: "Root file exceeds 300 line limit" - severity: WARNING - languages: [generic] - pattern-regex: "(?s)(?:[^\\n]*\\n){300,}" - - # Opt out of this check entirely - - id: S1-many-sections - disabled: true - - # S1-other-check not listed = inherited from core \ No newline at end of file diff --git a/schemas/capability.schema.yml b/schemas/capability.schema.yml new file mode 100644 index 0000000..7d6b826 --- /dev/null +++ b/schemas/capability.schema.yml @@ -0,0 +1,28 @@ +# Capability taxonomy schema +version: "0.1.0" + +fields: + id: + required: true + type: string + pattern: "^[a-z][a-z0-9_]*$" + description: "Unique capability identifier (snake_case)" + + level: + required: true + type: enum + values: [L1, L2, L3, L4, L5, L6] + description: "Which level this capability belongs to" + + description: + required: true + type: string + description: "What this capability means and how to recognize it" + + threshold: + required: false + type: object + description: "Detection parameters (e.g., min_lines, min_sections, has_any_of)" + +validation: + - rule: "id must be unique across all capabilities" \ No newline at end of file diff --git a/schemas/levels.schema.yml b/schemas/levels.schema.yml index 5ac6f53..7685ec2 100644 --- a/schemas/levels.schema.yml +++ b/schemas/levels.schema.yml @@ -1,6 +1,5 @@ -# Schema for levels.yml -# Canonical level-to-rule mappings consumed by CLI -version: "0.0.1" +# Levels schema +version: "0.1.0" fields: levels: @@ -16,30 +15,47 @@ fields: description: required: true type: string - description: "One-line description of what the level enables" - rules: + description: "What this level represents" + capabilities: required: true type: array + description: "Capability IDs required at this level (must exist in registry/capabilities.yml)" items: type: string - pattern: "^(CLAUDE_)?[A-Z]+[0-9]+$" - description: "Rule IDs introduced at this level (not cumulative)" + pattern: "^[a-z][a-z0-9_]*$" validation: - - rule: "L0 must exist with empty rules array" - - rule: "L1 through L6 must each exist" - - rule: "Each rule ID must appear in exactly one level" - - rule: "Rule IDs must match pattern: optional agent prefix + category letter(s) + number" - - rule: "Rules within a level are listed in matrix row order (not sorted)" + - rule: "Each capability ID must appear in exactly one level" + - rule: "Capability IDs must exist in registry/capabilities.yml" examples: - minimal: | + full: | levels: L0: name: Absent - description: No instruction file - rules: [] + description: "No instruction file exists" + capabilities: [] L1: name: Basic - description: Instruction file exists, reviewed, has basic content - rules: [CLAUDE_M1, M1] + description: "A non-trivial, tracked instruction file exists" + capabilities: [instruction_file] + L2: + name: Scoped + description: "Project-specific constraints defined, file is focused" + capabilities: [project_constraints, size_controlled] + L3: + name: Structured + description: "Guidance is modular with external references" + capabilities: [external_references, multiple_files] + L4: + name: Abstracted + description: "Instructions adapt based on code location" + capabilities: [path_scoping] + L5: + name: Maintained + description: "Structurally sound, governed, and navigable" + capabilities: [structural_integrity, org_policy, navigation] + L6: + name: Adaptive + description: "Dynamic context discovery and extensibility" + capabilities: [dynamic_context, extensibility, state_persistence] diff --git a/schemas/package.schema.yml b/schemas/package.schema.yml index ef6f99b..6ee3d50 100644 --- a/schemas/package.schema.yml +++ b/schemas/package.schema.yml @@ -1,34 +1,8 @@ -# Schema definition for rule package configuration -# Used by: ails validate, package authors, contributors +# Package configuration schema +version: "0.1.0" -version: "0.0.1" - -# ============================================================================= -# PACKAGE CONFIG -# ============================================================================= -# Packages extend the core rule set with additional rules. -# They slot between Core and Agent in the resolution stack: -# -# ┌─────────────────────────────────────┐ -# │ User/Local │ Can: define, override, exclude -# ├─────────────────────────────────────┤ -# │ Agent │ Can: define, override, exclude core + package -# ├─────────────────────────────────────┤ -# │ Package(s) │ Can: define rules, override/exclude core -# ├─────────────────────────────────────┤ -# │ Core │ Universal baseline (all agents) -# └─────────────────────────────────────┘ -# -# Key differences from agent config: -# - No vars (packages don't define file patterns) -# - Has provides (declares what the package contributes) -# - Has depends_on (schema version dependency) -# - Has version (package versioning) -# - Resolution: adds rules available to all agents (not agent-specific) -# ============================================================================= - -# Reference: reserved_package_prefixes defined in rule.schema.yml -# Packages must use a prefix from that list. +# Updated from v0.0.1: AILS→RRAILS, coordinate format, +# removed provides.levels (rules self-declare level). fields: package: @@ -88,11 +62,7 @@ fields: rules: required: true type: boolean - description: "Whether the package provides rule directories" - levels: - required: false - type: boolean - description: "Whether the package provides its own levels.yml" + description: "Must be true — every package provides rules" sources: required: false type: boolean @@ -111,7 +81,7 @@ fields: required: true type: string pattern: "^[A-Z]{3,}_[A-Z]+$" - description: "Agent rules prefix within package namespace (e.g., AILS_CLAUDE)" + description: "Agent rules prefix within package namespace (e.g., RRAILS_CLAUDE)" description: "Agent-specific rules provided by this package" excludes: @@ -119,8 +89,8 @@ fields: type: array items: type: string - pattern: "^[SCEGM][0-9]+$" - description: "Core rule IDs this package opts out of" + pattern: "^CORE:[SCEMG]:[0-9]{4}$" + description: "Core rule IDs this package opts out of" overrides: required: false @@ -134,152 +104,39 @@ fields: values: [critical, high, medium, low] description: "Override default severity" -# ============================================================================= -# SCHEMA RESOLUTION -# ============================================================================= -# Packages declare their schema dependency via depends_on. At validation time, -# the schema source is fetched by git tag matching min_version: -# -# git clone --depth 1 --branch <min_version> <source> /tmp/reporails-schemas -# -# The fetched schemas/ directory is used to validate the package's rules. -# -# Resolution steps: -# 1. Read config.yml → depends_on.source, depends_on.min_version -# 2. Clone source repo at tag matching min_version (shallow, schemas/ only) -# 3. Validate package rules against fetched schemas/rule.schema.yml -# 4. Validate package config against fetched schemas/package.schema.yml -# -# Tag convention: tags match schema version (e.g., 0.0.7) -# -# Offline / CI caching: -# - CI can cache the cloned schemas between runs (keyed on min_version) -# - For offline use, pre-fetch and set REPORAILS_SCHEMAS_PATH env var -# -# Example CI step (GitHub Actions): -# - name: Fetch core schemas -# run: | -# VERSION=$(yq '.depends_on.min_version' config.yml) -# SOURCE=$(yq '.depends_on.source' config.yml) -# git clone --depth 1 --branch "$VERSION" "$SOURCE" /tmp/core-schemas -# -# - name: Validate package -# run: ails validate --schemas /tmp/core-schemas/schemas -# ============================================================================= - -# ============================================================================= -# ID PATTERNS -# ============================================================================= -# Package rules follow: {PACKAGE_PREFIX}_{category}{number} -# e.g., AILS_S1, AILS_C1, AILS_E1 -# -# Package agent rules follow: {PACKAGE_PREFIX}_{AGENT}_{category}{number} -# e.g., AILS_CLAUDE_S1, AILS_CLAUDE_M1 -# -# See rule.schema.yml fields.id.pattern for regex patterns. -# ============================================================================= - -# ============================================================================= -# VALIDATION -# ============================================================================= - validation: - # Identity - - rule: "package must be lowercase letters, digits, and hyphens" - - rule: "prefix must be 3+ UPPERCASE letters" - - rule: "prefix must be in reserved_package_prefixes (see rule.schema.yml)" - - rule: "prefix must NOT be in reserved_agent_prefixes (see rule.schema.yml)" - - rule: "name must be max 64 characters" - - # Version - - rule: "version must be valid semver" - - # Dependencies - - rule: "depends_on.schema must reference a valid schema repository" - - rule: "depends_on.source must be a valid git repository URL" - - rule: "depends_on.min_version must be valid semver" - - rule: "depends_on.min_version must be <= current rule schema version" - - rule: "depends_on.source repo must have a tag matching min_version" - - # Provides + - rule: "prefix must be in reserved_package_prefixes" + - rule: "prefix must NOT be in reserved_agent_prefixes" - rule: "provides.rules is required and must be true" - - rule: "provides.agent_rules[].agent must match a reserved_agent_prefixes entry" - rule: "provides.agent_rules[].prefix must start with the package prefix" - - # Excludes - - rule: "excludes items must be valid core rule IDs" - - # Overrides - - rule: "overrides keys must be valid check IDs" - - rule: "overrides severity must be valid severity value" - -# ============================================================================= -# EXAMPLES -# ============================================================================= + - rule: "excludes items must be valid core rule coordinates" examples: recommended: | - # The canonical package: reporails/recommended package: recommended - prefix: AILS + prefix: RRAILS name: Reporails Recommended Rules - description: Opinionated best practices, governance, and process rules + description: Opinionated best practices and governance version: "0.2.2" - depends_on: schema: "reporails/rules" - min_version: "0.0.7" + min_version: "0.1.0" source: "https://github.com/reporails/rules.git" - provides: rules: true - levels: true sources: true agent_rules: - agent: claude - prefix: AILS_CLAUDE - - # No core rules excluded or overridden by this package - excludes: [] - overrides: {} + prefix: RRAILS_CLAUDE minimal: | - # Minimal package with just rules package: my-rules prefix: MYR name: My Custom Rules version: "1.0.0" - - depends_on: - schema: "reporails/rules" - min_version: "0.0.7" - source: "https://github.com/reporails/rules.git" - - provides: - rules: true - - with_exclusions: | - # Package that replaces some core rules - package: strict-docs - prefix: SDOC - name: Strict Documentation Rules - description: Stricter documentation rules that replace core defaults - version: "1.0.0" - depends_on: schema: "reporails/rules" - min_version: "0.0.7" + min_version: "0.1.0" source: "https://github.com/reporails/rules.git" - provides: rules: true - levels: true - - # Replace core size limits with stricter package version - excludes: - - S1 - - # Make missing project description critical - overrides: - C3-no-description: - severity: critical diff --git a/schemas/project.schema.yml b/schemas/project.schema.yml index a3c352f..edbb14d 100644 --- a/schemas/project.schema.yml +++ b/schemas/project.schema.yml @@ -1,124 +1,101 @@ -# Schema for .reporails/config.yml -# Project-level configuration — committed to git -version: "0.0.3" +# Project configuration schema (.reporails/config.yml) +version: "0.1.0" -# Migration from v2: -# - Replaced confidence/profile with tiers (core/experimental) -# - Aligns with tier derivation model: core (max source weight >= 0.8), experimental (< 0.8) +# Removed instruction_files (moved to agent config). +# Updated rules.disabled/overrides for coordinate format. fields: schema_version: required: true - type: integer - default: 1 - description: "Config schema version for forward compatibility" + type: string + pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$" + default: "0.1.0" + description: "Config schema version (semver). CLI validates against supported range." agent: required: false type: string default: "claude" - description: "Primary agent to check against (matches agents/{agent}/config.yml)" - - instruction_files: - required: false - type: object - description: "Defines which files are analyzed and their roles" - properties: - main: - type: string - default: "**/CLAUDE.md" - description: "Main instruction file — document-level rules apply here only" - supplementary: - type: string - default: ".claude/rules/**/*.md" - description: "Supplementary files — content rules apply, not document-level" - exclude: - type: array - items: - type: string - description: "Glob patterns to exclude from all analysis" + description: "Default agent for this project (loads agent config from rules repo)" components: required: false type: array - description: "Monorepo component definitions (optional)" + description: "Monorepo component definitions for multi-path scoring" items: type: object properties: path: required: true type: string - description: "Glob pattern or path to component root" + description: "Relative path to component root" main: type: string default: "CLAUDE.md" - description: "Main instruction file relative to component root" + description: "Component's primary instruction file" expected_level: type: string - pattern: "^L[1-5]$" - description: "Expected capability level — violations if below" + pattern: "^L[1-6]$" + description: "Target capability level for this component" role: type: enum - values: [orchestrator, component, library, docs] + values: [coordinator, component, library, docs] default: component - description: "Affects which rules apply" + description: "Component role (affects which rules apply)" rules: required: false type: object - description: "Rule customizations for this project" + description: "Project-level rule overrides and exclusions" properties: disabled: type: array + description: "Rule coordinates to skip entirely" items: type: string - pattern: "^[SCEGM][0-9]+$" - description: "Rule IDs to skip entirely" + pattern: "^[A-Z_]+:[SCEMG]:[0-9]{4}$" overrides: type: object + description: "Per-check severity adjustments (key = check coordinate)" additionalProperties: type: object properties: severity: type: enum values: [critical, high, medium, low] + description: "Override default severity for this check" disabled: type: boolean - description: "Per-check overrides keyed by check ID" + description: "Disable this specific check" scoring: required: false type: object + description: "Scoring configuration for CLI output" properties: scope: type: enum values: [main, all, aggregate] default: main - description: | - main: Score only main instruction file(s) - all: Score all files as one unit - aggregate: Separate score per component (monorepo) + description: "What to score: main file only, all files, or aggregate across components" tiers: required: false type: object - description: "Filter rules by evidence tier" + description: "Orthogonal to levels: evidence confidence vs concern level" properties: core: type: boolean default: true - description: "Enforce core rules (backed by official/research sources, max weight >= 0.8)" + description: "Enforce rules backed by official/research sources (weight >= 0.8)" experimental: type: boolean default: true - description: "Enforce experimental rules (community-only sources, max weight < 0.8)" + description: "Enforce rules backed by community sources only (weight < 0.8)" defaults: - schema_version: 3 + schema_version: "0.1.0" agent: "claude" - instruction_files: - main: "**/CLAUDE.md" - supplementary: ".claude/rules/**/*.md" scoring: scope: main tiers: @@ -126,87 +103,40 @@ defaults: experimental: true validation: - - rule: "schema_version must be supported (currently: 1, 2, or 3)" - - rule: "Unknown fields should warn, not error (forward compatibility)" - - rule: "Invalid patterns should error with clear message" - - rule: "If tiers.core is false, no rules are enforced (core is the minimum set)" + - rule: "schema_version must be supported (currently: 0.1.0)" + - rule: "Unknown fields should warn, not error" + - rule: "If tiers.core is false, no rules are enforced" + - rule: "rules.disabled items must be valid rule coordinates" + - rule: "rules.overrides keys must be valid check coordinates" examples: minimal: | - # Simplest config — all defaults - schema_version: 2 - - single_repo: | - # Standard single-repo setup - schema_version: 2 - agent: claude - - instruction_files: - main: "CLAUDE.md" - supplementary: ".claude/rules/**/*.md" + schema_version: "0.1.0" monorepo: | - # Monorepo with orchestrator + components - schema_version: 2 + schema_version: "0.1.0" agent: claude - - instruction_files: - main: "CLAUDE.md" # Root orchestrator - supplementary: ".claude/rules/**/*.md" - exclude: - - "**/node_modules/**" - - "**/dist/**" - components: - path: "packages/api" role: component expected_level: L3 - - path: "packages/web" - role: component - expected_level: L3 - path: "packages/shared" role: library expected_level: L2 - - path: "docs" - role: docs - expected_level: L1 - scoring: scope: aggregate with_overrides: | - # Customized rules - schema_version: 2 + schema_version: "0.1.0" agent: claude - rules: - disabled: - - E5 # We don't use grep guidance pattern - - E4 # Memory handled differently + disabled: ["CORE:E:0002"] overrides: - S1-root-too-long: - severity: medium # We allow longer root files - C12-no-version: - disabled: true # We use git tags instead + "CORE:S:0001:check:0001": + severity: medium - multi_agent: | - # Checking multiple agents (future) - schema_version: 2 - agent: claude # Primary - # Additional agents would need separate check runs - - enterprise_strict: | - # Only enforce validated rules (official + research backed) - schema_version: 2 - agent: claude + strict: | + schema_version: "0.1.0" tiers: core: true experimental: false - - early_adopter: | - # Include experimental community patterns - schema_version: 2 - agent: claude - tiers: - core: true - experimental: true diff --git a/schemas/rule.schema.yml b/schemas/rule.schema.yml index 04df1d2..e9a8715 100644 --- a/schemas/rule.schema.yml +++ b/schemas/rule.schema.yml @@ -1,16 +1,8 @@ -# Schema definition for rule frontmatter -# Used by: ails check, ails validate, agents, contributors - -version: "0.0.7" - -# ============================================================================= -# RULE TYPES -# ============================================================================= -# deterministic: OpenGrep decides. No LLM. -# semantic: OpenGrep first, LLM fills gaps. -# ============================================================================= +# Rule frontmatter schema +version: "0.1.0" types: + - mechanical - deterministic - semantic @@ -18,8 +10,8 @@ categories: - structure - content - efficiency - - governance - maintenance + - governance severities: - critical @@ -27,52 +19,13 @@ severities: - medium - low -# ============================================================================= -# RULE RESOLUTION STACK -# ============================================================================= -# Rules are resolved in layers (bottom to top). Higher layers win. -# -# ┌─────────────────────────────────────┐ -# │ User/Local │ Can: define, override, exclude -# ├─────────────────────────────────────┤ -# │ Agent │ Can: define, override, exclude core + package -# ├─────────────────────────────────────┤ -# │ Package(s) │ Can: define rules, override/exclude core -# ├─────────────────────────────────────┤ -# │ Core │ Universal baseline (all agents) -# └─────────────────────────────────────┘ -# -# Resolution for each file: -# 1. Collect applicable core rules -# 2. Apply package modifications: -# - excludes: remove core rules -# - overrides: adjust severity on core rules -# 3. Add package rules (AILS_S1, etc.) and package agent rules (AILS_CLAUDE_S1, etc.) -# 4. Apply agent modifications: -# - excludes: remove core + package rules -# - overrides (config): adjust severity -# - overrides (files): replace patterns -# 5. Add agent-specific rules (CLAUDE_*, CURSOR_*, etc.) -# 6. Apply user modifications (same as agent) -# 7. Add user-specific rules (USR_*, custom prefix) -# -# Namespaces: -# - Core: S1, S2, S3... (universal) -# - Package: AILS_S1, AILS_C1... (package's own sequence) -# - Package-Agent: AILS_CLAUDE_S1... (package agent rules) -# - Agent: CLAUDE_S1, CLAUDE_S2... (agent's own sequence) -# - User: USR_S1, ACME_S1... (user's own sequence) -# -# Override mechanisms: -# - Exclude rule: excludes: [S1] in config -# - Change severity: overrides: {S1-check: {severity: low}} in config -# - Change pattern: agents/{agent}/overrides/S1.yml -# -# ============================================================================= - -# ============================================================================= -# FIELDS -# ============================================================================= +levels: + - L1 + - L2 + - L3 + - L4 + - L5 + - L6 reserved_agent_prefixes: - CLAUDE @@ -85,381 +38,314 @@ reserved_agent_prefixes: - CONTINUE reserved_package_prefixes: - - AILS # reporails/recommended + - RRAILS fields: id: required: true type: string pattern: - core: "^[SCEGM][0-9]+$" - agent: "^[A-Z]+_[SCEGM][0-9]+$" - package: "^[A-Z]{3,}_[SCEGM][0-9]+$" - package_agent: "^[A-Z]{3,}_[A-Z]+_[SCEGM][0-9]+$" - custom: "^[A-Z]{3,}_[SCEGM][0-9]+$" - description: | - IMPORTANT: Namespaces are SEPARATE. Agent numbers are independent of core. - - Core: category + number (S1, S2, S3...) - - Universal rules, apply to all agents - - Located in core/{category}/{id}-{slug}/ - - Agent: prefix + category + number (CLAUDE_S1, CLAUDE_S2...) - - Agent-specific rules, OWN numbering sequence - - CLAUDE_S1 is Claude's first structure rule, NOT related to core S1 - - Located in agents/{agent}/rules/{id}-{slug}/ - - Package: 3+ letter prefix + category + number (AILS_S1, AILS_C1...) - - Package-provided rules, available to all agents - - Prefix must be in reserved_package_prefixes - - Package-Agent: package prefix + agent + category + number (AILS_CLAUDE_S1...) - - Package-provided agent-specific rules - - Located in package's agents/{agent}/rules/ directory - - Custom: 3+ letter prefix + category + number (ACME_S1, USR_S1) - - Organization or user-specific rules - - Note: Agent prefix must be in reserved_agent_prefixes. - Package prefix must be in reserved_package_prefixes. - Custom prefix must not be in either reserved list. - - To OVERRIDE core patterns (not define new rules), use: - agents/{agent}/overrides/{rule_id}.yml - See agent.schema.yml for override file format. + core: "^CORE:[SCEMG]:[0-9]{4}$" + agent: "^[A-Z]+:[SCEMG]:[0-9]{4}$" + package: "^[A-Z]{3,}:[SCEMG]:[0-9]{4}$" + package_agent: "^[A-Z]{3,}_[A-Z]+:[SCEMG]:[0-9]{4}$" + custom: "^[A-Z]{3,}:[SCEMG]:[0-9]{4}$" + description: "Coordinate: {REGISTRY}:{CATEGORY}:{SLOT}. Immutable, never reused." + + slug: + required: true + type: string + pattern: "^[a-z][a-z0-9-]*$" + description: "Mutable display name, used as directory name" title: required: true type: string max_length: 64 - description: "Human-readable name (max 64 chars)" + description: "Human-readable rule name (max 64 chars)" category: required: true type: enum - values: [structure, content, efficiency, governance, maintenance] + values: [structure, content, efficiency, maintenance, governance] + description: "Rule concern area. Maps to category letter in coordinate: S/C/E/M/G" type: required: true type: enum - values: [deterministic, semantic] + values: [mechanical, deterministic, semantic] + description: "Validation constraint + CLI dispatch signal. Determines which engines load." + + level: + required: true + type: enum + values: [L1, L2, L3, L4, L5, L6] + description: "Concern level. Rule fires when rule.level ≤ project_level." - # NOTE: 'confidence' field removed in schema v4. - # Tier (core/experimental) is derived from backed_by source weights: - # core: max(backing_source_weights) >= 0.8 - # experimental: max(backing_source_weights) < 0.8 (or no backing) - # See sources.schema.yml for tier derivation details. + targets: + required: true + type: string + description: "Template var resolved against agent config. Always files." backed_by: required: false type: array - description: "Source claims that back this rule" + description: "Evidence sources backing this rule. References source IDs from docs/sources.yml." items: - source: - required: true - type: string - description: "Source ID from sources.yml" - claim: - required: true - type: string - description: "Claim ID within that source" + type: string + pattern: "^[a-z][a-z0-9-]*$" + description: "Source ID (matches id field in docs/sources.yml)" checks: required: true type: array - description: "What OpenGrep detects" + min_items: 1 + description: "Ordered. Shape: [mechanical | deterministic]* → semantic?" items: id: required: true type: string - description: "Must match rules[].id in corresponding .yml. Format: {rule_id}-{suffix}" - name: + pattern: "^[A-Z_]+:[SCEMG]:[0-9]{4}:check:[0-9]{4}$" + description: "Check coordinate: {rule_id}:check:{slot}" + type: required: true - type: string - description: "Human-readable description" + type: enum + values: [mechanical, deterministic, semantic] + description: "Gate type for this check step" severity: required: true type: enum values: [critical, high, medium, low] - pattern_confidence: + description: "Impact weight for scoring. Critical=5.5, High=4.0, Medium=2.5, Low=1.0" + # mechanical + check: + required_if: "type == mechanical" + type: string + description: "Mechanical check function name (see values for available checks)" + values: + - file_exists + - directory_exists + - directory_contains + - git_tracked + - frontmatter_key + - file_count + - line_count + - byte_size + - path_resolves + - extract_imports + - aggregate_byte_size + - import_depth + - directory_file_types + - frontmatter_valid_glob + - content_absent + args: required: false - type: enum - values: [very_high, high, medium, low, very_low] - default: medium - description: | - How precisely the OpenGrep pattern captures what it claims to detect. - Consumers: LLM pattern generation (improvement targeting), CLI telemetry. - - very_high: Exact structural match (line count, file exists). Don't touch. - high: Tight regex, tested, rare false positives. Minor refinement only. - medium: Reasonable regex, some edge cases. Review test cases, tighten. - low: Broad match, known false positives. Rewrite with more context. - very_low: Placeholder or minimal pattern. Full rethink needed. - - Derivable from: test case count + observed false positive rate. + type: object + description: "Check-specific arguments (e.g., path, min, max)" + # deterministic + pattern: + required_if: "type == deterministic" + type: string + description: "OpenGrep regex pattern to match violations" + message: + required_if: "type == deterministic" + type: string + description: "Human-readable violation message when pattern matches" + cross_file: + required: false + type: boolean + default: false + description: "Whether pattern operates across the full target set (not per-file)" + # semantic + prompt: + required_if: "type == semantic" + type: string + description: "Evaluation prompt sent to coding agent for LLM judgment" question: + required: false required_if: "type == semantic" type: string - description: "What LLM evaluates after OpenGrep runs" + description: "Evaluation question for semantic rules. Sent to coding agent for LLM judgment. Must be answerable from matched content." criteria: + required: false required_if: "type == semantic" type: array + description: "Evaluation rubric for semantic rules. Each item is independently assessable by the coding agent." items: type: string - description: "How LLM decides (list of conditions)" - sources: + supersedes: required: false - type: array - items: - type: string - format: url - description: "URLs to supporting references (docs, articles, research papers, resources)" + type: string + pattern: "^[A-Z_]+:[SCEMG]:[0-9]{4}$" + description: "Coordinate of replaced rule. Must be lower level. 1:1 only." see_also: required: false type: array + description: "Related rule coordinates for cross-referencing" items: type: string - pattern: "^([A-Z]+_){0,2}[SCEGM][0-9]+$" - description: "Related rule IDs" + pattern: "^[A-Z_]+:[SCEMG]:[0-9]{4}$" -# ============================================================================= -# TEMPLATE VARIABLES -# ============================================================================= + conflicts: + required: false + type: array + description: "Known conflicts with other rules, with resolution status" + items: + conflict_id: + required: true + type: string + description: "Reference to a resolution in docs/resolutions/" + resolution_honored: + required: true + type: boolean + description: "Whether this rule follows the published resolution" + scoped_to: + required: false + type: string + description: "Context scope where this conflict applies (e.g., monorepo, single-root)" template_variables: universal: - description: "Required for ALL agents — core rules may only use these" - variables: - main_instruction_file: - description: "Primary instruction file (document-level rules apply here)" - example: "**/CLAUDE.md" - instruction_files: - description: "All instruction files (main + supplementary)" - example: ["**/CLAUDE.md", ".claude/rules/**/*.md"] - + main_instruction_file: "Primary instruction file" + instruction_files: "All instruction files (main + supplementary)" agent_specific: - description: "Only agents that support them — requires rule in agents/{agent}/rules/" - variables: - supplementary_files: - description: "Rule snippet files (excludes main)" - example: ".claude/rules/**/*.md" - rules_dir: - description: "Rules directory path" - example: ".claude/rules" - skills_dir: - description: "Skills directory path" - example: ".claude/skills" - local_file: - description: "Local/personal instruction file" - example: "CLAUDE.local.md" - managed_settings_linux: - description: "Path to managed settings file on Linux" - example: "/etc/claude-code/managed-settings.json" - managed_settings_macos: - description: "Path to managed settings file on macOS" - example: "/Library/Application Support/ClaudeCode/managed-settings.json" - managed_settings_windows: - description: "Path to managed settings file on Windows" - example: "C:/Program Files/ClaudeCode/managed-settings.json" - -# ============================================================================= -# VALIDATION -# ============================================================================= + supplementary_files: "Rule snippet files (excludes main)" + rules_dir: "Rules directory path" + skills_dir: "Skills directory path" validation: - # Contract between .md and .yml - - rule: "Every checks[].id must match a rules[].id in the .yml file" - - rule: "Every rules[].id in .yml must match a checks[].id in the .md file" - - rule: "checks[].id must start with the rule ID followed by hyphen" - - # Type-specific requirements - - rule: "Semantic rules must have question + criteria" - - rule: "Deterministic rules must not have question + criteria" - - # Source of truth - - rule: "Severity in .md is source of truth (overrides .yml)" - - # Field constraints - - rule: "title must be max 64 characters" - - # ID format - - rule: "Core rule IDs must match pattern ^[SCEGM][0-9]+$" - - rule: "Agent rule IDs must match pattern ^[A-Z]+_[SCEGM][0-9]+$" - - rule: "Package rule IDs must match pattern ^[A-Z]{3,}_[SCEGM][0-9]+$" - - rule: "Package-agent rule IDs must match pattern ^[A-Z]{3,}_[A-Z]+_[SCEGM][0-9]+$" - - rule: "Custom rule IDs must match pattern ^[A-Z]{3,}_[SCEGM][0-9]+$" - - rule: "Agent rule prefix must be in reserved_agent_prefixes" - - rule: "Package rule prefix must be in reserved_package_prefixes" - - rule: "Custom rule prefix must NOT be in reserved_agent_prefixes or reserved_package_prefixes" - - # References - - rule: "see_also must reference valid rule IDs" - - rule: "sources must be valid URLs" - - # Evidence chain - - rule: "backed_by[].source must exist in sources.yml" - - rule: "backed_by[].claim must exist in that source's claims" - - # Tier derivation (replaces confidence validation from v3) - - rule: | - Tier is derived, not stored. Computed from backed_by: - - core: at least one backing source with weight >= 0.8 (official or research) - - experimental: all backing sources have weight < 0.8, or backed_by is empty - - # Template variable restrictions - - rule: "Core rules (in core/) may only use {{main_instruction_file}} or {{instruction_files}}" - - rule: "Agent-specific variables (supplementary_files, rules_dir, skills_dir) require rule in agents/{agent}/rules/" - -# ============================================================================= -# EXAMPLES -# ============================================================================= + - rule: "Every checks[].id in rule.md must match a corresponding entry in rule.yml" + - rule: "checks[].id format: {rule_id}:check:{slot}" + - rule: "mechanical type: checks may only contain mechanical" + - rule: "deterministic type: checks may contain mechanical + deterministic" + - rule: "semantic type: any types allowed, semantic must be last" + - rule: "supersedes target must be at a strictly lower level" + - rule: "No circular supersessions" + - rule: "Each rule may be superseded by at most one other rule" + - rule: "Severity in rule.md is source of truth" + - rule: "Slots are immutable — deleted rules are tombstoned, never reused" + - rule: "Core rules may only use universal template variables" + - rule: "Tier derived from backed_by: core (weight >= 0.8), experimental (< 0.8 or empty)" examples: - core_with_backing: | + core_mechanical: | --- - # Tier: core (derived — backed by official source, weight 1.0) - id: S1 - title: Size Limits - category: structure - type: deterministic + id: CORE:M:0001 + slug: version-controlled + title: Version Controlled + category: maintenance + type: mechanical + level: L1 backed_by: - - source: claude-code-best-practices # official, weight 1.0 - claim: keep-concise + - claude-code-best-practices + targets: "{{instruction_files}}" checks: - - id: S1-root-too-long - name: Root file > 200 lines + - id: CORE:M:0001:check:0001 + type: mechanical + check: file_exists severity: critical - pattern_confidence: very_high # exact line count match - - id: S1-many-sections - name: 6+ sections in large file - severity: high - pattern_confidence: high # heading count, tight match - sources: - - "https://docs.anthropic.com/en/docs/claude-code/best-practices" - see_also: [S2, C1] - --- - - experimental_no_backing: | - --- - # Tier: experimental (derived — no backing sources) - id: M3 - title: Map Staleness Prevention - category: maintenance - type: deterministic - backed_by: [] - checks: - - id: M3-stale-map - name: Navigation map may be stale - severity: medium - see_also: [C4] + - id: CORE:M:0001:check:0002 + type: mechanical + check: git_tracked + severity: critical + see_also: [CLAUDE:M:0001] --- - deterministic: | + core_deterministic: | --- - id: C3 - title: Has Project Description - category: content + id: CORE:S:0001 + slug: size-limits + title: Size Limits + category: structure type: deterministic + level: L2 backed_by: - - source: claude-code-best-practices - claim: include-core-files + - claude-code-best-practices + targets: "{{main_instruction_file}}" checks: - - id: C3-no-description - name: Missing project description section + - id: CORE:S:0001:check:0001 + type: deterministic + pattern: "(?s)(?:[^\\n]*\\n){200,}" + message: "Root file exceeds 200 lines" + severity: critical + - id: CORE:S:0001:check:0002 + type: deterministic + pattern: "(?s)(^## [^\\n]+\\n.*){6,}" + message: "6+ top-level sections in large file" severity: high - sources: - - "https://docs.anthropic.com/en/docs/claude-code/best-practices" - see_also: [C1] + see_also: [CORE:S:0002, CORE:C:0001] --- - semantic: | + core_semantic: | --- - id: M2 + id: CORE:M:0002 + slug: no-conflicting-rules title: No Conflicting Rules category: maintenance type: semantic + level: L3 backed_by: - - source: claude-code-memory - claim: keep-rules-focused + - claude-code-memory + targets: "{{instruction_files}}" checks: - - id: M2-conflicting - name: Potentially conflicting rules detected + - id: CORE:M:0002:check:0001 + type: deterministic + pattern: "(?i)(MUST NOT|NEVER|ALWAYS|MUST)\\s" + message: "Potentially conflicting directive detected" + severity: high + - id: CORE:M:0002:check:0002 + type: semantic + prompt: "Given the matched directives, are there contradictory or conflicting rules?" severity: high - question: "Are there conflicting or contradictory rules?" - criteria: - - No rules give opposite instructions - - No rules override each other without explicit precedence - see_also: [C2] + see_also: [CORE:C:0002] --- agent_specific: | --- - # Agent rules use SEPARATE namespace - # CLAUDE_S1 = Claude's first structure rule (not override of core S1) - id: CLAUDE_S1 + id: CLAUDE:S:0001 + slug: hierarchical-memory title: Hierarchical Memory category: structure - type: deterministic + type: mechanical + level: L4 backed_by: - - source: claude-code-memory - claim: memory-hierarchy - checks: - - id: CLAUDE_S1-no-hierarchy - name: No hierarchical memory structure - severity: medium - sources: - - "https://code.claude.com/docs/en/memory" - see_also: [CLAUDE_S2, S2] - --- - - package: | - --- - # Package rule — provided by reporails/recommended - # AILS_S1 = recommended package's first structure rule - id: AILS_S1 - title: YAML Backbone - category: structure - type: deterministic - backed_by: [] + - claude-code-memory + targets: "{{rules_dir}}/**/*.md" checks: - - id: AILS_S1-no-backbone - name: No YAML backbone file + - id: CLAUDE:S:0001:check:0001 + type: mechanical + check: directory_exists + args: + path: "{{rules_dir}}" severity: medium - see_also: [S2] + see_also: [CLAUDE:S:0002, CORE:S:0002] --- - package_agent: | + with_supersession: | --- - # Package agent rule — provided by reporails/recommended for Claude - # AILS_CLAUDE_S1 = recommended package's first Claude structure rule - id: AILS_CLAUDE_S1 - title: Skill Size Limits - category: structure - type: deterministic - backed_by: [] + id: CORE:C:0002 + slug: single-source-of-truth + title: Single Source of Truth + category: content + type: semantic + level: L3 + supersedes: CORE:C:0001 + backed_by: + - claude-code-best-practices + targets: "{{instruction_files}}" checks: - - id: AILS_CLAUDE_S1-too-large - name: Skill file exceeds size limit - severity: medium - see_also: [S1, CLAUDE_S1] - --- - - custom: | + - id: CORE:C:0002:check:0001 + type: deterministic + pattern: "^## .+$" + cross_file: true + message: "Duplicate heading across files" + severity: high + - id: CORE:C:0002:check:0002 + type: semantic + prompt: "Are these duplicate headings actual content duplication or scoped context?" + severity: high --- - id: ACME_S1 - title: Internal Doc Size Limits - category: structure - type: deterministic - backed_by: [] - checks: - - id: ACME_S1-too-long - name: Internal docs > 150 lines - severity: medium - sources: - - "https://wiki.acme.corp/engineering/claude-guidelines" - see_also: [S1] - --- \ No newline at end of file diff --git a/schemas/sources.schema.yml b/schemas/sources.schema.yml new file mode 100644 index 0000000..8d668c1 --- /dev/null +++ b/schemas/sources.schema.yml @@ -0,0 +1,51 @@ +# Public source registry schema +# Format: flat YAML list of source entries +# Location: docs/sources.yml (in each package repo) +version: "1.0.0" + +format: list + +fields: + id: + required: true + type: string + pattern: "^[a-z][a-z0-9-]*$" + description: "Source slug — unique identifier" + + url: + required: true + type: string + format: url + description: "Canonical URL to the source" + + type: + required: true + type: enum + values: [official, research, community] + description: | + Source origin type. Determines base weight range: + official: 1.0 + research: 0.8 + community: 0.4-0.6 + + weight: + required: true + type: number + min: 0.4 + max: 1.0 + description: "Authority weight for tier derivation" + + title: + required: false + type: string + description: "Human-readable source name" + +tier_derivation: + description: "Computed by CLI, not stored in sources.yml" + core: "max(backing_source_weights) >= 0.8" + experimental: "max(backing_source_weights) < 0.8 or no backing" + +validation: + - rule: "Every backed_by reference in rule.md must match an id in sources.yml" + - rule: "Flat list format — no scoped dicts, no nested claims" + - rule: "Weights are authoritative" diff --git a/schemas/user.schema.yml b/schemas/user.schema.yml index 084c3f2..0e86c70 100644 --- a/schemas/user.schema.yml +++ b/schemas/user.schema.yml @@ -1,12 +1,13 @@ -# Schema for ~/.reporails/config.yml -# User/global configuration — not committed, personal preferences -version: "0.0.1" +# User configuration schema (~/.reporails/config.yml) +version: "0.1.0" fields: schema_version: required: true - type: integer - default: 1 + type: string + pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$" + default: "0.1.0" + description: "User config schema version (semver)" defaults: required: false @@ -44,6 +45,7 @@ fields: analytics: required: false type: object + description: "Anonymous usage analytics" properties: enabled: type: boolean @@ -51,7 +53,7 @@ fields: description: "Track scan history in ~/.reporails/analytics/" defaults: - schema_version: 1 + schema_version: "0.1.0" defaults: agent: "claude" display: @@ -62,33 +64,22 @@ defaults: enabled: true validation: - - rule: "schema_version must be supported (currently: 1)" - - rule: "Unknown fields should warn, not error (forward compatibility)" + - rule: "schema_version must be supported (currently: 0.1.0)" + - rule: "Unknown fields should warn, not error" - rule: "Invalid patterns should error with clear message" examples: default: | - # Typical user config - schema_version: 1 - + schema_version: "0.1.0" display: color: true developer: | - # Framework developer - schema_version: 1 - - display: - ascii: false - color: true - - # Point to local framework for testing + schema_version: "0.1.0" framework_path: /home/dev/reporails/framework - minimal_output: | - # CI-friendly or accessibility - schema_version: 1 - + ci: | + schema_version: "0.1.0" display: ascii: true color: false