CLAUDE.md — OpenRiC Development Rules

This file governs all AI-assisted development on OpenRiC. READ THIS FILE IN FULL BEFORE WRITING ANY CODE. NO EXCEPTIONS.

FIRST INSTRUCTION — EVERY PHASE, EVERY TASK

Before writing a single line of code:

1. READ THIS FILE (CLAUDE.md) — in full, every time
2. READ MEMORY — all memory files in the memory directory
3. READ THE PLAN — the current phase plan with detailed instructions
4. READ THE HERATIO SOURCE — the actual file you are adapting, in full
5. REPORT what you read and what you will build — get confirmation before coding

The Heratio Rule — NON-NEGOTIABLE

OpenRiC is Heratio rebuilt with RiC-O as the storage layer. This means:

What "Copy from Heratio" means:

• Read the ENTIRE Heratio source file — every line, every field, every method
• Translate ALL of it to OpenRiC — not part of it, not a summary, not "the important bits"
• If Heratio has 60 fields, OpenRiC has 60 fields
• If Heratio has 30 methods, OpenRiC has 30 methods
• If Heratio has repeatable rows, autocomplete, access points — OpenRiC has them too
• The user sees the same screens, same fields, same buttons — only the data layer changes

What changes from Heratio:

• Namespace: OpenRiC\ not AhgX\
• Database: PostgreSQL not MySQL for operational data
• Archival data: Fuseki triplestore via TriplestoreService not MySQL tables
• Table names: users not user, no ahg_ prefix
• IRI-based: object_iri (string) not object_id (integer) for entity references

What does NOT change from Heratio:

• Every form field — if Heratio has it, OpenRiC has it
• Every button and control — same actions, same UI
• Every service method — same logic, same edge cases
• Every view feature — pagination, sorting, filtering, facets
• Line count should be proportional — an 867-line Heratio service produces a proportional OpenRiC service, not a 138-line stub

The process for EVERY file:

1. Find the Heratio source file
2. Read it IN FULL — cat the entire file, not just head
3. List every method/field/control found
4. Write the OpenRiC adaptation with ALL of them
5. Compare line counts — if OpenRiC is less than 60% of Heratio, something is missing
6. Report what was adapted and what (if anything) was intentionally excluded, with justification

Authorisation

• Only Johan Pieterse may commit to GitHub
• Claude Code must never run git push, git commit, or any GitHub CLI command
• Claude Code may stage files with git add but must stop there
• Always present proposed changes for review before staging

Non-Negotiable Architecture Rules

1. All code must be PHP CS Fixer compliant
2. Laravel 12 throughout — no Symfony, no Propel, no AtoM dependencies
3. Namespace: OpenRiC\ — never mix with Heratio or AtoM namespaces
4. Database: PostgreSQL only for operational data — auth, sessions, jobs, audit log
5. Triplestore: Always use TriplestoreService interface — never call Fuseki directly from controllers
6. No stubs — every method must be fully implemented. Never use placeholder comments like // TODO: implement or return empty collections
7. No hardcoded data — controllers must query real data sources, never return static arrays or dummy content
8. ADD COLUMN IF NOT EXISTS does not work on this PostgreSQL instance — always check column existence first
9. No partial implementations — if a feature is started, it must be completed to 100% parity with Heratio
10. No deferring — never say "we'll do this later" or "placeholder until full UI"

Phase Execution Rules

Every phase MUST follow this process:

Before starting a phase:

1. Read CLAUDE.md (this file)
2. Read all memory files
3. Read the phase plan with detailed per-file instructions
4. Read the ROADMAP.md to confirm what's in scope
5. List every Heratio source file that will be adapted
6. For each file, state: Heratio path, line count, OpenRiC target path

During a phase:

1. Read each Heratio source file IN FULL before writing the OpenRiC equivalent
2. Write the OpenRiC file with ALL fields/methods/controls from Heratio
3. After each file, report: source lines, target lines, field count comparison

After completing a phase:

1. Run a FULL AUDIT comparing every OpenRiC form/view/service against its Heratio equivalent
2. Report: field-by-field comparison, missing fields, missing buttons, missing controls
3. The audit must show 100% parity before the phase is marked complete
4. Update ROADMAP.md with completion status
5. Update version.json
6. Provide push commands with version tag
7. Update ric.theahg.co.za docs

Audit requirements:

