aura-labs.ai

Feature Readiness Standard

Every feature merged to main must satisfy the acceptance criteria defined in this standard. This applies equally to new features, enhancements, bug fixes, and refactors that touch user-facing endpoints or business-critical paths.

This is not a suggestion — it is a blocking requirement. Pull requests that do not meet these criteria must not pass the pipeline gate.

Why This Exists

AURA handles real money. A feature that works but can’t be monitored, secured, traced, or tested in production is a liability. The Access Worldpay platform taught us that operational maturity comes from discipline at the feature level, not from bolting quality onto a running system after the fact.

The Core Principle

Define what “done” looks like before writing code.

This principle applies to everything: tests, security, observability, API contracts, and documentation. These are not separate activities performed at different stages. They are all part of answering one question before the first line of implementation is written: “What must be true for this feature to be complete?”

Every feature begins with acceptance criteria. Those criteria are written into the PR description or linked issue before the first implementation commit. The criteria cover all of the domains below. If a domain doesn’t apply (e.g., the change doesn’t introduce a new endpoint), note that explicitly — don’t leave it ambiguous.

Acceptance Criteria Domains

1. Functional Correctness

What logic paths must be tested? What edge cases? What error conditions? What end-to-end flows must work? What database state transitions?

Before code:

• Define unit test criteria: happy path, error paths, edge cases, boundary conditions.
• Define integration test criteria: end-to-end flows, database state transitions, multi-step operations.
• For state-changing operations, specify the valid and invalid state transitions.

2. Security

What are the security requirements for this feature? What attack surfaces does it introduce or modify?

Before code, answer these questions against the API Security Baseline (docs/security/API_SECURITY_BASELINE.md):

• Authentication: Does this endpoint require authentication? If yes, specify { preHandler: verifyAgent }. If no, document why it is safe to leave unauthenticated.
• Object-level authorization (API1): Does this endpoint accept a resource identifier? If yes, specify the ownership predicate that will be included in the database query. Write the SQL clause. “Agent A cannot access agent B’s resource” is not a criterion — WHERE id = $1 AND agent_id = $2 is.
• Property-level authorization (API3): Does the response include fields that should not be visible to all callers? If yes, specify which fields are filtered for which roles.
• Function-level authorization (API5): Which agent roles are authorized to call this endpoint? Specify explicitly (e.g., “scout only”, “beacon only”, “any authenticated agent”, “session owner or associated beacon”).
• Input validation: What are the type, format, and size constraints on every input field? Specify maximums.
• SSRF (API7): Does this feature make outbound HTTP requests based on user-supplied data? If yes, specify the URL validation rules.
• Rate limiting: Does this feature need endpoint-specific rate limits beyond the global defaults?

Write specific, testable security criteria. Examples of good criteria:

• “GET /v1/sessions/:sessionId returns 403 when the requesting agent is not the session creator.”
• “POST /v1/offers rejects requests from agents with role ‘scout’.”
• “Webhook endpoint URL must be HTTPS and must not resolve to a private IP range.”

Examples of criteria that are too vague to be useful:

• “Authentication enforced.” (Enforced how? On which endpoints? What happens on failure?)
• “Input validated.” (Which fields? What constraints? What error codes?)
• “Authorization requirements documented.” (Documented where? What specific checks?)

3. API Contract

What does the request/response interface look like?

Before code:

• Define request schema: required fields, types, constraints, content type.
• Define response schema: success shape, error shapes, status codes.
• Define HATEOAS links and their semantics.
• For state-changing endpoints, define the idempotency strategy (idempotency key format, duplicate handling).
• For collection endpoints, define pagination parameters (default limit, maximum limit).

4. Observability

How will this feature be monitored in production?

Before code:

• Business metrics: What counters, gauges, or histograms must be emitted? Specify the metric name, labels, and the action that triggers emission. Use the metric naming conventions from metrics.js.

  Action	Required Metric	Example
  Entity created	Counter increment	sessionsCreatedTotal.inc()
  Entity state change	Counter increment	transactionsCommittedTotal.inc()
  Active entity tracking	Gauge inc/dec	activeSessions.inc() / .dec()
  External call outcome	Counter with status label	webhookDeliveriesTotal.inc({ status: 'success' })

