RIGOR Agent Work Information Management

Status: Active working convention Updated: 2026-08-27 Owner: Repository maintainers

Use this guide before changing RIGOR across module boundaries. It tells human and AI contributors which document, contract, code path, or runtime source answers a question, what reading order to follow, and which related information must be updated together.

1. Purpose

RIGOR contains current implementation documents, target PRDs, API contracts, module instructions, diagrams, runtime data, and generated assets. Agents must know which source answers which question. This document prevents an outdated README, diagram, local database, or aspirational PRD from being treated as the wrong kind of truth.

2. Information Hierarchy

Use sources by purpose, not one universal precedence order:

Question	Authoritative source
What rules apply to this edit?	Root and nearest module AGENTS.md
What product behavior are we building toward?	Accepted PRD, especially agent-first-system-design-prd.md
What interface is valid?	JSON Schema, Pydantic schema, OpenAPI, MCP/controller/runtime contract docs
What is implemented now?	Source code and tests
What is running locally now?	Health/API queries and local logs; never committed as architecture truth
What has been completed or remains?	docs/project-progress.md
How do components relate visually?	Maintained diagrams, checked against code
How is a module operated?	Module README and deployment docs

When sources disagree:

• do not silently choose the most convenient source;
• identify whether the disagreement is target-versus-current or genuine drift;
• preserve current compatibility unless the task authorizes migration;
• update the stale source in the same change when it is in scope;
• record unresolved cross-module design conflicts in the relevant PRD rather than creating an untracked personal note.

3. Required Reading Order

For any cross-module product or architecture task:

AGENTS.md
docs/agent-first-system-design-prd.md
docs/agent-work-information.md
docs/project-progress.md
nearest module AGENTS.md files
relevant contract/schema
relevant implementation and tests

For a narrow module task, read the root AGENTS.md, nearest module AGENTS.md, and directly relevant contract/code. Do not load every repository document when it cannot affect the task.

Runtime Agent role sources such as each module's agent/AGENTS.md and SOUL.md govern the sandboxed Agent's authority, working stance, and expression. They are not substitutes for module developer instructions.

4. Document Roles

4.1 Root AGENTS.md

Contains repository-wide product philosophy, safety boundaries, working rules, secrets handling, and cross-module information synchronization. It should remain compact enough to read before any task.

4.2 Module AGENTS.md

Contains module authority, code map, invariants, target migration direction, validation commands, and module-specific sync requirements. It must not repeat the entire root PRD.

4.3 PRDs

PRDs define accepted target behavior and acceptance criteria. Every PRD starts with status, updated date, owner, and scope. Use one of these statuses:

Draft
Accepted target design
In implementation
Implemented
Superseded by <document>
Historical implemented — superseded by <document>
Historical investigation

An accepted target PRD is not evidence that code is already implemented. Historical statuses are used only under docs/archive/; archived documents preserve decisions and acceptance denominators but do not describe current implementation or priorities.

4.4 Contracts

Machine-readable schema or typed source is preferred over prose for field names, enums, validation, and compatibility. Contract documentation explains semantics, ownership, and lifecycle behavior that a schema cannot express.

Current Agent-first contract locations:

