Operations

A stack that needs several terminals and a wiki page starts differently for every developer, and the differences become bug reports nobody can reproduce. One named command brings WebApi, PostgreSQL, the frontends, and the background Worker up together, so every developer and every agent starts from the same running system. The baseline command is Aspire's AppHost, with ServiceDefaults supplying the shared discovery, health, resilience, and telemetry defaults its resources rely on. A workspace that orchestrates the same set another way satisfies this rule with its own command: the obligation is that one command brings the stack up, not that one tool does.

Reviewed forOne command named in the consumer AGENTS.md starts WebApi, PostgreSQL, the frontends, and the Worker.

Marked guidance: a reviewer answers this question.

Each running service is a host, and one request often crosses several. Logs and traces carry timestamp, level, service, environment, trace identifier, and span identifier, and metrics carry service and environment labels. The correlation identifiers let one request be followed across every host it touched, which is the only trail a cross-host failure leaves. Stable event names keep dashboards working across releases instead of breaking each time a message is reworded.

Reviewed forLogs and traces carry correlation identifiers, and metrics carry service labels.

Marked guidance: a reviewer answers this question.

A trace identifier joins the runtime records of one request to each other, but not to the specification: a person holding a slow span, a log line, or an error report still has to guess which use case it was. The identity is already a generated value, so a pipeline stage reads it from the registry once per message and stamps it on every surface under one name, and reactions, jobs, and outbox consumers carry it as well as requests. A metric carries it only as a label on an instrument whose series stay bounded: a duration histogram labeled by every use case multiplies its series by hundreds, so request instruments label by module instead.

A Claimwick request to submit an expense opens a span and a log scope carrying litespec.use_case = use-case/spending.submit-expense, and an unhandled failure inside it reaches the error tracker with the same tag.

Reviewed forWhich pipeline stage reads the registry and stamps litespec.use_case on the span, the log scope, and the error report of each mediated message? Look at the mediator pipeline and one error report per host.

Marked guidance: a reviewer answers this question.

An alert is the runtime half of a quality requirement: it fires when the measure the requirement promises is breached, and the runbook says what a person does next. Written as a file path or left out, the link is a string no tool follows, so an alert can outlive its requirement, a requirement can lose its last alert, and a renamed runbook breaks silently. Record identifiers in the alert's own labels keep the link in the file the alert lives in, in the syntax its tool already reads, and let the model check both ends. A baseline alert also carries its window and severity, as litespec/ext/delivery#define-actionable-baseline-alerts states for projects that select the Delivery extension.

Claimwick's alert rule submission-acknowledgement-slow carries requirement: requirement/expense-submission.month-end-submissions and runbook: runbook/slow-submissions in its labels.

Checked bylitespec model check reports alert-link-missing (level S) for an alert rule in the files paths.alerts names whose requirement label is missing or names no quality requirement, or whose runbook label is missing or names no runbook.

Marked checkable: the tool named here checks it.

A quality requirement nobody watches is a promise checked only when a customer notices it broken. An alert names it to watch production, and a check result, from a measured check or a drill, names it through its check to show it was measured before release; a requirement that cannot be watched yet says so as a gap exception with a reason, an exit and an expiry date, instead of passing silently.

requirement/expense-submission.month-end-submissions is named by the alert submission-acknowledgement-slow and by the k6 result its check names.

Checked bylitespec model check reports quality-alert-missing (level G) for a quality requirement that no alert rule names in its requirement label, whose check matches no measured-check or check result the model read, and that no gap exception covering quality-alert-missing lists in its subject.

Marked checkable: the tool named here checks it.

Operations files hold choices as load-bearing as code: the proxy's security headers, the backup schedule, the gates a pull request passes. Their reason usually lives in a comment that no tool reads, so a retired decision leaves its configuration behind unnoticed. A follows mark in the file's own comment syntax is the same link a technical class carries, so decision-unimplemented and mark-unknown cover these files too.

