@zigrivers/scaffold 3.28.0 → 3.30.0

package/content/guides/review-workflow/index.md

@@ -0,0 +1,248 @@
+---
+title: The Code-Review Workflow
+topic: review-workflow
+description: When and how to run multi-model review — entry points, input modes, verdicts, the round limit, and degraded mode
+category: workflows
+order: 30
+---
+
+## What this guide covers
+
+This is the **workflow** around multi-model review: *when* to review, *which*
+entry point to reach for, *which* input mode matches your target, how to read
+the verdict, and how the fix loop is bounded. It does **not** re-explain the
+review engine itself — channels, reconciliation, the `finding_key`, the verdict
+algorithm, and `.mmr.yaml` all live in the [MMR reference](../mmr/index.md).
+Read that guide for "what is a channel"; read this one for "I have a change, now
+what do I run."
+
+:::callout{type=tip}
+**Two layers.** `mmr review` is the engine. `scaffold run review-pr` and
+`review-code` are *workflow wrappers* on top — they pick the input mode, add the
+Superpowers code-reviewer agent channel via `mmr reconcile`, handle auth
+recovery, and bound the fix loop. `post-implementation-review` is a separate,
+release-time full-codebase review with its own flow (see Step 1). This guide is
+about driving those entry points; the engine details are in
+[the MMR reference](../mmr/index.md).
+:::
+
+## Step 1 — Pick the entry point
+
+Two of these are wrappers over `mmr review` — `review-pr` and `review-code` —
+sharing the same engine and verdict semantics, differing in *scope* and *what
+they synthesize*. `post-implementation-review` is **not** a `mmr review` wrapper:
+it's an independent release-time review of the whole codebase that runs its own
+channel flow and writes its own report under `docs/reviews/`, with MMR
+reconciliation only as an optional add-on. Consult its own doc for specifics.
+
+```mermaid
+flowchart TD
+  Q{What are you reviewing?} --> A[An open PR]
+  Q --> B[Local changes
+before commit/push]
+  Q --> C[The whole codebase
+after all tasks land]
+  A --> AR["scaffold run review-pr
+(mmr review --pr N)"]
+  B --> BR["scaffold run review-code
+(synthesized delivery candidate)"]
+  C --> CR["scaffold run post-implementation-review
+(two-phase: systemic + per-story)"]
+```
+
+| Entry point | Target | Notes |
+| --- | --- | --- |
+| `scaffold run review-pr` | One PR (`--pr N`, auto-detected from the branch) | **MMR wrapper.** Adds auth checks, the Superpowers agent channel, the per-finding round bookkeeping, an opt-in Beads bridge over a bare `mmr review`. |
+| `scaffold run review-code` | Local pre-push: committed branch diff + staged + unstaged, as one synthesized "delivery candidate" | **MMR wrapper.** Adds the same agent channel + round bounding, plus file & standards context for the file-blind CLIs. **Untracked files are not covered.** |
+| `scaffold run post-implementation-review` | The full implemented codebase against stories + standards | **Independent, not an MMR wrapper.** A release-time review (systemic sweep + per-story functional review via parallel agents) with its own report under `docs/reviews/`; MMR injection is optional. Consult its own doc. |
+
+:::callout{type=note}
+**The mandatory one.** After `gh pr create`, running `review-pr` is mandatory
+before moving to the next task (a PostToolUse hook reminds you).
+`review-code` is the recommended preflight before a push but isn't gated.
+`post-implementation-review` is a release-time sweep, not a per-change gate.
+:::
+
+### When no wrapper fits
+
+The wrappers are conveniences, not gates on the engine. For any target a wrapper
+doesn't cover — a branch range, an existing patch file, a single doc — call
+`mmr review` directly with the matching input flag. The
+[MMR reference](../mmr/index.md) lists every flag; the next step is the workflow
+view of the same choice.
+
+## Step 2 — Choose the input mode
+
+`mmr review` resolves a diff from exactly one input source. Pick the one that
+describes your target. The `--diff -` (stdin) form is the universal escape hatch:
+anything you can express as a unified diff, you can pipe in.
+
+```mermaid
+flowchart TD
+  S{Where is the change?} --> PR[On a GitHub PR]
+  S --> ST[Staged in the index]
+  S --> BR[A branch, vs a base]
+  S --> DC[Local working tree:
+committed + staged + unstaged]
+  S --> UF[A brand-new file
+git doesn't track yet]
+  PR --> PRc["mmr review --pr N"]
+  ST --> STc["mmr review --staged"]
+  BR --> BRc["mmr review --base main --head BRANCH"]
+  DC --> DCc["git diff MERGE_BASE | mmr review --diff -
+(this is what review-code synthesizes)"]
+  UF --> UFc["(diff -u /dev/null FILE || true) | mmr review --diff -"]
+```
+
+| Target | Command | Notes |
+| --- | --- | --- |
+| A PR | `mmr review --pr 123` | Fetches the diff via `gh pr diff`. This is `review-pr`'s mode. |
+| Staged changes | `mmr review --staged` | Just the index (`git diff --cached`) — the pre-commit slice. |
+| A branch range | `mmr review --base main --head "$BRANCH"` | Committed work only; no staged/unstaged. |
+| Full delivery candidate | `git diff "$MERGE_BASE" \| mmr review --diff -` | Committed branch diff + staged + unstaged in one patch. `review-code` synthesizes this for you. |
+| A single tracked file's pending edits | `git diff HEAD -- path/file.ts \| mmr review --diff -` | Fails with "no diff content" if the file has no local changes — use the next row. |
+| A brand-new / untracked file | `(diff -u /dev/null path/file.ts \|\| true) \| mmr review --diff -` | Synthesizes an "all-added" diff from current contents. |
+| An existing patch | `mmr review --diff path/changes.patch` | Reads diff-format content directly. |
+
+:::callout{type=danger}
+**Untracked files are silently skipped — this is the trap.** `review-code`
+reviews the committed branch diff plus staged and unstaged changes *to tracked
+files*. A brand-new file you've never `git add`-ed is **not** in any of those
+diffs, so it sails through review with zero findings — not because it's clean,
+but because no channel ever saw it. To review a new file, pipe it in explicitly:
+`(diff -u /dev/null path/to/new-file.ts || true) | mmr review --diff -`. The
+`|| true` guard is required: `diff` exits non-zero whenever files differ, which
+would otherwise kill the pipeline under `set -o pipefail`. The wrappers cannot
+guess which untracked files you meant to include
+:cite[content/tools/review-code.md:37].
+:::
+
+The `--diff` flag expects **diff-format content** — a path to a `.patch`/`.diff`
+file, or `-` for stdin. It does not accept raw document text; wrap the target in
+a diff first.
+
+## Step 3 — Read the verdict, then act
+
+Every review collapses to exactly one of four verdicts. The verdict, not the raw
+findings, is what decides whether you proceed. The
+[MMR reference](../mmr/index.md) defines the gate, the severity tiers, and the
+exact derivation algorithm; this table is the *action* you take for each outcome.
+
+| Verdict | Exit | Do |
+| --- | --- | --- |
+| `pass` | 0 | **Proceed** — merge / push / next task. |
+| `degraded-pass` | 0 | **Proceed**, noting reduced coverage. The max achievable verdict once any channel was compensated. |
+| `blocked` | 2 | **Stop.** Fix the blocking findings (Step 4), then re-review. Do not merge. |
+| `needs-user-decision` | 3 | **Stop and surface to the user.** Automated iteration can't resolve this. |
+
+A review is `blocked` when any unacknowledged finding sits at or above the fix
+threshold (:sev[P2]{level=p2} by default; override per-run with
+`--fix-threshold`). See the [MMR reference](../mmr/index.md) for how the verdict
+is derived from gate result + channel health.
+
+:::callout{type=warning}
+**Proceed only on `pass` or `degraded-pass`.** On `blocked` or
+`needs-user-decision`, never merge automatically — surface the verdict and the
+remaining findings to the user. The wrappers enforce this: a `blocked` /
+`needs-user-decision` outcome takes the "Stop path" and does **not** print the
+ready-for-merge message :cite[content/tools/review-pr.md:610].
+:::
+
+## Step 4 — Fix the blocking findings (bounded)
+
+When the verdict is `blocked`, the loop is: fix the findings at or above the
+threshold → re-review → repeat. The guard rail is that this loop is **bounded
+per finding**, so a finding the model can't actually fix doesn't trap you in an
+infinite cycle.
+
+### The 3-round-per-finding limit
+
+The limit is **3 attempts per finding**, not 3 rounds total. Each round that
+surfaces *genuinely new* findings is healthy iteration — keep going. The loop
+stops only when one specific finding has been attempted three times without
+resolution.
+
+A "finding" here is its **stable identity**, not its wording, so a re-worded
+report of the same defect still counts against the same finding. (The
+[MMR reference](../mmr/index.md) covers how that identity is computed.) Co-equal
+stop conditions:
+
+- A finding's identity reaches 3 recorded attempts.
+- The same underlying defect recurs across 3 rounds even if the reviewer's
+  wording produces a new identity each time.
+- Channels genuinely contradict each other (→ `needs-user-decision`).
+- The user explicitly asks to stop.
+
+When you stop, **do not merge**. Document each unresolved finding (severity,
+location, attempt count) and hand the decision to the user
+:cite[content/tools/review-pr.md:610].
+
+### Where the bookkeeping lives today
+
+The engine ships **native** multi-round sessions — `mmr review --session <id>
+--round N --max-rounds M` :cite[packages/mmr/src/commands/review.ts:289] — and a
+stable, line-number-independent `finding_key`
+:cite[packages/mmr/src/core/stable-id.ts:115]. (See the
+[MMR reference](../mmr/index.md) for how that key collapses the same issue at
+different severities.)
+
+The scaffold **wrappers** have not yet migrated to native sessions. Until they
+do, `review-pr` and `review-code` enforce the 3-strike rule with their own
+bookkeeping: a per-session attempts file at
+`.scaffold/review-attempts/<session-id>.json`. Each fix round computes a hash
+over the same four identity components, increments that finding's counter, and
+the `_review_at_strike_limit` helper blocks once it hits 3
+:cite[content/tools/review-pr.md:468]. The wrapper hash deliberately mirrors the
+engine's `finding_key` components, so the eventual swap to
+`mmr review --session` is a clean migration rather than a re-think.
+
+:::callout{type=note}
+**Practical takeaway.** You drive the fix loop through the wrapper; the attempts
+file under `.scaffold/review-attempts/` is the current source of truth for the
+strike count. For a very noisy loop you may narrow the gate for one run with
+`--fix-threshold P1` — but don't permanently lower the project default (P2).
+:::
+
+## Step 5 — Handle degraded mode
+
+A review never silently runs with fewer reviewers. A channel is *degraded* when
+its binary isn't installed, auth fails, it times out, or it errors out. The
+workflow's response is to **compensate and tell you how to recover**, then cap
+the verdict at `degraded-pass`. The mechanics — how compensation runs and the
+per-channel auth checks — live in the [MMR reference](../mmr/index.md); below is
+what it means for *your* workflow.
+
+- **Compensating pass.** For each degraded *external* channel, MMR runs a
+  compensating pass focused on that channel's strength area and records the
+  source as `compensating-<channel>` :cite[packages/mmr/src/core/compensator.ts:162].
+  The compensator defaults to `claude -p` unless `defaults.compensator.channel`
+  overrides it :cite[packages/mmr/src/core/compensator.ts:74]. These findings
+  are single-source, low confidence. With the default compensator, a missing
+  Claude CLI has no compensator of its own. (The bracket labels like
+  `[compensating: Grok-equivalent]` you'll see are the *manual fallback* summary
+  wording, distinct from the engine's `compensating-<channel>` source name.)
+- **Auth recovery is never silent.** The workflow surfaces the exact recovery
+  command for the failed channel; the channel's `recovery` string drives this
+  :cite[packages/mmr/src/core/auth.ts:65]. See the
+  [MMR reference](../mmr/index.md) for the per-channel auth-check + recovery
+  table.
+
+:::callout{type=warning}
+**Foreground only.** When the `mmr` CLI is unavailable and a wrapper falls back
+to invoking Codex / Gemini / Claude / Grok directly, run them as **foreground**
+Bash calls — never with `run_in_background`, `&`, or `nohup`. Background
+execution produces empty output, which the parser then reads as a degraded
+channel :cite[content/tools/review-code.md:265].
+:::
+
+Once any channel was compensated, the best possible verdict is
+`degraded-pass` — full `pass` requires all channels to have completed for real.
+
+## See also
+
+- [MMR reference](../mmr/index.md){mode=advisory} — channels, reconciliation,
+  the `finding_key`, verdict internals, and `.mmr.yaml`.
+- The wrapper meta-prompts themselves:
+  :cite[content/tools/review-pr.md:15]{mode=advisory},
+  :cite[content/tools/review-code.md:16]{mode=advisory}, and
+  :cite[content/tools/post-implementation-review.md:16]{mode=advisory}.

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.

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

@@ -2,6 +2,12 @@
 name: backend-fintech-testing
 description: Deterministic backtests; financial-accuracy tests; broker sandbox testing; regulatory edge-case coverage.
 topics: [backend, fintech, testing, determinism, backtesting, sandbox, accuracy, property-based]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.pact.io/
+  - url: https://martinfowler.com/articles/practical-test-pyramid.html
 ---
 
 Fintech tests have unusual requirements: bit-exact numeric accuracy, full determinism across runs and hosts, rich regulatory edge-case coverage, and realistic multi-session flows that span market-hours boundaries. A flakey fintech test is worse than no test — it hides the exact race conditions that cause real money to move incorrectly. This doc covers the patterns that keep backtests reproducible, numeric tests honest, broker integrations verifiable, and regulatory behavior exercised before it becomes an incident.

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

@@ -2,6 +2,13 @@
 name: backend-observability
 description: Structured logging, distributed tracing, RED method metrics, SLO-based alerting, and operational dashboards
 topics: [backend, observability, logging, tracing, metrics, alerting, opentelemetry, slo]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://opentelemetry.io/docs/
+  - url: https://sre.google/sre-book/service-level-objectives/
+  - url: https://sre.google/sre-book/monitoring-distributed-systems/
 ---
 
 Observability is the ability to answer arbitrary questions about a system's behavior using its outputs alone — without deploying new code. Investing in structured logging, distributed tracing, and SLO-based alerting before the first incident makes the difference between a 5-minute diagnosis and a 5-hour outage.

package/content/knowledge/backend/backend-project-structure.md

@@ -2,6 +2,12 @@
 name: backend-project-structure
 description: Canonical directory layout for backend services — routes/controllers, services, models/repositories, middleware, utils, config resolution, and dependency injection patterns
 topics: [backend, project-structure, architecture, dependency-injection, layers]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://martinfowler.com/eaaCatalog/
+  - url: https://martinfowler.com/articles/injection.html
 ---
 
 A well-organized backend project is readable to a new engineer in minutes. The directory layout should communicate the architecture: which layer owns which responsibility, where to add a new feature, and where to find any piece of behavior. The most common structural failure is mixing concerns — business logic in controllers, database calls in services, HTTP parsing in repositories. Enforce boundaries through structure first, tooling second.

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

@@ -2,6 +2,12 @@
 name: backend-requirements
 description: API-first design principles, SLA requirements (latency p99, uptime, throughput), scalability targets, backwards compatibility commitments, and API versioning strategy
 topics: [backend, requirements, sla, api, versioning, scalability, performance]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://spec.openapis.org/oas/latest.html
+  - url: https://sre.google/sre-book/service-level-objectives/
 ---
 
 Backend requirements are the contract the service makes with its consumers — other teams, external developers, and end users. Setting explicit SLAs, versioning policies, and scalability targets before any code is written eliminates the most expensive class of late-breaking architectural changes. A backend that surprises its callers with latency spikes or breaking changes destroys trust and creates cascading toil.

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

@@ -2,6 +2,13 @@
 name: backend-security
 description: Input validation, SQL injection prevention, rate limiting, OWASP API Security Top 10, secrets management, and dependency auditing
 topics: [backend, security, validation, sql-injection, rate-limiting, owasp, secrets]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://owasp.org/www-project-api-security/
+  - url: https://owasp.org/www-project-top-ten/
+  - url: https://owasp.org/www-project-cheat-sheets/
 ---
 
 Security vulnerabilities in backend services are disproportionately expensive to fix after launch — building in input validation, injection prevention, rate limiting, and secrets hygiene from the start is always cheaper than retrofitting them under pressure after a breach.

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

@@ -2,6 +2,13 @@
 name: backend-testing
 description: API integration tests, contract testing, database testing patterns, mocking external services, and load testing
 topics: [backend, testing, integration-tests, contract-testing, database-testing, mocking, load-testing]
+volatility: stable
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://docs.pact.io/
+  - url: https://martinfowler.com/articles/practical-test-pyramid.html
+  - url: https://martinfowler.com/bliki/ContractTest.html
 ---
 
 Backend testing strategy determines how much confidence you have before every deploy — a well-layered test suite catches regressions at the fastest possible feedback loop while still exercising the real data layer and honoring API contracts with consumers.

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

@@ -2,6 +2,12 @@
 name: backend-worker-patterns
 description: Background job frameworks, cron scheduling, event consumers, dead letter queues, retry strategies, and graceful shutdown for workers
 topics: [backend, workers, bullmq, celery, temporal, cron, background-jobs, dlq]
+volatility: evolving
+last-reviewed: null
+version-pin: null
+sources:
+  - url: https://microservices.io/patterns/data/transactional-outbox.html
+  - url: https://sre.google/sre-book/handling-overload/
 ---
 
 Background workers offload time-consuming and deferred work from the request path, but they introduce their own failure modes — jobs that silently vanish, duplicate executions, and unclean shutdowns during deploys all require deliberate design to prevent.

package/content/knowledge/browser-extension/browser-extension-architecture.md

@@ -2,6 +2,12 @@
 name: browser-extension-architecture
 description: Component isolation across content scripts, background service workers, and popup pages; message passing patterns; and state synchronization strategies
 topics: [browser-extension, architecture, message-passing, state-synchronization, service-worker, content-scripts]
+volatility: evolving
+last-reviewed: null
+version-pin: 'Manifest V3'
+sources:
+  - url: https://developer.chrome.com/docs/extensions/mv3/architecture-overview
+  - url: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension
 ---
 
 Browser extension architecture is fundamentally different from web app architecture because the application is split across multiple isolated execution environments that cannot share memory directly. Content scripts run inside host pages but in an isolated JavaScript world. Service workers run in a separate context that is terminated and re-created between events. Popup pages are ephemeral — they exist only while the popup is open. These constraints drive every architectural decision: communication is via message passing, state must be externalized to `chrome.storage`, and every component must tolerate being initialized from scratch at any time.

package/content/knowledge/browser-extension/browser-extension-content-scripts.md

@@ -2,6 +2,12 @@
 name: browser-extension-content-scripts
 description: DOM manipulation from content scripts, isolated worlds, CSS injection, and communicating with the host page via postMessage
 topics: [browser-extension, content-scripts, dom-manipulation, isolated-worlds, css-injection, postmessage]
+volatility: fast-moving
+last-reviewed: null
+version-pin: 'Manifest V3'
+sources:
+  - url: https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts
+  - url: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts
 ---
 
 Content scripts are the extension's interface with the web page. They run inside the page's DOM but in an isolated JavaScript world — they see the same HTML and can manipulate the same elements, but they cannot access the page's JavaScript variables or prototype chain without explicitly crossing the world boundary. Understanding this isolation is essential for writing content scripts that are both functional and secure.