Contract/behavior	Current source
CapabilitySpec, PolicyDecision, AvailableAction, AgentDecision, AgentTrace, direct-action request	ascend/backend/src/ascend/agent_control/contracts.py
Five user phases and server-provided actions	ascend/backend/src/ascend/agent_control/projection.py
direct-action policy/execution, AgentRun and correlated trace	ascend/backend/src/ascend/agent_control/
durable ASCEND Intake Review/Revision state, shared Runner profile, context snapshots, Specialist envelope, and worker retry	ascend/backend/src/ascend/intake.py, intake_runner.py, intake_reviews.py, intake_worker.py, and migrations v4/v8
ASCEND current recovery Plan/PlanRevision, ordered-intent policy, and execution linkage	ascend/backend/src/ascend/plans.py, Agent Control contracts, and migrations v5-v6
mandatory experimental Rehearsal gate and exact capability lineage	contracts/rehearsal-attestation-v1.schema.json, ASCEND rehearsal_gate.py and migration v18, PACE loop_service.py, LabFlow signed workflow context, and LabBridge virtual_lab/service.py plus capability_calls/service.py
ASCEND internal-stage deadlines/recovery, duration-unbounded EXECUTING status polling, and stalled/status-unreachable/disabled-automation Attention	ascend/backend/src/ascend/liveness.py, routine advancement in agent_control/service.py, PACE loop status mapping in iterations.py, local decision dispatch in inbox.py, and migrations v15-v17
Versioned Research Goal presets, curated rehearsal-only plans, and factorial study guardrails	ascend/backend/src/ascend/coordination_presets.py, study_design.py, ascend/presets/*.yaml, ASCEND virtual_lab.py, and LabBridge virtual_lab/
governed Stop Experiments and Reset Devices operation	ascend/backend/src/ascend/device_resets.py, migration v7, and LabBridge device_resets/service.py
Experiment-owned history manifest, logical data locations, governed owner purge, legacy-orphan reconciliation, and factory reset	Accepted PRD §9.1, ascend/web/admin/src/features/experiments/ExperimentsPage.tsx, ascend/backend/src/ascend/records.py, records_router.py, and each owner's record-projection/v1 / bulk-delete contract; normal users manage the Experiment root, not module records
domain deployment unit/service membership, start order, scripts, health and console endpoints	deployments/topology.json; deployment wrappers and Supervisor consume this contract; root run.sh additionally owns required Supervisor/Docs infrastructure order
process supervision, four-unit/service status/control, configured public Docs/Controller navigation, configured console workspace, and embedded module chrome	supervisor/src/sdlx_supervisor/, supervisor/web/, centralized infrastructure.supervisor.public_url and infrastructure.docs.public_url, ASCEND platform_contracts.py, platform_runtime.py, platform_router.py, ascend/web/admin/src/app/Shell.tsx, ConsoleMenu.tsx, and ConsoleWindow.tsx; module header behavior remains in each */web/admin source and is covered by ASCEND browser and engineering-console tests
device reset support and human-assisted fallback	GET /api/agent/device-resets, POST /api/device-resets, LabBridge reset idempotency record, and reset_to_safe_state device manifests
LabBridge capability catalog projection, semantic ID, and simulated/physical provenance	labbridge/src/labbridge/core/contracts.py and mcp/views.py
controller availability, independent state freshness, and atomic complete-fleet SimFleet heartbeat	labbridge/docs/controller-protocol.md, labbridge/src/labbridge/live_availability.py, and simfleet/heartbeat.py; repeated leases are disposable runtime state and do not rewrite durable device state or audit history
versioned spatial facts, mutable workspace LayoutDraft authoring, multi-mobile role-aware device Access Points, DeviceModel/controller-owned service targets, revision-only mobile validation starts, semantic equipment navigation, pre-branch private target materialization, layout qualification/publish/activation gate, shared 2D/3D renderer, immutable recorded paths and execution/replay scenes	contracts/spatial-map-v1.schema.json, navigation-path-v1.schema.json, rehearsal-plan-resolution-v1.schema.json, execution-snapshot-v1.schema.json, packages/ui-lab-map/, LabBridge layout_drafts.py, _registry/layout_drafts.py, virtual_lab/intent_resolution.py, virtual_lab/access_routing.py, core/access_points.py, core/layout_qualification.py, core/navigation.py, map_revisions.py, ASCEND virtual_lab.py, LabSituationProjection and scene/replay projections; only Access Points are user-authored map targets, each fixed device may define separate delivery/operation/pickup positions for compatible mobile units, station-like IDs/routes are private projections, a draft is never runtime truth, validation starts never become live placements, no branch exists before compatibility passes, and the renderer never owns spatial truth or arrival
truth-labeled Docs home laboratory view	ASCEND scene_contracts.py and showcase_projection.py own sdlx.lab-showcase/v1; Docs server.mjs only caches/proxies it and packages/ui-lab-map renders it
semantic HTTP capability execution	POST /api/capability-calls in LabBridge Admin Server
primary user Take over and trace views	ascend/web/admin/src/main.tsx
primary Home execution-journey projection	ExperimentJourney in ascend/backend/src/ascend/workspace_contracts.py and experiment_journey() in workspace_projection.py
ASCEND Self-aware source context, filter policy, snapshot and read-only sandbox mount	ascend/backend/src/ascend/source_view.py, session_sandbox.py, runtime_profile.py, ChatTurnRequest, and migration v9
ASCEND Creator conversation mode, source intake, owner/readiness planning, and owner-validated extension installation	docs/creator-mode-prd.md; contracts/creator-extension-plan-v1.schema.json; ASCEND creator_sources.py, creator_extension_plan.py, creator_tools.py, scientist_capabilities.py, nanobot_config.py, runtime_profile.py, ChatTurnRequest, and migration v24; Agent Runtime external managed-Skill root policy and MCP hot reload; Composer Skill and Workflow owner APIs; PRISM skill_library.py and /api/skills/install
immutable unverified Scientist process proposal handoff into Composer local compilation	contracts/scientific-process-proposal-v1.schema.json; ASCEND scientific_process_proposals.py, iterations.py, migration v25, and Scientist Tool profile; Composer scientific-process-proposal Skill, agent_support.py, composition plan, and package provenance
recorded-results Agent replay	ascend/backend/src/ascend/agent_control/contracts.py and service replay reducer
shared runtime/profile contract	packages/agent-runtime/src/nanobot/runtime_profile.py and module runtime_profile.py entry points
shared context/task budget governance, typed checkpoints, and sustained-Goal continuation	Agent Runtime agent/context_governance.py, agent/runner.py, session/turn_continuation.py, and api/server.py; ASCEND persists the product projection in chat_turns.py and migration v20
ASCEND durable conversation progress, live activity, reply streaming, reconnect, worker recovery/health, and reply-only cancellation	docs/conversation-live-feedback-design.md; Agent Runtime OpenAI-compatible SSE plus sdlx_runtime; ASCEND chat_turns.py, chat_worker.py, migration v21, chat router, workspace_contracts.py, /api/health, /api/stream, and features/conversation/; generated ASCEND OpenAPI remains the browser contract
Intake/Composer/PRISM Specialist task envelope	contracts/specialist-task-envelope-v1.schema.json and packages/agent-runtime/src/nanobot/specialist_task.py
portable production AgentRun record	contracts/agent-run-v1.schema.json
Composer bounded model outputs	contracts/composer-draft-v1.schema.json and contracts/composer-brief-review-v1.schema.json
CoN4Cl real-data benchmark mapping and qualification	docs/con4cl-control-matrix-benchmark.md and qualification/fixtures/con4cl-xps/v1/manifest.json
ASCEND Intake bounded output	contracts/research-brief-review-v2.schema.json and ascend/backend/src/ascend/intake.py; v1 remains a retained compatibility contract
committed-report translation and download	ascend/backend/src/ascend/report_translations.py, report_translation_runner.py, report_translation_worker.py, and workspace_router.py; PRISM remains authority for the original report, result, and archive
PRISM reviewable analysis decision graph and scientist review	PRISM contracts.py, decision_graph.py, stable skill:<skill-id>/<relative-path> Tool identity, committed decision_graph, and read-only /api/analysis-runs/{id}/decision-graph; ASCEND analysis_reviews.py, Evidence indicators/conclusion summary, grouped gaps, conclusion-first Story, scientific Graph, grouped Timeline, and immutable review annotations own the normal researcher review
durable background jobs	packages/job-runtime/src/sdlx_jobs/store.py
versioned SQLite migration mechanics	packages/schema-runtime/src/sdlx_schema/sqlite.py; domain DDL remains with ASCEND, PACE, and LabBridge
immutable PACE RunSpec loading, validation, bundle normalization, and hash	packages/run-spec/src/sdlx_runspec/; pace.package_loader is a compatibility import only, and Composer/PACE depend on sdlx-run-spec
shared Agent image rationale and Podman sandbox runtime mechanics	docs/agent-sandbox-image.md and packages/sandbox-runtime/src/sdlx_sandbox/; ASCEND, Composer, and PRISM retain domain-specific mount/policy/audit ownership
frontend OpenAPI types/client	packages/ui-contracts/openapi/ascend.openapi.json and generated src/ascend.gen.d.ts
deployable unit metadata	deployments/*/deployment.json
centralized runtime configuration, secret references, generated service projections, revisions, and rollback	config/sdlx.yaml, config/secrets.yaml, packages/config-runtime/, and Supervisor /api/config*; local values and projections remain ignored
immutable PACE/PRISM object writes and verified reads	packages/object-store/src/sdlx_object_store/store.py
portable SQLite and versioned object-store backup inventory	contracts/runtime-backup-v1.schema.json and scripts/runtime-backup.py
PostgreSQL native dump/restore qualification evidence	contracts/postgres-restore-evidence-v1.schema.json and scripts/test-postgres-backup-restore.sh
live Scientist/Planner/Analyst qualification evidence	contracts/agent-profile-qualification-v1.schema.json and scripts/qualify-agent-profiles.py
bounded software/SimFleet soak evidence	contracts/software-soak-evidence-v1.schema.json and scripts/run-software-soak.py

The obsolete manual Compose/Sync/Prepare/Start/Refresh lifecycle endpoints have been removed after caller migration. Domain APIs and module run scripts remain intentional engineering boundaries. A successful MQTT publish means transport dispatch only; inspect the linked Operation result and verification_status before making a physical or scientific claim.

4.5 Project progress

docs/project-progress.md records implementation status and qualification. It must link to the governing PRD and distinguish software completion, physical qualification, and production deployment.

4.6 Diagrams

Diagrams are explanatory views. Update them when deployable boundaries, primary data flow, or authority changes. Label target diagrams and current implementation diagrams explicitly.

4.7 Runtime and generated information

Local configuration, databases, logs, pid files, model transcripts, generated archives, caches, and firmware binaries are not repository truth and must not be committed unless a task explicitly creates a sanitized fixture.

4.8 Archive, release, decision, and prompt records

• Write maintained documentation for a human reader with a concrete task. Give the page a descriptive title, explain its purpose near the top, define module names and acronyms before relying on them, and distinguish requirements, current behavior, dated evidence, history, and visual intent.
• Organize navigation by reader intent rather than repository folder names or internal implementation phases. Avoid linking the same page under multiple labels unless the duplicate is essential to a guided reading path.
• Current Web documentation uses English. Put a maintained translation in a separate, clearly named language edition; do not alternate narrative languages inside one active requirements, architecture, or operations page. Historical records may retain their original language in the repository when the index labels them first, but non-English source material is excluded from the public Web build until a maintained language edition exists.
• Keep active governing, architecture, operations, qualification, and current status documents at stable paths under docs/.
• Move completed PRDs and time-bound investigations to docs/archive/ only after migrating still-current requirements and updating inbound links.
• Keep ADRs under docs/decisions/ and dated evidence/change records under docs/releases/; completion does not make either category disposable.
• Keep illustration briefs under docs/prompts/ and state plainly that they are visual concepts rather than requirements or evidence.
• Do not create an undated next-step, notes, or current-investigation document when project-progress.md, a PRD phase, an ADR, or a dated release record can own the information.
• Keep README.md and docs/index.md as navigation layers, not duplicate status reports. Exact suite counts and volatile topology facts belong in current progress, machine-readable topology, or dated evidence.
• Keep active pages focused on decisions or tasks a reader can act on. Move superseded implementation narratives, exact historical test counts, and time-bound local observations to an archive or dated release record.
• docs-site/scripts/check-content.mjs reads every page included in the public build as well as the real top and sidebar navigation during every documentation build. It rejects missing or excluded navigation targets, incomplete page metadata, duplicate sidebar destinations, mixed narrative languages, invalid H1 counts, skipped heading levels, and missing page introductions.
• scripts/check-agent-guidance.py verifies required scoped AGENTS.md files, their reading size, synchronized runtime copies, and known stale statements.
• scripts/check-maintainability-size.py rejects new oversized active documents or maintained source files. Existing hotspots are recorded at their current size and may shrink but cannot grow; generated contracts, archives, release records, build output, dependencies, and runtime sandboxes are not hand-edited maintainability units and are excluded.

5. Task Context Packet

For a complex change, an Agent should be able to state this compact context before editing:

Objective:
Current behavior:
Target behavior:
Authority owner:
Contracts affected:
Files likely affected:
Safety/provenance constraints:
Validation plan:
Explicit non-goals:

This packet belongs in the task plan, issue, or PRD implementation section. Do not create a new persistent status file for every task.

6. Change Synchronization Matrix

Change	Also inspect/update
Product flow or human decision behavior	Agent-first PRD, ASCEND UI, runtime Agent instructions, scenario tests
Agent tool input/output	Pydantic/tool schema, profile allowlist, trace projection, tests, relevant prompt
Agent context projection	context policy, allowlist tests, trace redaction, PRD authority table
Agent profile/prompt/SOUL/Skill behavior	version metadata, managed AGENTS.md/SOUL.md source and workspace sync, artifact hashes, golden tests, trace display
Capability metadata	LabBridge contract/docs, controller or manifest, Agent view, LabFlow/direct execution validation
MCP tool	MCP contract docs, callers, compact projection, tests
Workflow/Procedure schema	LabFlow schema/runtime contract, Composer selection, PACE package validation, editor types
PACE result/evidence contract	PACE schema, PRISM input, ASCEND decision projection, demos/tests
Attention event/decision	shared JSON Schema including any producer-declared input form, producer result handler, ASCEND rendering/validation, idempotency/restart and browser submission tests
User-facing lifecycle action	backend available_actions, policy tests, UI; do not add a frontend-only transition map
Public API	OpenAPI/client types, caller tests, README only when operational use changes
Spatial map, device placement, Access Point, or Lab situation	LabBridge revision/preflight contracts, ASCEND typed projection, shared renderer consumers, PRD §9, immutable snapshot/replay behavior, desktop/mobile browser tests
Deployable boundary	target/current diagrams, root README, deployment docs, run scripts
SQLite schema evolution	owning module migration plan, packages/schema-runtime runner tests, forward/rollback and immutable-lineage tests
Frontend stack/build path	root run script, module README/AGENTS, CI build, generated asset policy
Device/node	firmware YAML, manifest capability, GPIO/topic table, LabBridge visibility, validation procedure

7. Change-aware Validation

Routine validation is selected from the actual Git diff by scripts/test_changes.py. The selector is deterministic and prints the paths that caused every command to be selected. This lets an Agent choose additional tests based on its semantic understanding without giving it authority to omit the repository's minimum mapped checks.

# Inspect or execute the fast plan for local staged, unstaged, and untracked work.
python3 scripts/test_changes.py
python3 scripts/test_changes.py --run

# Run complete suites/builds only for modules touched by the same diff.
python3 scripts/test_changes.py --tier deep --run

# Plan committed changes, for example in CI or after a commit.
python3 scripts/test_changes.py --base origin/main

Quick validation includes diff hygiene, maintained-file limits, language static checks, mapped domain tests, and focused browser journeys. Deep validation adds the full suite/build/browser surface of impacted modules; it does not run an unchanged module merely because that module exists in the repository. A new or unmapped production source fails closed until its owning test impact is declared.

Live process recovery, PostgreSQL and MinIO integration, identity-boundary checks, deterministic Agent fault injection, soak, production qualification, and physical qualification are separate explicit gates. They are not normal pre-commit checks and are never hidden inside quick or deep validation. Agents must report which tier they ran and any additional manually selected tests.

8. Agent Runtime Information

The generic runtime source of truth is packages/agent-runtime. Scientist, Planner, and Analyst behavior is selected through module entry-point profiles; the module-local backend/src/nanobot paths are compatibility symlinks to that single source, not forks. Deterministic replay is owned by ASCEND Agent Control and consumes recorded trace events only.

Every persisted AgentRun should identify the exact information that influenced it:

agent_profile_id and version
prompt version
Skill ids and versions
tool schema versions
context policy version
context snapshot hash/reference
model and generation parameters
policy snapshot
parent coordination/iteration/run ids

Do not use mutable workspace files as the only record of Agent behavior. Do not store credentials or hidden chain-of-thought. Store structured decision summaries, tool calls, policy outcomes, evidence references, and bounded model outputs. Treat current model context and cumulative execution-segment spend as separate ledgers. Product code consumes the additive sdlx_runtime response extension; it must not parse a human-readable token error to decide whether work can resume.

9. Architecture Decisions

Create a lightweight ADR under docs/decisions/ only when a change makes a durable cross-module decision that is not already governed by a PRD. An ADR is appropriate for replacing a protocol, changing a deployable boundary, or adopting a repository-wide persistence or frontend strategy. It is not needed for routine refactors or feature implementation.

An ADR contains:

Status and date
Context
Decision
Alternatives considered
Consequences
Migration/rollback
Affected contracts and modules

10. Handoff Requirements

At the end of a change, report:

• outcome and user-visible behavior;
• important design decisions;
• files and contracts changed;
• tests/builds/validation run and their result;
• known gaps that remain in scope;
• whether docs describe current implementation or target state.

Do not claim completion from documentation alone. Do not mark a target phase implemented until its acceptance tests and required runtime behavior exist.

11. Information Hygiene

• Prefer links to canonical files over duplicated prose.
• Keep stable identifiers and contract names in English even when surrounding documentation is Chinese.
• Use UTC ISO timestamps in machine records; document dates use YYYY-MM-DD.
• Never copy secrets, local tokens, model keys, raw credentials, or credential helper output into prompts, docs, tests, or traces.
• Do not use runtime databases or logs as fixtures without sanitizing and minimizing them.
• Remove or mark superseded guidance rather than leaving two active instructions.
• When target and current architecture differ, label both explicitly.
• After moving a document, scan all first-party Markdown references and build the documentation site before considering the cleanup complete.
• Split an active document or source file when it accumulates unrelated reader tasks or implementation responsibilities; do not raise a legacy size budget to accommodate new behavior.