Claimwick's deploy/Caddyfile opens with # <follows>decision/0004-serve-receipts-behind-one-proxy</follows>.

Checked bylitespec model check reports mark-missing (level S) for a file in paths.operations with no follows mark and mark-unknown (level S) for a mark naming no decision, exception, or provision, and counts the file toward decision-unimplemented.

Marked checkable: the tool named here checks it.

An identifier that each host formats its own way correlates nothing across the boundary between them. traceparent is the format OpenTelemetry implements and every managed backend accepts, so a trace crosses a frontend, an API, a background host, and a provider without translation. One propagator, the component that reads and writes the headers, is the part that matters: two configured propagators produce two identifiers for one request, and the trace splits at whichever hop reads the other one.

The trace identifier in a Problem Details response is the trace-id field of the current traceparent, which is what litespec/backend/api#return-stable-problem-details returns.

Reviewed forOne propagator reads and writes W3C trace context on every host.

Marked guidance: a reviewer answers this question.

Liveness answers whether the process is alive; readiness answers whether it can safely serve traffic. When a dependency fails, readiness fails so the orchestrator stops sending traffic, while liveness stays true so the orchestrator does not restart a healthy process. One endpoint for both forces a choice between serving traffic the application cannot handle and restarting a process that only needs its dependency back.

Reviewed forLiveness answers without dependency checks while readiness includes the critical ones.

Marked guidance: a reviewer answers this question.

Schema work is a release step, not a startup step. A replica that applies schema at startup races its siblings, and each one serves traffic against a half-applied schema until the race settles. Running the change as one dedicated step before traffic shifts, reviewed against both the old and the new application version, keeps every replica on the same schema from its first request.

Reviewed forThe schema step runs before traffic shifts, with no schema work at replica startup.

Marked guidance: a reviewer answers this question.

A Worker fails on its own schedule: its queue grows, its retries climb, its oldest item ages, while WebApi keeps answering health checks. Without its own liveness, readiness, processing rate, failure count, retry count, oldest pending age, and shutdown behavior, the failure stays invisible until the backlog is the incident. WebApi readiness otherwise hides a failed Worker while the queue grows unobserved.

Reviewed forThe Worker publishes its own health, rates, counts, oldest pending age, and shutdown behavior.

Marked guidance: a reviewer answers this question.

Every network call waits on a system the product does not control. Without an explicit timeout and cancellation path, one slow provider holds a request thread until that unrelated system recovers, and each held thread is one less thread for healthy requests. Retries stay bounded and idempotent-only, because retrying a call that already acted repeats the act.

Reviewed forEach network call declares a timeout, a cancellation path, and bounded retries for idempotent operations only.

Marked guidance: a reviewer answers this question.

Customers ask which providers touch their data, and the sub-processor list is the answer. The model builder renders it from the provider actor records, so a provider added in code but missing from the list answers that question wrong. Generating the list from records keeps the answer and the code in step.

Reviewed forEach provider the release calls appears on the generated sub-processor list.

Marked guidance: a reviewer answers this question.

A runbook nobody names answers no failure: an alert, a job, a reaction or a failure policy is the caller that sends a person to the procedure, and without that link the procedure waits undiscovered while the failure it answers is handled from memory. Naming each runbook from at least one caller keeps every procedure reachable from the event that needs it.

Claimwick's job send-event-change-notices names runbook/clear-stuck-notices in its runbook field, so the procedure is reachable from the work that needs it.

Checked bylitespec model check reports runbook-unused (level A) for a runbook record that no alert label, job, reaction or failure policy names.

Marked checkable: the tool named here checks it.

A secret committed once lives in history after deletion, readable to everyone the repository ever reaches. Keeping production values on the host and only placeholders in a repository example file keeps the values with the deployment that needs them and out of every clone.

Reviewed forProduction values live on the host, with only placeholders in the repository example file.

Marked guidance: a reviewer answers this question.