railiance-clock/AGENTS.md

railiance-clock — Agent Instructions

Purpose: authenticated, uncertainty-aware application time across independently managed hosts. Domain: infotech. Repo slug: railiance-clock. Prefix: RCLK-WP-.

Orientation

Read INTENT.md → SCOPE.md → specs/railiance-clock-v0.1.md → specs/acceptance-v0.1.md → docs/ecosystem.md → .custodian-brief.md → workplans/. Check unread Statehub messages to railiance-clock and relevant human-needed tasks. Mark read only after processing. Inspect local Git changes before editing.

State Hub

Use REST/CLI; MCP is opt-in. Local primary tunnel: http://127.0.0.1:8000; remote tunnel alternative: http://127.0.0.1:18000. Verify /state/health identity before writes: expected primary/railiance01. Explicitly configured relay receipts are pending until replay/readback. Retry sandbox-related loopback failures with escalated execution before declaring an outage. Do not copy work records into a second database or treat Statehub as time authority.

Workplans are source files in workplans/RCLK-WP-NNNN-.md. Use frontmatter id, type: workplan, title, domain: infotech, repo: railiance-clock, status, owner, created and updated. Statuses: proposed, ready, active, blocked, backlog, finished, archived. One task block per ## section; task id RCLK-WP-NNNN-TNN, status wait/todo/progress/done/cancel and priority high/medium/low. Repo Manager assigns only missing deterministic bridge UUIDs; do not fabricate them.

Before finishing a plan, hand residuals to live work records. Log meaningful progress to POST /progress/ with author and workplan/task UUID when applicable. After source changes, commit then run:

uv run --project ~/repo-manager rmgr sync --path . --push

Require exact pushed-commit applied/noop receipt from primary/railiance01. A queued receipt is pending. Use statehub fix-consistency only for a separate deep audit.

Engineering boundaries

• This seed is not a deployed service or adopted security contract.
• Do not change corporate host clocks, time configuration or artifact validity fields as a workaround. Adoption belongs to the consumer and security owners.
• Forgejo preserves history; Git dates and HTTP Date headers are not trusted time samples.
• Never equate signature validity with clock accuracy or a nonce with delay bounds.
• Never weaken TLS verification, accept future/expired credentials on guessed time, or silently fall back to OS wall time when the Railiance clock is unusable.
• No security engine roles, policies, keys or public listeners are created by registration.
• Test with fake clocks and disposable infrastructure first. Native tests must preserve expiry, wrong-identity and failure-path checks.
• Before credential work run warden plan "<need>" --json, then route find/show. Use admitted owner transports; never print or commit secret values.
• Use the canonical security-layer model and Railiance owner contracts linked in docs/ecosystem.md. Record undecided layer/PEP mapping as open review, not compliance.