• Every form: count inputs, selects, textareas, checkboxes, buttons, links
• Every browse view: pagination, sorting, filtering, facets, table columns
• Every service: method count, line count vs Heratio source
• Report must be written to /usr/share/nginx/OpenRiC/storage/logs/audit-phase-{N}.md
• If parity is below 100%, the phase is NOT complete — fix the gaps first

No Modifications Without Authorisation

• Never modify working screens, layouts, or functionality without explicit instruction
• Never modify routing on any package marked stable
• Never modify CSS/theme files — all styling goes through the central theme
• Never modify database/migrations/ without showing proposed changes first and receiving approval
• Never modify config/ files without explicit authorisation
• Present ALL proposed changes before implementing them

Theme & Frontend Rules

• Bootstrap 5 throughout — no other CSS frameworks
• Central CSS/theme — all custom styles in the designated theme file only, never inline, never in component-level CSS files
• WCAG 2.1 Level AA compliance on all UI — every new screen must meet accessibility standards
• No inline styles — use Bootstrap utility classes or the central theme
• Screen layouts must be consistent across all views — follow established OpenRiC UI patterns

RiC-O Rules

• RiC-O 1.1 is the canonical layer — all archival data writes to the triplestore via TriplestoreService
• Every triple write must include RDF-Star provenance annotation — who, when, on what basis
• ISAD(G) and ISAAR-CPF are lenses — they are rendered from SPARQL, never stored as the primary model
• Standards mappings live in config — never hardcode field mappings in controllers or services
• RiC-O property names must match the ontology exactly — verify against RiC-O 1.1 at https://www.ica.org/standards/RiC/RiC-O_1-1.html before using any property
• When in doubt on RiC-O modelling — consult RiC-CM 1.0 and the RiC Application Guidelines before implementing

Code Architecture Rules

• Controllers must be thin — no business logic in controllers, only service calls
• Service layer is mandatory — every controller method calls a service class
• Repository pattern — data access goes through repositories, not raw queries in services
• TriplestoreService — all SPARQL reads and writes go through this abstracted interface
• No raw SQL — use Eloquent or Laravel Query Builder for PostgreSQL; use TriplestoreService for Fuseki
• Transactions — any operation writing to both PostgreSQL and the triplestore must handle failure of either gracefully
• Every new class must have a corresponding interface

File Creation Convention

cat > filename << 'EOF'
content
EOF

Always use bash heredoc syntax for file creation. Never use echo for multi-line files.

Anti-Stub Rules

Claude Code must never: - Return [] or null from a method that should query data - Write // TODO or // implement later comments - Create controller methods that render views without passing real data - Create service methods that return hardcoded responses - Skip validation in store/update methods - Create migrations without the corresponding model, service, and controller - Write a form with fewer fields than the Heratio equivalent - Write a service with fewer methods than the Heratio equivalent - Summarise or abbreviate Heratio code instead of translating it fully

Every piece of code delivered must be production-ready, functional, and at 100% parity with Heratio.

Version Control

• Every push must include version.json update and git tag
• Use semantic versioning: major.minor.patch
• Include version in commit message

Stable Packages — Do Not Modify Routing or Core Logic

Once marked stable, these packages are locked: - openric-auth — authentication and ACL - openric-audit — audit trail and RDF-Star annotations - openric-workflow — workflow engine - openric-theme — Bootstrap 5 theme

SPARQL Rules

• All SPARQL queries must be parameterised — never string-interpolate user input into queries
• Queries must include LIMIT clauses — no unbounded queries against the triplestore
• PREFIX declarations must use the canonical OpenRiC prefix file — never declare ad-hoc prefixes inline
• Every SPARQL write (INSERT/DELETE) must be followed by an RDF-Star provenance annotation

Testing

• Every new service method must have a corresponding unit test
• Every new controller action must have a feature test
• No pull request without tests — even Claude Code output must include tests

What to Read Before Starting Any Task

1. This file (CLAUDE.md) — IN FULL
2. All memory files — IN FULL
3. VISION.md — architectural decisions and why
4. ROADMAP.md — current phase and priorities
5. The Heratio source file being adapted — IN FULL
6. The relevant RiC-O 1.1 property/class documentation for the entity being worked on
7. The existing service class for the package being modified — follow established patterns

When in Doubt

• Do not guess — ask
• Do not implement a workaround — raise it as a question first
• Do not modify existing working code to make new code fit — adapt the new code to the existing patterns
• Do not write a shorter version of what Heratio has — translate ALL of it
• RiC-O modelling questions: consult RiC-CM 1.0, RiC-AG, and the Records_in_Contexts_users Google Group precedents