@zigrivers/scaffold 3.28.0 → 3.29.0

package/content/guides/mmr/index.md

@@ -0,0 +1,403 @@
+---
+title: MMR Reference
+topic: mmr
+description: Multi-Model Review — independent AI reviewers, reconciliation, and verdict gating
+category: tools
+order: 10
+---
+
+## What MMR is
+
+Multi-Model Review runs your changes past several **independent** AI code
+reviewers ("channels"), then **reconciles** their findings into a single
+de-duplicated list and a **verdict** that gates the work. No channel ever sees
+another channel's output — agreement between them is what raises confidence, and
+disagreement is what surfaces ambiguity.
+
+### The core idea in five moves
+
+1. **Resolve a diff** — from a PR, staged changes, a branch range, or a piped diff.
+2. **Dispatch channels** — each channel is a separate subprocess given the same
+   prompt, run in parallel and isolated.
+3. **Parse** — each channel's raw output is parsed into a common `Finding` shape.
+4. **Reconcile** — findings are grouped by a stable key, de-duplicated, and
+   scored for agreement and confidence.
+5. **Verdict** — a severity gate yields `pass`, `degraded-pass`, `blocked`, or
+   `needs-user-decision`.
+
+:::callout{type=tip}
+**Two layers, one mental model.** The `mmr` CLI is the engine that dispatches
+the built-in channels and computes the verdict. The `scaffold run review-pr` /
+`review-code` wrappers sit on top: they add a Superpowers code-reviewer *agent*
+channel via `mmr reconcile`, handle auth recovery, and drive the fix loop.
+:::
+
+## End-to-end flow
+
+A single `mmr review … --sync` run walks the whole pipeline. Channels fan out in
+parallel; everything converges at reconciliation.
+
+```mermaid
+flowchart LR
+  R["Resolve diff
+(--pr / --staged
+--diff / --base)"] --> B["Build prompt
+(+ focus, criteria)"]
+  B --> C1["codex"]
+  B --> C2["gemini"]
+  B --> C3["claude"]
+  B --> C4["grok"]
+  B --> C5["doc-conformance
+(opt-in)"]
+  C1 --> P["Parse
+→ Finding"]
+  C2 --> P
+  C3 --> P
+  C4 --> P
+  C5 --> P
+  P --> RC["Reconcile
+(dedupe + score)"]
+  RC --> V["Verdict
+(gate + exit code)"]
+```
+
+Compensating passes (see *Degraded mode* below) are injected *after* the first
+dispatch round for any channel that was unavailable, then folded back into the
+same reconcile step.
+
+## The `mmr review` command
+
+One command, several input modes. Pick the flag that matches your target;
+everything else is control and output options. Type in the box to filter the
+table.
+
+:::filter-table
+| Flag | Group | Description |
+| --- | --- | --- |
+| `--diff <path\|->` | input | Read a unified diff from a file, or `-` for stdin. Highest-priority input mode. |
+| `--pr <n>` | input | Fetch the PR diff via `gh pr diff`. |
+| `--staged` | input | Review staged changes (`git diff --cached`). |
+| `--base <ref> [--head <ref>]` | input | Review a branch range (`git diff base...head`, head defaults to HEAD). |
+| *(no input flag)* | input | Falls back to unstaged working-tree changes (`git diff`). |
+| `--focus <text>` | control | Free-text focus areas appended to every channel prompt. |
+| `--fix-threshold <P0\|P1\|P2\|P3>` | control | Severity gate. Findings at or above this block. Default P2 (from `.mmr.yaml`). |
+| `--channels <names…>` | control | Run only these channels, overriding config defaults. Abstract channels are filtered out. |
+| `--timeout <seconds>` | control | Per-channel timeout override. |
+| `--template <name>` | control | Use a named review-criteria template from config. |
+| `--format <json\|text\|markdown>` | output | Output format. Default `json`. |
+| `--sync` | mode | Run the full pipeline (dispatch → parse → reconcile → verdict) and return results. Without it, dispatch is fire-and-forget. |
+| `--dry-run` | mode | Resolve the diff and assemble the prompt without dispatching any channel. |
+| `--session <id>` | rounds | Link this run into a multi-round session (`[A-Za-z0-9_-]`). |
+| `--round <n>` | rounds | 1-based round counter within a session. |
+| `--max-rounds <n>` | rounds | Hard cap on rounds. Defaults to 5 when `--session` is set without it. |
+| `--accept-new-acks` | trust | Trust acknowledgment files newly introduced by the diff. |
+| `--trust-project-acks` | trust | Trust working-tree project acks in non-Git / untrusted modes. |
+| `--trust-project-config` | trust | Trust working-tree `.mmr.yaml` in untrusted modes. |
+| `--config-base-ref <ref>` | trust | Load `.mmr.yaml` and acks from a trusted Git ref instead of HEAD. |
+:::
+
+### Copy-paste commands by target
+
+```bash
+# PR review (full pipeline, JSON out)
+mmr review --pr 123 --sync --format json
+
+# Staged changes before commit
+mmr review --staged --sync --format json
+
+# All tracked uncommitted changes (no untracked)
+git diff HEAD | mmr review --diff - --sync --format json
+
+# Branch range
+mmr review --base main --head "$BRANCH" --sync --format json
+
+# A single file's current contents, as an "all-added" diff
+(diff -u /dev/null path/to/file.ts || true) | mmr review --diff - --sync --format json
+
+# Only specific channels (e.g. just grok + claude)
+mmr review --pr 123 --channels grok claude --sync --format json
+```
+
+## Other subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `mmr reconcile <job-id> --channel <name> --input <data>` | Inject an external channel's findings (e.g. the Superpowers agent) into an existing job and re-run the results pipeline. Input is a file, `-` for stdin, or inline JSON. |
+| `mmr status <job-id>` | Per-channel status and elapsed time. Exit 0 = all complete, 1 = running, 2 = a channel failed, 5 = not found. |
+| `mmr results <job-id> [--raw]` | Re-run parse → reconcile → format on a completed job. Exit code reflects the verdict. |
+| `mmr jobs <list\|prune>` | List jobs, or prune old ones per `job_retention_days`. |
+| `mmr sessions <start\|list\|show\|end> <id>` | Manage multi-round review sessions (stored under `~/.mmr/sessions/`). |
+| `mmr config <init\|show\|validate…>` | Scaffold and inspect `.mmr.yaml` (including OSS-runtime example blocks). |
+| `mmr ack <add\|list\|rm\|prune>` | Sticky acknowledgments — silence a finding by its stable key so it stops blocking across rounds. |
+
+```bash
+# Capture a job_id from a review, then fold in an agent channel:
+mmr reconcile "$JOB_ID" --channel superpowers --input findings.json
+```
+
+## Channel architecture
+
+A channel is **pure config data** — there is no per-channel code. The dispatcher
+runs whatever `command` the channel defines, hands it the prompt, and parses its
+output with the configured parser. Adding a channel is normally a `.mmr.yaml`
+edit, not a code change.
+
+### The channel config shape
+
+```yaml
+channels:
+  <name>:
+    enabled: true                 # run by default?
+    command: "codex exec"         # whitespace-split, spawned WITHOUT a shell
+    flags: ["--ephemeral"]        # appended after the command tokens
+    env: { KEY: value }           # extra environment
+    prompt_delivery: stdin        # stdin (default) | prompt-file
+    prompt_wrapper: "{{prompt}}"  # template wrapped around the prompt
+    output_parser: default        # default | gemini | doc-conformance | {kind:…}
+    stderr: capture               # capture | suppress | passthrough
+    timeout: 300                  # seconds (falls back to defaults.timeout)
+    auth: { check, timeout, failure_exit_codes, recovery }
+    extends: base-channel         # inherit from another channel (≤4 levels)
+    abstract: false               # template-only; never dispatched directly
+```
+
+### Built-in channels
+
+:::callout{type=info}
+**Why grok is different.** codex/gemini/claude all read the prompt from `stdin`.
+Grok's CLI requires the prompt as an argument and ignores stdin, so its channel
+uses `prompt_delivery: prompt-file` — the dispatcher writes the prompt to a temp
+file and passes its path via the `{{prompt_file}}` placeholder. Grok wraps its
+reply in a JSON `.text` field, which the parser unwraps before extracting
+findings.
+:::
+
+::::tabs
+
+:::tab{title="Compare"}
+| Channel | Default | Strength | Prompt delivery | Parser |
+| --- | --- | --- | --- | --- |
+| `codex` | enabled | Correctness, security, API contracts | stdin | `default` |
+| `gemini` | enabled | Architecture, broad-context reasoning | stdin | `gemini` |
+| `claude` | enabled | Plan alignment, code quality, testing | stdin | `default` |
+| `grok` | enabled | Independent second opinion (xAI; proprietary) | **prompt-file** | `unwrap $.text → default` |
+| `doc-conformance` | opt-in | PRD/stories/standards conformance (LLM-graded) | stdin | `doc-conformance` |
+:::
+
+:::tab{title="codex"}
+```yaml
+command: codex exec
+flags: [--skip-git-repo-check, -s, read-only, --ephemeral]
+auth.check: codex login status        # local file check (fast, 5s)
+recovery: codex login
+output_parser: default
+stderr: suppress
+```
+:::
+
+:::tab{title="gemini"}
+```yaml
+command: gemini                       # NO -p: gemini reads stdin natively
+flags: [--output-format, json]
+env: { NO_BROWSER: "true" }
+auth.check: NO_BROWSER=true gemini -p "respond with ok" -o json   # LLM round-trip, 20s
+recovery: gemini -p "hello"
+output_parser: gemini                 # unwraps { "response": "…" }
+timeout: 360
+```
+:::
+
+:::tab{title="claude"}
+```yaml
+command: claude -p
+flags: [--output-format, json]
+auth.check: claude -p "respond with ok"   # LLM round-trip, 20s
+recovery: claude login
+output_parser: default
+```
+:::
+
+:::tab{title="grok"}
+```yaml
+command: grok
+prompt_delivery: prompt-file
+flags: [--prompt-file, "{{prompt_file}}", --output-format, json]
+auth.check: grok models                # lists models / login state (no round-trip)
+recovery: grok login
+output_parser: { kind: unwrap-jsonpath, wrap: "$.text", then: default }
+```
+
+Grok is proprietary (xAI), not open-source — it joins the standard set
+mechanically as a 4th CLI channel. Disable it with
+`channels_disabled: ["grok"]`.
+:::
+
+:::tab{title="doc-conformance"}
+```yaml
+enabled: false                         # opt-in: runs up to 3 LLM calls (~3 min)
+command: scaffold observe audit --profile=full --scope=all --output-mode=mmr-findings
+output_parser: doc-conformance         # expects a JSON array of findings
+timeout: 240
+```
+
+Enable with `--channels doc-conformance` or in `.mmr.yaml`.
+:::
+
+::::
+
+### The dispatcher
+
+- **Isolation.** Each channel is spawned as its own detached subprocess writing
+  to its own output file; channels run in parallel and never share output.
+- **Prompt delivery.** `stdin` mode pipes the prompt and closes stdin (avoids
+  `E2BIG` on large diffs). `prompt-file` mode writes the prompt to
+  `<channel>.prompt.txt` and substitutes `{{prompt_file}}` in the flags.
+- **Timeout.** A per-channel timer SIGKILLs the whole process group and marks
+  the channel `timeout`.
+- **Command parsing.** `command` is split on whitespace and spawned without a
+  shell — so quoting/pipelines in `command` won't work; that's exactly why
+  arg-only CLIs like grok use `prompt_delivery` rather than a shell shim.
+
+**Adding a new channel — where it's clean vs. hard-coded.** *Clean (config
+only):* a new subprocess channel (`command` + `flags` + `auth` +
+`output_parser`), output reshaping via the `unwrap-jsonpath` or
+`regex-findings` parser kinds, disabling/timeout overrides, and pointing the
+compensator at a different channel — all pure `.mmr.yaml`. *Needs code:* a
+brand-new *named* parser must be registered in `core/parser.ts`; HTTP-endpoint
+channels (`kind: http`) need the planned http-dispatcher; and the
+`COMPENSATING_FOCUS` map carries per-channel focus text (falls back gracefully
+if absent).
+
+## Scaffold wrappers
+
+Direct `mmr review` runs the built-in CLI channels. The `scaffold run` wrappers
+add orchestration on top.
+
+| Wrapper | Target | Adds on top of `mmr review` |
+| --- | --- | --- |
+| `scaffold run review-pr` | A PR (`--pr`) | Auth checks, the Superpowers code-reviewer *agent* channel via `mmr reconcile`, consensus/verdict handling, the 3-strike-per-finding round bookkeeping, optional Beads issue bridge. |
+| `scaffold run review-code` | Local pre-push | Synthesizes a "delivery candidate" diff (committed + staged + unstaged), gathers file & standards context for the file-blind CLIs, then the same agent channel + round bounding. *Untracked files aren't covered.* |
+| `scaffold run post-implementation-review` | Full codebase | Two phases — systemic review + per-story functional review via parallel agents — with its own report under `docs/reviews/`. (See its own doc for the exact channel layout.) |
+
+:::callout{type=warning}
+**Foreground only.** The wrappers' manual fallback runs Codex, Gemini, Claude,
+and Grok as foreground Bash calls when the `mmr` CLI isn't available — never in
+the background. Background execution produces empty output.
+:::
+
+## Findings, reconciliation & verdicts
+
+### The Finding shape
+
+```json
+{
+  "id": "F-001",
+  "category": "security",
+  "severity": "P0",
+  "location": "src/auth.ts:42",
+  "description": "…",
+  "suggestion": "…"
+}
+```
+
+After reconciliation, each finding also carries `confidence`, `sources[]`,
+`agreement`, a stable `finding_key`, a `description_shingle` (for fuzzy
+cross-round matching), and `acknowledged`.
+
+### Stable identity (`finding_key`)
+
+```text
+finding_key = sha1( normLocation | category | sha1(normDescription) | sha1(normSuggestion) )
+```
+
+Line numbers are stripped from the location and severity is *excluded*, so the
+same issue at P1 vs P2 collapses to one key. A character-5-gram shingle backs a
+Jaccard ≥ 0.7 fuzzy match when wording drifts between rounds.
+
+### Agreement & confidence
+
+| Sources | Severity | Agreement | Confidence |
+| --- | --- | --- | --- |
+| 2+ | same | consensus | high |
+| 2+ | differ | majority | medium |
+| 1 | :sev[P0]{level=p0} | unique | high |
+| 1 | `compensating-*` | unique | low |
+| 1 | other | unique | medium |
+
+### The gate & the four verdicts
+
+The gate **passes** when every unacknowledged finding is *below* the
+`fix_threshold` (default :sev[P2]{level=p2}). Severity tiers run
+:sev[P0]{level=p0} (highest) → :sev[P1]{level=p1} → :sev[P2]{level=p2} →
+:sev[P3]{level=p3} (lowest).
+
+| Verdict | Condition | Exit |
+| --- | --- | --- |
+| `pass` | Gate passed, all channels completed | 0 |
+| `degraded-pass` | Gate passed, but some channels failed / timed out / weren't installed | 0 |
+| `blocked` | An unacknowledged finding sits at or above the threshold | 2 |
+| `needs-user-decision` | No channel completed (can't make a determination) | 3 |
+
+:::callout{type=warning}
+Proceed only on **pass** or **degraded-pass**. On **blocked** or
+**needs-user-decision**, surface the verdict and findings — don't merge
+automatically.
+:::
+
+## Degraded mode, compensation & auth
+
+A channel is "degraded" when it's `not_installed` (no binary), `auth_failed`,
+`timeout`, `skipped`, or `failed`. The review doesn't stop — it compensates and
+tells you how to recover.
+
+- **Compensating pass.** For each degraded external channel, a `claude -p` pass
+  runs with that channel's focus area, labeled e.g.
+  `[compensating: Grok-equivalent]`. These findings are single-source, low
+  confidence. The compensator channel is configurable via
+  `defaults.compensator.channel`.
+- **Auth recovery** is surfaced, never silent.
+
+| Channel | Auth check | Recovery |
+| --- | --- | --- |
+| `codex` | `codex login status` | `codex login` |
+| `gemini` | `gemini -p "respond with ok"` | `gemini -p "hello"` |
+| `claude` | `claude -p "respond with ok"` | `claude login` |
+| `grok` | `grok models` | `grok login` |
+
+## Configuration (`.mmr.yaml`)
+
+Config is layered: built-in defaults → `~/.mmr/config.yaml` → project
+`.mmr.yaml` → CLI flags. Arrays replace; objects deep-merge.
+
+```yaml
+version: 1
+defaults:
+  fix_threshold: P2          # gate severity
+  timeout: 300               # default per-channel timeout (s)
+  parallel: true
+channels_disabled: ["grok"]  # opt OUT of a built-in (e.g. no grok installed)
+channels:
+  doc-conformance:
+    enabled: true            # opt IN to a default-off channel
+  # Bring-your-own model via channel inheritance:
+  qwen-local:
+    command: ollama run
+    flags: ["qwen2.5-coder:32b", "--format", "json"]
+    output_parser: { kind: unwrap-jsonpath, wrap: "$.response", then: default }
+    auth: { check: "ollama list", timeout: 5, failure_exit_codes: [1], recovery: "ollama serve" }
+```
+
+- `channels_disabled` — skip these built-ins in the default dispatch (ignored
+  when you pass an explicit `--channels` list).
+- `enabled: false` — per-channel off switch (how `doc-conformance` ships).
+- `extends` — inherit from another channel (≤ 4 levels, cycle-checked); child
+  fields override the parent.
+- `fix_threshold` — project gate; override per-run with `--fix-threshold`.
+
+:::callout{type=danger}
+**Trust boundary.** When reviewing a diff, project `.mmr.yaml` and acks should
+be read from the diff's *base ref*, not the working tree — otherwise a PR could
+add a channel that exfiltrates secrets or self-acknowledge its own findings. Use
+`--config-base-ref` / the `--trust-project-*` flags to control this in untrusted
+(e.g. CI) contexts.
+:::

package/content/knowledge/VERSION

@@ -0,0 +1 @@
+0.1.0

package/content/knowledge/backend/backend-api-design.md

@@ -2,6 +2,14 @@
 name: backend-api-design
 description: REST maturity levels, GraphQL schema-first design, gRPC protobuf conventions, tRPC router patterns, API versioning strategies, pagination, and filtering
 topics: [backend, api-design, rest, graphql, grpc, trpc, versioning, pagination]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://spec.openapis.org/oas/latest.html
+  - url: https://spec.graphql.org/
+  - url: https://www.rfc-editor.org/rfc/rfc9110.html
+  - url: https://martinfowler.com/articles/richardsonMaturityModel.html
 ---
 
 API design is a long-lived contract. Every structural decision — URL shape, error format, pagination scheme, versioning strategy — is expensive to change after consumers depend on it. Design APIs from the consumer's perspective first. The best API is one where new developers can predict the shape of an endpoint they have never seen before, because every other endpoint follows the same patterns.

package/content/knowledge/backend/backend-architecture.md

@@ -2,6 +2,14 @@
 name: backend-architecture
 description: Monolith vs microservices decision framework, layered architecture patterns, CQRS, event sourcing, hexagonal architecture, and service mesh considerations
 topics: [backend, architecture, microservices, monolith, cqrs, event-sourcing, hexagonal, clean-architecture]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://microservices.io/patterns/
+  - url: https://martinfowler.com/bliki/CQRS.html
+  - url: https://martinfowler.com/eaaDev/EventSourcing.html
+  - url: https://martinfowler.com/bliki/MonolithFirst.html
 ---
 
 Backend architecture is the set of structural decisions that determine how the system scales, how teams work independently, and how expensive future changes will be. The single most common backend architecture mistake is choosing microservices before the problem demands them. Start with the simplest architecture that solves the current problem, and evolve to complexity only when specific pain points — not hypothetical future ones — force the change.

package/content/knowledge/backend/backend-async-patterns.md

@@ -2,6 +2,13 @@
 name: backend-async-patterns
 description: Message queue patterns, event-driven architecture, saga patterns, retry strategies, and idempotency keys
 topics: [backend, async, message-queues, event-driven, saga, retry, idempotency, cqrs]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://microservices.io/patterns/data/saga.html
+  - url: https://martinfowler.com/articles/patterns-of-distributed-systems/
+  - url: https://sre.google/sre-book/handling-overload/
 ---
 
 Asynchronous patterns decouple services in time and space, enabling systems to absorb load spikes, survive partial failures, and scale independently — but they introduce delivery guarantees and consistency tradeoffs that must be designed for explicitly from the start.

package/content/knowledge/backend/backend-auth-patterns.md

@@ -2,6 +2,15 @@
 name: backend-auth-patterns
 description: JWT lifecycle, OAuth2 authorization code flow, API key management, and service-to-service authentication
 topics: [backend, auth, jwt, oauth2, api-keys, mtls, security]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.rfc-editor.org/rfc/rfc6749
+  - url: https://www.rfc-editor.org/rfc/rfc7519
+  - url: https://www.rfc-editor.org/rfc/rfc7636
+  - url: https://openid.net/specs/openid-connect-core-1_0.html
+  - url: https://owasp.org/www-project-api-security/
 ---
 
 Authentication and authorization are the first line of defense for any backend service — mistakes here compromise the entire system, making it essential to use proven patterns like JWTs with rotation, OAuth2 with PKCE, and workload identity from the start.

package/content/knowledge/backend/backend-conventions.md

@@ -2,6 +2,12 @@
 name: backend-conventions
 description: Service and handler naming conventions, structured error handling patterns, structured logging with correlation IDs, and file organization standards for backend codebases
 topics: [backend, conventions, error-handling, logging, naming, file-organization]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://google.github.io/styleguide/
+  - url: https://martinfowler.com/tags/clean%20code.html
 ---
 
 Consistent conventions in a backend codebase reduce cognitive load, make code reviewable at a glance, and prevent entire classes of bugs. Naming, error handling, and logging are the three highest-leverage areas — they touch every layer of the stack and every engineer on the team. Establish these conventions before the first PR, codify them in linting rules where possible, and treat violations as blocking review comments.

package/content/knowledge/backend/backend-data-modeling.md

@@ -2,6 +2,13 @@
 name: backend-data-modeling
 description: Relational vs document modeling tradeoffs, migration strategies, connection pooling, ORM vs query builder tradeoffs, multi-tenancy patterns, and eventual consistency
 topics: [backend, data-modeling, database, migrations, orm, multi-tenancy, eventual-consistency, connection-pooling]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.postgresql.org/docs/current/
+  - url: https://martinfowler.com/articles/evodb.html
+  - url: https://microservices.io/patterns/data/database-per-service.html
 ---
 
 Data modeling decisions have the highest reversal cost of any backend choice. A schema design that seemed reasonable at launch can become an operational crisis at scale — queries that worked at 10,000 rows fail at 100 million. The goal is to match the data model to the access patterns of the application, not to normalize for its own sake or to denormalize prematurely. Design the schema with the queries in mind from day one.

package/content/knowledge/backend/backend-deployment.md

@@ -2,6 +2,14 @@
 name: backend-deployment
 description: Containerization best practices, serverless patterns, health check endpoints, graceful shutdown, and deployment strategies
 topics: [backend, deployment, docker, serverless, health-checks, graceful-shutdown, blue-green, canary]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/bliki/BlueGreenDeployment.html
+  - url: https://martinfowler.com/bliki/CanaryRelease.html
+  - url: https://sre.google/sre-book/release-engineering/
+  - url: https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/welcome.html
 ---
 
 Deployment reliability is a multiplier on every other engineering investment — a well-written service that deploys poorly will cause more incidents than a mediocre service that deploys safely and rolls back cleanly.

package/content/knowledge/backend/backend-dev-environment.md

@@ -2,6 +2,11 @@
 name: backend-dev-environment
 description: Docker Compose for local databases and queues, database seeding and migration scripts, API testing tools, environment variable management, and local SSL setup
 topics: [backend, dev-environment, docker, migrations, testing, environment-variables]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.postgresql.org/docs/current/
 ---
 
 A backend development environment that requires manual setup steps is a productivity drain and an onboarding failure. The standard should be: clone the repo, run one command, and have a fully functional local environment in under five minutes. Docker Compose is the primary tool for achieving this — it pins the exact versions of every external dependency and makes the environment reproducible across all developer machines.

package/content/knowledge/backend/backend-fintech-broker-integration.md

@@ -2,6 +2,12 @@
 name: backend-fintech-broker-integration
 description: Multi-broker adapter pattern; credential rotation; error harmonization; rate-limit management; broker-side quirks.
 topics: [backend, fintech, brokers, integration, adapter-pattern, rate-limits, credentials, retry]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://microservices.io/patterns/reliability/circuit-breaker.html
+  - url: https://martinfowler.com/bliki/CircuitBreaker.html
 ---
 
 A fintech backend that routes orders or reads positions across more than one broker inherits the union of every broker's quirks, outages, auth schemes, and undocumented behaviors. The broker-integration layer exists to hide that mess behind one normalized internal contract so the rest of the system — risk, order lifecycle, ledger, UI — can stay clean. This doc covers the adapter contract, credential handling, error harmonization, rate-limit strategy, and the specific pitfalls that recur regardless of which brokers you connect.

package/content/knowledge/backend/backend-fintech-compliance.md

@@ -2,13 +2,21 @@
 name: backend-fintech-compliance
 description: PCI-DSS, SOC 2, SEC/FINRA regulations for consumer/B2B fintech backends; audit trail immutability; data retention; segregation of duties.
 topics: [backend, fintech, compliance, pci-dss, soc2, sec, finra, audit-trail, gdpr]
+volatility: evolving
+last-reviewed: null
+version-pin: 'PCI-DSS v4.0.1'
+sources:
+  - url: https://www.pcisecuritystandards.org/document_library/
+  - url: https://www.aicpa-cima.com/topic/audit-assurance
+  - url: https://www.finra.org/rules-guidance/rulebooks/finra-rules
+  - url: https://eur-lex.europa.eu/eli/reg/2016/679/oj
 ---
 
 Fintech compliance is not a checklist applied at the end — it determines schema design, deployment pipelines, and system boundaries. Most regulations apply based on what a service *touches* (cards, trades, PII), so scope reduction is the single highest-leverage design decision available to engineering. This doc covers the regulatory regimes a typical US/EU fintech encounters, the audit-trail patterns they demand, and concrete implementation choices that keep audits survivable.
 
 ## Summary
 
-Which regulations apply depends on what the service handles. Handling card data (PAN, CVV, track data) triggers PCI-DSS v4.0. Storing customer PII, financial records, or operating as a service provider to regulated firms triggers SOC 2 Type II expectations from customers and GLBA obligations (US financial privacy). Executing securities trades or routing orders triggers SEC Rule 17a-4 record retention and FINRA supervisory requirements. Operating in the EU triggers GDPR and — for crypto — MiCA. Serving retail vs institutional customers changes consumer-protection obligations (Reg Z, Reg E, CFPB oversight vs institutional carve-outs).
+Which regulations apply depends on what the service handles. Handling card data (PAN, CVV, track data) triggers PCI-DSS v4.0.1. Storing customer PII, financial records, or operating as a service provider to regulated firms triggers SOC 2 Type II expectations from customers and GLBA obligations (US financial privacy). Executing securities trades or routing orders triggers SEC Rule 17a-4 record retention and FINRA supervisory requirements. Operating in the EU triggers GDPR and — for crypto — MiCA. Serving retail vs institutional customers changes consumer-protection obligations (Reg Z, Reg E, CFPB oversight vs institutional carve-outs).
 
 Compliance cost scales with scope, not with traffic. A service that never sees raw PANs is *out of scope* for most PCI-DSS controls. A microservice that only handles trade metadata (not orders themselves) may be out of the SEC 17a-4 retention perimeter. Practical scope-reduction strategies: tokenize at the edge (Stripe, Marqeta, Basis Theory) so internal services only ever see tokens; keep regulated datastores (ledger, order book, card vault) in dedicated VPCs with narrow IAM; route regulated-data logs to a separate SIEM stream so the main observability stack stays out of scope; design SDK boundaries where PII-sensitive fields are never emitted to general-purpose workers.
 
@@ -22,7 +30,7 @@ Encryption is assumed baseline: TLS 1.2+ in transit (1.3 preferred), AES-256 at
 
 ### PCI-DSS Scoping and Tokenization
 
-PCI-DSS v4.0 applies to any system that stores, processes, or transmits cardholder data (CHD) — the Primary Account Number (PAN), cardholder name, expiration date, service code — or sensitive authentication data (full track, CVV, PIN). The cost of compliance is roughly quadratic in the scope of the "cardholder data environment" (CDE): every service inside the CDE needs quarterly ASV scans, annual penetration tests, hardened configurations, FIM, and quarterly access reviews.
+PCI-DSS v4.0.1 applies to any system that stores, processes, or transmits cardholder data (CHD) — the Primary Account Number (PAN), cardholder name, expiration date, service code — or sensitive authentication data (full track, CVV, PIN). The cost of compliance is roughly quadratic in the scope of the "cardholder data environment" (CDE): every service inside the CDE needs quarterly ASV scans, annual penetration tests, hardened configurations, FIM, and quarterly access reviews.
 
 **Scope reduction via tokenization** is the dominant pattern. Instead of your application receiving raw PANs, the card is submitted directly from the browser/mobile app to a tokenization provider (Stripe Elements, Braintree Hosted Fields, Marqeta, Basis Theory, Very Good Security) which returns an opaque token. Your backend stores only the token. The card vault is the provider's CDE; your systems are *SAQ A* eligible (the lightest form).
 

package/content/knowledge/backend/backend-fintech-data-modeling.md

@@ -2,6 +2,12 @@
 name: backend-fintech-data-modeling
 description: Financial data models; currency handling; decimal precision; positions, trades, prices; time-series designs.
 topics: [backend, fintech, data-modeling, decimal, currency, time-series, positions, trades]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://www.postgresql.org/docs/current/datatype-numeric.html
+  - url: https://www.iso.org/iso-4217-currency-codes.html
 ---
 
 Financial data modeling is where most fintech bugs are born: a float creeps into a money field, a currency is implied instead of stored, a tick table grows unbounded, or a `current_position` column drifts from the journal. This doc covers the non-negotiable shapes of money, quantity, and price data, and the time-series and derived-view patterns that keep a trading or banking system honest at scale.

package/content/knowledge/backend/backend-fintech-ledger.md

@@ -2,6 +2,12 @@
 name: backend-fintech-ledger
 description: Double-entry accounting for fintech ledgers; journal vs ledger tables; idempotent posting; reconciliation patterns; balance invariants.
 topics: [backend, fintech, ledger, double-entry, accounting, reconciliation, idempotency, invariants]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/eaaCatalog/
+  - url: https://www.postgresql.org/docs/current/ddl-constraints.html
 ---
 
 A fintech ledger is the authoritative record of money movement; if it is wrong, nothing else in the system can be trusted. The discipline is borrowed intact from 700 years of double-entry bookkeeping — not a new invention, and not negotiable. This doc covers the invariants, schema shape, idempotent posting mechanics, and reconciliation patterns that keep a ledger survivable at production scale.

package/content/knowledge/backend/backend-fintech-observability.md

@@ -2,6 +2,12 @@
 name: backend-fintech-observability
 description: Trade event correlation; market-hours aware scheduling; SLOs for fintech systems; compliance logging; alerting strategy.
 topics: [backend, fintech, observability, tracing, slos, alerting, correlation-id, market-hours]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://opentelemetry.io/docs/
+  - url: https://sre.google/sre-book/service-level-objectives/
 ---
 
 Observability for a trading system is not generic APM with a finance skin — it is the ability to reconstruct any single order, end to end, across six or more services, on demand, years later, with timezone-correct timestamps and a stable correlation identifier. It is also the early-warning system that catches a sudden drop in fill rate at 09:31 ET before the desk calls. Done well it overlaps with — but does not replace — the immutable audit trail (`backend-fintech-compliance.md`).

package/content/knowledge/backend/backend-fintech-order-lifecycle.md

@@ -2,6 +2,12 @@
 name: backend-fintech-order-lifecycle
 description: Order state machine; fills, partial fills, cancellation; event-driven order tracking; idempotency; handling "unknown" states.
 topics: [backend, fintech, orders, state-machine, fills, partial-fills, event-driven, webhooks]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://microservices.io/patterns/data/saga.html
+  - url: https://martinfowler.com/articles/patterns-of-distributed-systems/
 ---
 
 Orders in a trading system are long-lived, asynchronous, externally mutated objects — the exact shape of problem a disciplined state machine is built for. This doc covers the canonical states and transitions, how fills and partial fills land, why "unknown" is a real state you cannot wish away, and the reconciliation posture that keeps internal bookkeeping aligned with the broker of record.

package/content/knowledge/backend/backend-fintech-risk-management.md

@@ -2,6 +2,12 @@
 name: backend-fintech-risk-management
 description: Position limits, drawdown caps, circuit breakers, kill switches; pre-trade and post-trade risk checks; operational risk controls.
 topics: [backend, fintech, risk, position-limits, drawdown, circuit-breakers, kill-switch, pre-trade-checks]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/bliki/CircuitBreaker.html
+  - url: https://microservices.io/patterns/reliability/circuit-breaker.html
 ---
 
 Risk management in a trading system is the set of controls that stops a bad day from becoming a catastrophic one. It lives in two places: *before* an order goes to the broker (pre-trade checks that block) and *after* fills land (post-trade monitoring that alerts, throttles, or halts). Neither half is optional, and both are exercised continuously, not just during incidents.