Principles · v1.0.0

position-keeper-guardrails

Twelve rules a position keeper is built under — and the reason ADR-0007 could be written as data, not remembered.

Status Accepted Version 1.0.0 Ratified Last amended Read time

The standard profile's twelve principles, seeded at init and ratified unchanged once all seven feature bundles had been designed and built against them. P-3 (explicit over implicit), P-5 (record the why) and P-10 (least privilege) are the ones the guardrail leans on: a decision about who may write the positions store is recorded as data with its reason, and every role — the adapter's, the reader's, a downstream service's — gets the narrowest capability that does the job.

Core principles

These bind every spec, plan, and task in this project. Deviations require an amendment to this document and a version bump.

P-1 · Clarity over cleverness

Prefer the simplest code the next reader — human or agent — can follow. Clever indirection is a cost, not a flex.

P-2 · Small, reversible changes

Ship in slices. Every change SHOULD be easy to revert; a large irreversible batch is a design smell.

P-3 · Explicit over implicit

Name things. No hidden magic, no action-at-a-distance an agent can't see from the code in front of it.

P-4 · One set of conventions, enforced

A single formatter and lint config, applied automatically. Style is decided once and enforced by the toolchain, not debated per PR.

P-5 · Record the why

Decisions carry their rationale. Code says what; a decision log or comment says why it had to be this way.

P-6 · Tests accompany behavior

Code that ships carries a test for the behavior it adds. The demoable path is covered before it merges.

P-7 · Contract-first interfaces

A component that exposes an interface ships a checked-in contract before the code behind it — OpenAPI or Swagger for request/response, Protobuf for RPC, GraphQL SDL for GraphQL, AsyncAPI for event-driven, JSON Schema, or a typed signature. The contract is the agent's target and the consumer's guarantee.

P-8 · Library-first boundaries

Keep the reusable core separate from its entry point. Logic lives in a testable, importable library; the CLI, endpoint, or UI is a thin adapter over it.

P-9 · Secure by default

Safe defaults are the floor: no hardcoded credentials, secrets from the environment, authorization on by default. Every insecurity is an explicit, reviewed exception, never an accident.

P-10 · Least privilege

Grant the narrowest capability that does the job — to a service, a token, and an autonomous agent alike. Bound the blast radius before you widen the access.

P-11 · Semantic versioning

Release versions are MAJOR.MINOR.PATCH, a compatibility contract: a breaking change bumps MAJOR, a backward-compatible feature MINOR, a fix PATCH. Dependents and agents then reason mechanically about whether an upgrade is safe.

P-12 · Supply-chain hygiene

Pin, audit, and prune dependencies; adding one is a reviewed decision, not a reflex. Agents pull transitive forests, so bound the blast radius at the manifest.

Scope

This project does

  • Keep securities positions from a stream of trade events, idempotently, behind ports — and prove every change reaches Risk, P&L and the audit trail.
  • Serve read-only queries, health and reference data over a small HTTP surface, contract first.
  • Reconcile the book against the custodian's settled snapshot, nightly and on request from a downstream service — always through the position use case.
  • Demonstrate spectastic's architectural guardrails on a real two-service Gradle build: a decision recorded in 2024's timeline catches a 2026 request at plan and at merge.

This project does not

  • Run in production — the store is an embedded H2 file, authentication is deferred to a gateway that does not exist here, and the dates in docs/timeline.md are narrated.
  • Own the downstream reconciliation service's book: services/reconciliation-service is a separate spectastic project that routes corrections through this one.

Governance

Owners
Position Keeping team — Brian Corbin · @briancorbinxyz.
Decision style
Owner decides; propose changes by PR.
Amendment process
PR to this file with a version bump and a Sync Impact Report.
Versioning
Semver. MAJOR = principle removed/redefined. MINOR = principle added. PATCH = wording.

The standard profile's level of rigor fits this project: a soft enforcement gate (formatter, linter, test-runner — all covered by the Gradle build) and the plan-stage constraint at merge, without the verified tier's coverage floor.

Change log

  1. v1.0.0 · Ratified — the twelve seeded principles unchanged; scope, non-goals and owners filled in at the end of the build-out, once every spec bundle (001–007) had been designed and built against them. Closes inbox I-003: the specs' v1.0.0 links are now true.
  2. v0.1.0 · Seeded by spectastic init --profile standard.