• Trace context: Does this feature make outgoing HTTP calls? If yes, it must propagate W3C Trace Context via getTraceHeaders(request).
• Structured logging: What significant events must be logged? All logs must use request.log (which automatically includes traceId and spanId), never console.log.
• Error observability: 4xx errors logged at warn level with error code and context. 5xx errors logged at error level with stack trace.
• SLO impact: Does this feature introduce a new latency-sensitive path? If yes, document its impact on existing SLO targets. If it introduces a new SLI, add it to slo.js.

5. Documentation

What must be updated?

• API documentation for new/changed endpoints.
• Decision log entry for any non-trivial architectural choice.
• DEPLOYMENT.md if new environment variables or infrastructure dependencies are added.
• API Security Baseline if new OWASP-relevant patterns are introduced.

Verification (CI-Enforced)

Criteria are only as good as their verification. Every domain above must have corresponding tests that run in CI.

Functional tests

Unit and integration tests that verify the logic paths defined in domain 1.

Security tests

Tests that verify the security behaviour defined in domain 2. These are not optional supplements — they are acceptance tests, same as any functional test.

Required patterns:

• Authorization boundary tests: For every endpoint that enforces ownership, test that agent A cannot access agent B’s resources. Assert 403.
• Authentication tests: For every authenticated endpoint, test that requests without valid signatures receive 401.
• Input validation tests: For every validated field, test that invalid input receives 400 with a specific error code.
• SSRF tests (where applicable): Test that private IP ranges and non-HTTPS URLs are rejected.

Observability tests

Tests that verify the metric emission and trace propagation defined in domain 4. Use the MetricsTestHelper from src/lib/test-helpers/metrics-helper.js.

Required patterns:

• After exercising the happy path, assert that the expected counter/histogram/gauge was updated.
• Assert that emitted metrics carry the correct labels.
• For features making outgoing calls, assert that the outgoing request includes a valid traceparent header.

Example:

import { MetricsTestHelper } from '../lib/test-helpers/metrics-helper.js';
import { sessionsCreatedTotal } from '../lib/metrics.js';

test('POST /sessions increments sessions_created counter', async () => {
  const helper = new MetricsTestHelper();
  await helper.snapshot(); // MUST await

  const response = await app.inject({
    method: 'POST',
    url: '/v1/sessions',
    payload: { intent: 'buy running shoes' },
  });

  assert.equal(response.statusCode, 200);
  await helper.assertCounterIncremented(sessionsCreatedTotal, 1);
});

PR Checklist

Copy this into your PR description:

## Feature Readiness Checklist

### Acceptance Criteria (defined before code)
- [ ] Functional test criteria defined (unit paths, integration flows, state transitions)
- [ ] Security criteria defined against API Security Baseline (auth, authorization, input validation, SSRF)
- [ ] API contract defined (request/response schemas, pagination, idempotency)
- [ ] Observability criteria defined (metrics, trace propagation, logging, SLO impact)
- [ ] Documentation needs identified

### Implementation Verification
- [ ] Unit tests pass (including authorization boundary tests)
- [ ] Integration tests pass
- [ ] Security acceptance tests verify authorization, authentication, input validation
- [ ] Observability tests verify metric emission and labels
- [ ] Performance tests pass (if latency-sensitive path)

### Documentation
- [ ] API docs updated
- [ ] Decision log entry (if architectural choice made)
- [ ] DEPLOYMENT.md updated (if new env vars or infra)
- [ ] Security annotations on route handlers (OWASP categories considered)

Enforcement

The CI pipeline (Pipeline gate) blocks merge if any test job fails. Security tests, observability tests, and functional tests all run as part of the standard test suite. There are no separate gates — security and observability are not optional add-ons, they are part of the definition of done.

If a PR adds a new endpoint without corresponding authorization boundary tests and metric emission tests, the review must flag it as incomplete.

Reference Documents

• API Security Baseline: docs/security/API_SECURITY_BASELINE.md
• Security Audit Report: docs/security/SECURITY_AUDIT_REPORT.md
• SLI/SLO Definitions: src/lib/slo.js
• Metrics Definitions: src/lib/metrics.js
• Tracing: src/lib/tracing.js
• Decision Log: docs/decisions/DECISION_LOG.md