AI Contributor Guide

Use this guide when an AI coding or research agent is about to inspect or change RIGOR. It provides the shortest useful orientation path and points to the documents that own detailed rules. It does not duplicate module instructions or serve as an implementation-status report.

Start Here

Read these sources in order:

1. AGENTS.md for repository-wide constraints and product rules.
2. Main Product Design for accepted behavior and authority boundaries.
3. Repository Working Guide for source-of-truth and cross-module synchronization rules.
4. Current Progress for implemented, qualified, and open work.
5. The nearest module AGENTS.md, then the relevant schema, code, and tests.

Read Laboratory Architecture when a change crosses the device, workflow, robotics, or evidence boundaries. Read Planning and Execution Architecture when it changes planning, packages, loop execution, workflows, or capabilities.

Know Which Source Owns the Answer

Question	Authoritative source
What constraints apply to this edit?	Root and nearest module AGENTS.md
What should the product do?	Accepted PRD
What fields or enum values are valid?	Schema, typed contract, or OpenAPI
What does the repository do now?	Code and tests
What is implemented or still open?	Current Progress
Is the running stack healthy now?	Health endpoints and local logs

Runtime health, logs, generated files, and local databases are observations, not architecture facts. Do not copy them into current documentation unless the task is creating a dated, sanitized evidence record.

Preserve the Product Model

RIGOR has six domain modules with separate authority:

Module	Responsibility
ASCEND	Goals, policy, coordination, Attention, and scientific decisions
Composer	Bounded planning and deterministic immutable package construction
PACE	Loop execution, result completeness, archives, and evidence delivery
LabFlow	Procedure validation, scheduling, waits, locks, and cancellation
LabBridge	Semantic capabilities, Operations, devices, artifacts, and Human Tasks
PRISM	Isolated evidence analysis and committed structured results

The normal deployment groups them into Control, Execution, LabBridge, and Analysis Worker units. Co-deployment does not merge their APIs, databases, or safety authority.

Keep these rules intact:

• Researchers provide goals, constraints, and autonomy policy; routine Compose, Prepare, Start, Refresh, polling, and analysis dispatch are internal actions.
• Human intervention is a typed Needs you/Attention item, required physical task, or important policy decision—not a lifecycle button sequence.
• Agents select semantic capabilities, never GPIO pins, MQTT topics, serial commands, robot poses, or vendor SDK calls.
• Models propose intent and plans. Deterministic code owns policy, validation, locking, idempotency, timeout, cancellation, safe-stop, and evidence commitment.
• Low-risk atomic work may execute directly through Policy → Execution → LabBridge. Reusable or multi-step work uses a Procedure and immutable RunSpec/package.
• Frontends render backend-provided phases, blocking reasons, and available_actions; they do not recreate the lifecycle state machine.

Choose the Smallest Reading Path

For a focused task, add only the sources that can change the answer:

• Product flow or UI lifecycle: main PRD, ASCEND contracts, ASCEND code and browser tests.
• Planning or Agent tools: Agent runtime/profile contracts, Composer schemas, package builder, and planning tests.
• Execution or evidence: RunSpec contracts, PACE/LabFlow schemas, stores, workers, and recovery tests.
• Device integration: LabBridge capability and controller contracts, the device definition, and integration tests.
• Analysis: PRISM task/result contracts, Skill definition, sandbox policy, and evidence fixtures.
• Deployment: deployments/topology.json, root and deployment wrappers, health contracts, and recovery tests.

Use rg to locate the current implementation instead of relying on a long, static list of filenames. The nearest module AGENTS.md supplies any required module-specific reading order.

Before and After Editing

Before editing:

1. Identify the authority owner and affected contracts.
2. Search for producers, consumers, tests, and documentation references.
3. Check the synchronization matrix in the Repository Working Guide.
4. Preserve compatibility boundaries unless their callers are migrated in the same change.

After editing:

1. Run focused tests, then the relevant contract, architecture, build, or browser gates.
2. Update current documentation only when accepted behavior, interfaces, deployment boundaries, or verified progress changed.
3. Keep secrets, logs, databases, caches, generated runtime state, and firmware binaries out of commits.
4. Report what was verified and distinguish software evidence from production or physical qualification.

For repository guidance and maintained-file structure, also run:

python3 scripts/check-agent-guidance.py
python3 scripts/check-maintainability-size.py

The first command checks scoped AGENTS.md coverage and synchronized runtime copies. The second rejects new oversized active documents or source files and prevents recorded legacy hotspots from growing. A legacy budget is a reduction queue, not permission to add more responsibilities to that file.