forgecraft-mcp 1.4.0 → 1.7.0

package/templates/data-pipeline/structure.yaml

@@ -1,23 +1,23 @@
-tag: DATA-PIPELINE
-section: structure
-entries:
-  - path: dags/
-    description: "Pipeline orchestration definitions (Airflow DAGs, Prefect flows, Dagster jobs)"
-  - path: src/extractors/
-    description: "Data source connectors: API, database, file extractors"
-  - path: src/transformers/
-    description: "Data transformation logic: cleaning, enrichment, aggregation"
-  - path: src/loaders/
-    description: "Data sinks: warehouse loaders, file writers, API publishers"
-  - path: src/validators/
-    description: "Data quality checks: schema validation, business rules, anomaly detection"
-  - path: src/config/
-    description: "Pipeline configuration: sources, schedules, thresholds (YAML)"
-  - path: tests/
-    description: "Unit tests for transformers, validators, and business logic"
-  - path: tests/fixtures/
-    description: "Sample data files for deterministic testing"
-  - path: sql/
-    description: "SQL transformations and DDL for warehouse tables"
-  - path: scripts/
-    description: "Operational scripts: backfill, reprocess, data repair"
+tag: DATA-PIPELINE
+section: structure
+entries:
+  - path: dags/
+    description: "Pipeline orchestration definitions (Airflow DAGs, Prefect flows, Dagster jobs)"
+  - path: src/extractors/
+    description: "Data source connectors: API, database, file extractors"
+  - path: src/transformers/
+    description: "Data transformation logic: cleaning, enrichment, aggregation"
+  - path: src/loaders/
+    description: "Data sinks: warehouse loaders, file writers, API publishers"
+  - path: src/validators/
+    description: "Data quality checks: schema validation, business rules, anomaly detection"
+  - path: src/config/
+    description: "Pipeline configuration: sources, schedules, thresholds (YAML)"
+  - path: tests/
+    description: "Unit tests for transformers, validators, and business logic"
+  - path: tests/fixtures/
+    description: "Sample data files for deterministic testing"
+  - path: sql/
+    description: "SQL transformations and DDL for warehouse tables"
+  - path: scripts/
+    description: "Operational scripts: backfill, reprocess, data repair"

package/templates/docs-manifest.yaml

@@ -0,0 +1,227 @@
+# docs-manifest.yaml — canonical schema for the GS document taxonomy
+#
+# This file is the SINGLE SOURCE OF TRUTH for the document layout that all
+# Pragmaworks GS-aware tools (forgecraft, chronicle, chronicle-team) honor.
+# Projects do NOT copy this file. They write their own ./docs/manifest.yaml
+# which references this canonical schema and overrides paths where needed.
+#
+# Canonical location:
+#   github.com/jghiringhelli/forgecraft-mcp/templates/docs-manifest.yaml
+#   (also reachable via the forgecraft npm package)
+#
+# A project's docs/manifest.yaml LOOKS LIKE:
+#
+#     schema_source: forgecraft@1.5.0/templates/docs-manifest.yaml
+#     project:
+#       name: my-app
+#       type: api
+#     overrides:
+#       documents.specs.path: docs/product/      # legacy layout, mapped in
+#       documents.use_cases.path: docs/uc/
+#
+# Tools resolve paths in this order:
+#   1. project's docs/manifest.yaml `overrides:` block (highest priority)
+#   2. project's docs/manifest.yaml top-level fields
+#   3. this canonical schema's defaults
+#
+# That is what "back-compat" means here: the canonical layout is the default;
+# legacy projects map their existing files into the schema via overrides.
+
+version: 1
+
+# ── Project metadata ─────────────────────────────────────────────────────
+project:
+  name: <required>           # human-readable project name
+  type: <required>           # library | cli | api | service | app | tool
+  release_phase: greenfield  # greenfield | brownfield | maintenance
+
+# ── Document types and their canonical locations ─────────────────────────
+# Each entry defines:
+#   path        — where files live (or active_path/done_path for archived types)
+#   pattern     — glob applied for discovery
+#   required_on — conventional-commit types that MUST touch a file in this slot
+#   archive_when (optional) — when files move from active_path to done_path
+documents:
+
+  # SPECS — what we are building (product/use-case-driven specs)
+  specs:
+    path: docs/specs/
+    pattern: "*.md"
+    required_on: [feat, refactor]
+    description: >
+      Product-level specs. One per feature or major capability.
+      Answers: what does the user do, what outcome do they want, what is in/out of scope?
+
+  # ADRs — architectural decision records (how we build, with rationale)
+  adrs:
+    active_path: docs/adrs/active/
+    done_path: docs/adrs/done/
+    pattern: "ADR-*.md"
+    required_on: []          # encouraged on feat/refactor when a decision is made
+    archive_when: superseded
+    description: >
+      Architectural Decision Records. One file per decision (e.g. ADR-0007-pick-postgres.md).
+      Active = currently in force. Done = superseded or rolled back, kept for history.
+
+  # USE CASES — actor + action + outcome (executable scenarios)
+  use_cases:
+    path: docs/use-cases/
+    pattern: "UC-*.md"
+    required_on: [feat]
+    description: >
+      Executable use cases. Each one: actor, preconditions, steps, expected outcome.
+      These bind specs to harness/tests.
+
+  # ROADMAPS — planned/active/done work items
+  roadmaps:
+    active_path: docs/roadmaps/active/
+    done_path: docs/roadmaps/done/
+    pattern: "RM-*.md"
+    required_on: []          # roadmap items are pulled from tickets/issues, not commits
+    archive_when: implemented
+    description: >
+      Roadmap items. One file per planned chunk of work (e.g. RM-0042-add-oauth.md).
+      Active = open. Done = shipped (kept for history and changelog generation).
+
+  # SCHEMAS — diagrams, data schemas, API schemas
+  schemas:
+    path: docs/schemas/
+    pattern: "*.{md,mmd,json,yaml}"
+    required_on: [feat]
+    description: >
+      Mermaid diagrams (.mmd or fenced .md), JSON Schema, OpenAPI specs, ER diagrams.
+      Required when data model or API surface changes.
+
+  # DECISIONS — lightweight bug-fix or operational decisions
+  decisions:
+    path: docs/decisions/
+    pattern: "*.md"
+    required_on: []          # optional even on fix; encouraged when behavior is intentionally redefined
+    scaffolded_by: generate_decision   # forgecraft tool that emits the post-mortem stub
+    description: >
+      One-pager rationale for non-architectural decisions: bug-fix interpretations,
+      operational tweaks, "we chose X over Y because Z" notes that don't warrant a full ADR.
+      Filename pattern: YYYY-MM-DD-slug.md.
+      Use forgecraft `generate_decision` (or change_request with type=bug-postmortem)
+      to scaffold a stub with Trigger / Root cause / Fix / Regression test / Chronicle link.
+
+  # CONTRACTS — behavioral contracts (what the system promises)
+  contracts:
+    path: docs/contracts/
+    pattern: "*.{md,yaml}"
+    required_on: []
+    description: >
+      Behavioral contracts. NFRs, SLOs, API contracts, error semantics.
+      Often referenced from specs and ADRs.
+
+  # SESSION PROMPTS — bound to roadmap items (forgecraft + chronicle convention)
+  session_prompts:
+    path: docs/session-prompts/
+    pattern: "RM-*.md"
+    required_on: []
+    description: >
+      Per-roadmap-item prompts that drive AI sessions. One per RM-* item.
+      Generated by forgecraft propose_session, executed by chronicle.
+
+# ── Cascade rules — which commit types require which doc updates ─────────
+# These are enforced by:
+#   - .claude/hooks/pre-commit-doc-cascade.sh (local, advisory)
+#   - .github/workflows/validate-pr.yml       (CI, blocking when severity=error)
+#
+# Severity:
+#   error    — blocks commit/PR
+#   warning  — emits a notice; does not block
+#   info     — logs only
+cascade:
+  feat:
+    required: [specs]
+    encouraged: [use_cases, schemas, adrs]
+    severity: warning            # bump to error once a project's baseline is clean
+
+  fix:
+    required: []                 # no doc requirement; regression test is mandatory (see human_judgment)
+    encouraged: [decisions]
+    require_regression_test: true
+    severity: warning
+
+  refactor:
+    required: []
+    encouraged: [adrs, decisions]
+    severity: info
+
+  perf:
+    required: []
+    encouraged: [decisions, schemas]
+    severity: info
+
+  docs:
+    required: []
+    encouraged: []
+    severity: info
+
+  test:
+    required: []
+    encouraged: []
+    severity: info
+
+  chore:
+    required: []
+    encouraged: []
+    severity: info
+
+  ci:
+    required: []
+    encouraged: []
+    severity: info
+
+  revert:
+    required: []
+    encouraged: [decisions]
+    severity: info
+
+# ── Anti-drift — public API surface enforcement ─────────────────────────
+# When the public surface changes (exports, public types, CLI flags, MCP tool
+# schemas), a spec or ADR touch is required regardless of commit type.
+api_surface:
+  detect:
+    typescript:
+      exports_glob: "src/**/index.ts"
+      public_types_glob: "src/types/**/*.ts"
+    cli:
+      flags_glob: "src/cli/**/*.ts"
+    mcp:
+      tools_glob: "src/tools/**/*.ts"
+  on_change_require: [specs, adrs]
+  severity: warning
+
+# ── Human-judgment gate — "no untested or unreviewed code to prod" ──────
+human_judgment:
+  protected_branches: [main, develop]
+  require_review: true
+  min_reviewers: 1               # set 0 for solo mode (still requires PR + checks)
+  require_tests_pass: true       # CI must show tests green
+  require_human_ack: true        # at least one human comment/approval on the PR
+  block_ai_only_merge: true      # disallow merge when only the PR author has interacted
+
+# ── Recording layers — three-tier memory contract ───────────────────────
+# This block is informational. It documents how project / individual / team
+# memory split across tools, so each tool knows its lane.
+recording:
+  project:
+    owner: forgecraft
+    surface: docs/* + .forgecraft/* + .claude/hooks/*
+    scope: cascade docs, gates, hooks, harness contracts
+  individual:
+    owner: chronicle
+    surface: ~/.chronicle/ (per-user memory store)
+    scope: prompt history, decisions, findings, developer habits, work style
+  team:
+    owner: chronicle-team
+    surface: shared DB (Railway) + dashboard
+    scope: shared memory, prompt analytics, ticket integration, workload split (axon)
+
+# ── Brownfield ingestion settings ───────────────────────────────────────
+brownfield:
+  scanner: pragmaworks-cli       # external tool, not embedded
+  override_file: docs/manifest.yaml    # generated/edited during ingestion
+  report_path: reports/brownfield-audit.md

package/templates/fintech/hooks.yaml

@@ -1,55 +1,55 @@
-tag: FINTECH
-section: hooks
-hooks:
-  - name: vol-unit-convention
-    trigger: pre-commit
-    description: "Block double-scaling of volatility fields already stored as percentage-per-period"
-    filename: pre-commit-vol-units.sh
-    script: |
-      #!/bin/bash
-      # Volatility unit confusion is the single most common source of false crash triggers
-      # and missed recovery conditions in financial simulations.
-      #
-      # This hook catches the two double-scaling patterns:
-      #   / sqrt(N)  applied to a field already stored as percentage-per-period
-      #   * 100      applied to a field already stored as percentage-per-period
-      #
-      # CUSTOMIZE: replace VOL_FIELD_PATTERNS with the actual field names used in
-      # this codebase (e.g. vol_pct_per_day, sigma_stored, realised_vol_pct).
-      # The generic pattern below catches common naming conventions.
-      #
-      # Label: customize VOL_FIELD_PATTERNS for this project's field names.
-
-      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|ts|tsx|js|jsx|go|rs)$')
-      if [ -z "$STAGED" ]; then exit 0; fi
-
-      # Generic vol field patterns — override with project-specific names
-      VOL_FIELD_PATTERNS="vol_pct|sigma_pct|realized_vol|implied_vol|vol_stored|pct_vol|annualized_vol"
-
-      VIOLATIONS=0
-
-      for file in $STAGED; do
-        # Pattern 1: double sqrt-annualization on a _pct / stored vol field
-        if grep -nE "($VOL_FIELD_PATTERNS).*/ ?sqrt\(|sqrt\(.*\).*($VOL_FIELD_PATTERNS)" "$file" 2>/dev/null | grep -v "^[[:space:]]*//" | grep -q .; then
-          echo "  ❌ $file — possible double sqrt-scaling on a percentage-per-period vol field"
-          echo "     Vol fields stored as pct-per-period must not be divided by sqrt(N) again."
-          grep -nE "($VOL_FIELD_PATTERNS).*/ ?sqrt\(|sqrt\(.*\).*($VOL_FIELD_PATTERNS)" "$file" | grep -v "^[[:space:]]*//"
-          VIOLATIONS=$((VIOLATIONS + 1))
-        fi
-
-        # Pattern 2: *100 on a field already stored as percentage
-        if grep -nE "($VOL_FIELD_PATTERNS).*\* ?100[^.]|[^.]100 ?\* ?.*($VOL_FIELD_PATTERNS)" "$file" 2>/dev/null | grep -v "^[[:space:]]*//" | grep -q .; then
-          echo "  ❌ $file — possible *100 rescaling on a percentage-per-period vol field"
-          echo "     Vol fields stored as pct-per-period must not be multiplied by 100 again."
-          grep -nE "($VOL_FIELD_PATTERNS).*\* ?100[^.]|[^.]100 ?\* ?.*($VOL_FIELD_PATTERNS)" "$file" | grep -v "^[[:space:]]*//"
-          VIOLATIONS=$((VIOLATIONS + 1))
-        fi
-      done
-
-      if [ $VIOLATIONS -gt 0 ]; then
-        echo ""
-        echo "❌ Vol unit convention violation(s) found."
-        echo "   Check that the field is stored as a raw ratio (0.03 = 3%), not already as percentage."
-        echo "   To suppress a false positive: add a comment '# vol-unit: raw-ratio' on the same line."
-        exit 1
-      fi
+tag: FINTECH
+section: hooks
+hooks:
+  - name: vol-unit-convention
+    trigger: pre-commit
+    description: "Block double-scaling of volatility fields already stored as percentage-per-period"
+    filename: pre-commit-vol-units.sh
+    script: |
+      #!/bin/bash
+      # Volatility unit confusion is the single most common source of false crash triggers
+      # and missed recovery conditions in financial simulations.
+      #
+      # This hook catches the two double-scaling patterns:
+      #   / sqrt(N)  applied to a field already stored as percentage-per-period
+      #   * 100      applied to a field already stored as percentage-per-period
+      #
+      # CUSTOMIZE: replace VOL_FIELD_PATTERNS with the actual field names used in
+      # this codebase (e.g. vol_pct_per_day, sigma_stored, realised_vol_pct).
+      # The generic pattern below catches common naming conventions.
+      #
+      # Label: customize VOL_FIELD_PATTERNS for this project's field names.
+
+      STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|ts|tsx|js|jsx|go|rs)$')
+      if [ -z "$STAGED" ]; then exit 0; fi
+
+      # Generic vol field patterns — override with project-specific names
+      VOL_FIELD_PATTERNS="vol_pct|sigma_pct|realized_vol|implied_vol|vol_stored|pct_vol|annualized_vol"
+
+      VIOLATIONS=0
+
+      for file in $STAGED; do
+        # Pattern 1: double sqrt-annualization on a _pct / stored vol field
+        if grep -nE "($VOL_FIELD_PATTERNS).*/ ?sqrt\(|sqrt\(.*\).*($VOL_FIELD_PATTERNS)" "$file" 2>/dev/null | grep -v "^[[:space:]]*//" | grep -q .; then
+          echo "  ❌ $file — possible double sqrt-scaling on a percentage-per-period vol field"
+          echo "     Vol fields stored as pct-per-period must not be divided by sqrt(N) again."
+          grep -nE "($VOL_FIELD_PATTERNS).*/ ?sqrt\(|sqrt\(.*\).*($VOL_FIELD_PATTERNS)" "$file" | grep -v "^[[:space:]]*//"
+          VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+
+        # Pattern 2: *100 on a field already stored as percentage
+        if grep -nE "($VOL_FIELD_PATTERNS).*\* ?100[^.]|[^.]100 ?\* ?.*($VOL_FIELD_PATTERNS)" "$file" 2>/dev/null | grep -v "^[[:space:]]*//" | grep -q .; then
+          echo "  ❌ $file — possible *100 rescaling on a percentage-per-period vol field"
+          echo "     Vol fields stored as pct-per-period must not be multiplied by 100 again."
+          grep -nE "($VOL_FIELD_PATTERNS).*\* ?100[^.]|[^.]100 ?\* ?.*($VOL_FIELD_PATTERNS)" "$file" | grep -v "^[[:space:]]*//"
+          VIOLATIONS=$((VIOLATIONS + 1))
+        fi
+      done
+
+      if [ $VIOLATIONS -gt 0 ]; then
+        echo ""
+        echo "❌ Vol unit convention violation(s) found."
+        echo "   Check that the field is stored as a raw ratio (0.03 = 3%), not already as percentage."
+        echo "   To suppress a false positive: add a comment '# vol-unit: raw-ratio' on the same line."
+        exit 1
+      fi

package/templates/fintech/instructions.yaml

@@ -1,112 +1,112 @@
-tag: FINTECH
-section: instructions
-blocks:
-  - id: transaction-integrity
-    tier: recommended
-    title: "Transaction Integrity & Data Precision"
-    content: |
-      ## Transaction Integrity & Financial Data Precision
-
-      - Never use floating-point types for monetary values. Use fixed-precision decimal types (e.g., `Decimal`, `BigDecimal`, `NUMERIC(19,4)`) or integer minor units (cents/pips) throughout the entire stack.
-      - Ensure all financial operations are ACID-compliant. Use database transactions with appropriate isolation levels (at minimum READ COMMITTED; use SERIALIZABLE for balance mutations).
-      - Implement double-entry bookkeeping: every transaction creates at least two ledger entries (debit and credit) that sum to zero. Validate this invariant on every write.
-      - Make all transaction processing idempotent using client-supplied idempotency keys. Retry-safe APIs prevent duplicate charges or transfers.
-      - Record immutable transaction history. Financial records are append-only; corrections are modeled as reversing entries, never as in-place updates or deletes.
-      - Perform end-of-day reconciliation between internal ledgers and external payment processor/bank records. Alert immediately on any discrepancy.
-      - Store and display all monetary amounts with their ISO 4217 currency code. Never assume a default currency.
-
-  - id: audit-compliance
-    tier: recommended
-    title: "Audit Trails & Regulatory Compliance"
-    content: |
-      ## Audit Trails & Regulatory Compliance
-
-      - Maintain a tamper-evident, append-only audit log for every state change to accounts, transactions, and user permissions. Include actor, timestamp, old value, new value, and IP address.
-      - Implement PCI-DSS controls if handling cardholder data: network segmentation, encryption, access logging, vulnerability scanning, and annual compliance assessments.
-      - Mask or tokenize sensitive financial identifiers (account numbers, SSNs, card PANs) in logs, error messages, and non-production environments.
-      - Enforce KYC/AML checks at onboarding and on an ongoing basis. Integrate with identity verification and sanctions screening providers via well-defined service boundaries.
-      - Retain financial records and audit logs for the period required by applicable regulations (typically 5-7 years). Automate archival and ensure archived data remains queryable for audits.
-      - Design for regulatory reporting: build data models and pipelines that can produce required reports (SAR, CTR, regulatory filings) with minimal manual intervention.
-
-  - id: security-resilience
-    tier: recommended
-    title: "Security & Operational Resilience"
-    content: |
-      ## Security & Operational Resilience
-
-      - Implement multi-factor authentication for all user-facing financial operations above a configurable threshold (e.g., transfers > $500).
-      - Apply velocity checks and fraud detection rules: flag unusual transaction volumes, amounts, geographies, or timing patterns for review before processing.
-      - Use cryptographic signing (HMAC or asymmetric signatures) for all webhook payloads, inter-service financial messages, and API requests to prevent tampering.
-      - Design for graceful degradation: if an external payment provider is unavailable, queue transactions for retry rather than failing the user experience entirely.
-      - Maintain a disaster recovery plan with RPO < 1 hour and RTO < 4 hours for critical financial services. Test failover procedures quarterly.
-      - Separate read and write paths for high-throughput systems. Use CQRS to ensure reporting queries never contend with transaction processing.
-
-  - id: simulation-invariants
-    tier: recommended
-    title: "Financial Simulation & Backtesting Invariants"
-    content: |
-      ## Financial Simulation & Backtesting Invariants
-
-      Financial simulations fail in two directions, both silently. Name them explicitly
-      so every engineer on the team recognizes the pattern immediately.
-
-      ### Category A — Silent Loss Bugs (strategy runs, earns nothing)
-
-      These bugs produce flat or zero P&L while the simulation completes without error.
-      The strategy appears to have run. It did not.
-
-      **1. P&L decomposition invariant**
-      At finalize: `fee_income + price_income == total_pnl ± 1%`.
-      A gap larger than 1% means an accounting component is unlinked — it exists
-      in the ledger but never flows into the reported total.
-
-      **2. Fee-time ratio**
-      Fees must be proportional to active simulation time. Near-zero fees after
-      1000 hours of "running" means the instrument was never created. The strategy
-      ran against nothing. Check: `total_fees / active_hours < threshold` → flag.
-
-      **3. State concentration**
-      If >80% of simulation time is spent in a single non-productive state
-      (e.g. `crash_short`, `emergency`, `waiting`), the state machine is stuck.
-      A stuck machine is not a conservative strategy — it is a broken one.
-      Surface this in finalize as a warning, not a footnote.
-
-      ### Category B — Silent Gain Bugs (inflated returns from accounting errors)
-
-      These bugs produce plausible-looking positive returns. They are harder to catch
-      because the output looks like a win.
-
-      **4. Return plausibility**
-      For a market-neutral strategy: annual return >200% or `total_pnl / fee_income >10×`
-      is almost certainly a bug, not alpha. Fee income is ground truth of actual activity.
-      A strategy that earns 10× its fees in price income has a broken hedge or look-ahead leak.
-
-      **5. Delta neutrality**
-      Track `avg |net_delta|` while in the primary running state.
-      High average delta = the hedge is broken, bootstrapped incorrectly, or bypassed.
-      This check surfaces bootstrap order bugs that only appear mid-simulation.
-
-      **6. Instrument balance**
-      Sub-strategies should be sized proportionally per the allocation spec.
-      If one instrument is 5× larger than another at finalize, allocation logic failed.
-      Check: `max(instrument_notionals) / min(instrument_notionals) > 3× → warn`.
-
-      ### Integration requirements
-
-      - All 6 checks run in the harness `finalize()` step, printing alongside standard metrics.
-      - Failed invariants logged as `[INVARIANT FAIL]` — not swallowed as warnings.
-      - Checks are parameterized: thresholds in config, not hardcoded.
-      - All 6 checks have unit tests with synthetic data that triggers each failure mode.
-
-      ### Volatility unit convention
-
-      Unit confusion in vol calculations is the single most common source of both false crash
-      triggers and missed recovery conditions in DeFi and market-neutral strategies.
-
-      - Vol fields stored as `percentage_per_period` must never be re-transformed with
-        `/ sqrt(N)` or `* 100` after storage. Storing already-scaled vol and scaling again
-        = off by 10×–100× with no runtime error.
-      - Label every vol field with its unit in the variable name or type alias:
-        `vol_pct_per_day`, `sigma_annual` — never just `vol` or `sigma`.
-      - Annualization convention must be a named constant: `TRADING_DAYS_PER_YEAR = 252`
-        (or 365, or actual — choose one, name it, use it everywhere).
+tag: FINTECH
+section: instructions
+blocks:
+  - id: transaction-integrity
+    tier: recommended
+    title: "Transaction Integrity & Data Precision"
+    content: |
+      ## Transaction Integrity & Financial Data Precision
+
+      - Never use floating-point types for monetary values. Use fixed-precision decimal types (e.g., `Decimal`, `BigDecimal`, `NUMERIC(19,4)`) or integer minor units (cents/pips) throughout the entire stack.
+      - Ensure all financial operations are ACID-compliant. Use database transactions with appropriate isolation levels (at minimum READ COMMITTED; use SERIALIZABLE for balance mutations).
+      - Implement double-entry bookkeeping: every transaction creates at least two ledger entries (debit and credit) that sum to zero. Validate this invariant on every write.
+      - Make all transaction processing idempotent using client-supplied idempotency keys. Retry-safe APIs prevent duplicate charges or transfers.
+      - Record immutable transaction history. Financial records are append-only; corrections are modeled as reversing entries, never as in-place updates or deletes.
+      - Perform end-of-day reconciliation between internal ledgers and external payment processor/bank records. Alert immediately on any discrepancy.
+      - Store and display all monetary amounts with their ISO 4217 currency code. Never assume a default currency.
+
+  - id: audit-compliance
+    tier: recommended
+    title: "Audit Trails & Regulatory Compliance"
+    content: |
+      ## Audit Trails & Regulatory Compliance
+
+      - Maintain a tamper-evident, append-only audit log for every state change to accounts, transactions, and user permissions. Include actor, timestamp, old value, new value, and IP address.
+      - Implement PCI-DSS controls if handling cardholder data: network segmentation, encryption, access logging, vulnerability scanning, and annual compliance assessments.
+      - Mask or tokenize sensitive financial identifiers (account numbers, SSNs, card PANs) in logs, error messages, and non-production environments.
+      - Enforce KYC/AML checks at onboarding and on an ongoing basis. Integrate with identity verification and sanctions screening providers via well-defined service boundaries.
+      - Retain financial records and audit logs for the period required by applicable regulations (typically 5-7 years). Automate archival and ensure archived data remains queryable for audits.
+      - Design for regulatory reporting: build data models and pipelines that can produce required reports (SAR, CTR, regulatory filings) with minimal manual intervention.
+
+  - id: security-resilience
+    tier: recommended
+    title: "Security & Operational Resilience"
+    content: |
+      ## Security & Operational Resilience
+
+      - Implement multi-factor authentication for all user-facing financial operations above a configurable threshold (e.g., transfers > $500).
+      - Apply velocity checks and fraud detection rules: flag unusual transaction volumes, amounts, geographies, or timing patterns for review before processing.
+      - Use cryptographic signing (HMAC or asymmetric signatures) for all webhook payloads, inter-service financial messages, and API requests to prevent tampering.
+      - Design for graceful degradation: if an external payment provider is unavailable, queue transactions for retry rather than failing the user experience entirely.
+      - Maintain a disaster recovery plan with RPO < 1 hour and RTO < 4 hours for critical financial services. Test failover procedures quarterly.
+      - Separate read and write paths for high-throughput systems. Use CQRS to ensure reporting queries never contend with transaction processing.
+
+  - id: simulation-invariants
+    tier: recommended
+    title: "Financial Simulation & Backtesting Invariants"
+    content: |
+      ## Financial Simulation & Backtesting Invariants
+
+      Financial simulations fail in two directions, both silently. Name them explicitly
+      so every engineer on the team recognizes the pattern immediately.
+
+      ### Category A — Silent Loss Bugs (strategy runs, earns nothing)
+
+      These bugs produce flat or zero P&L while the simulation completes without error.
+      The strategy appears to have run. It did not.
+
+      **1. P&L decomposition invariant**
+      At finalize: `fee_income + price_income == total_pnl ± 1%`.
+      A gap larger than 1% means an accounting component is unlinked — it exists
+      in the ledger but never flows into the reported total.
+
+      **2. Fee-time ratio**
+      Fees must be proportional to active simulation time. Near-zero fees after
+      1000 hours of "running" means the instrument was never created. The strategy
+      ran against nothing. Check: `total_fees / active_hours < threshold` → flag.
+
+      **3. State concentration**
+      If >80% of simulation time is spent in a single non-productive state
+      (e.g. `crash_short`, `emergency`, `waiting`), the state machine is stuck.
+      A stuck machine is not a conservative strategy — it is a broken one.
+      Surface this in finalize as a warning, not a footnote.
+
+      ### Category B — Silent Gain Bugs (inflated returns from accounting errors)
+
+      These bugs produce plausible-looking positive returns. They are harder to catch
+      because the output looks like a win.
+
+      **4. Return plausibility**
+      For a market-neutral strategy: annual return >200% or `total_pnl / fee_income >10×`
+      is almost certainly a bug, not alpha. Fee income is ground truth of actual activity.
+      A strategy that earns 10× its fees in price income has a broken hedge or look-ahead leak.
+
+      **5. Delta neutrality**
+      Track `avg |net_delta|` while in the primary running state.
+      High average delta = the hedge is broken, bootstrapped incorrectly, or bypassed.
+      This check surfaces bootstrap order bugs that only appear mid-simulation.
+
+      **6. Instrument balance**
+      Sub-strategies should be sized proportionally per the allocation spec.
+      If one instrument is 5× larger than another at finalize, allocation logic failed.
+      Check: `max(instrument_notionals) / min(instrument_notionals) > 3× → warn`.
+
+      ### Integration requirements
+
+      - All 6 checks run in the harness `finalize()` step, printing alongside standard metrics.
+      - Failed invariants logged as `[INVARIANT FAIL]` — not swallowed as warnings.
+      - Checks are parameterized: thresholds in config, not hardcoded.
+      - All 6 checks have unit tests with synthetic data that triggers each failure mode.
+
+      ### Volatility unit convention
+
+      Unit confusion in vol calculations is the single most common source of both false crash
+      triggers and missed recovery conditions in DeFi and market-neutral strategies.
+
+      - Vol fields stored as `percentage_per_period` must never be re-transformed with
+        `/ sqrt(N)` or `* 100` after storage. Storing already-scaled vol and scaling again
+        = off by 10×–100× with no runtime error.
+      - Label every vol field with its unit in the variable name or type alias:
+        `vol_pct_per_day`, `sigma_annual` — never just `vol` or `sigma`.
+      - Annualization convention must be a named constant: `TRADING_DAYS_PER_YEAR = 252`
+        (or 365, or actual — choose one, name it, use it everywhere).

package/templates/fintech/mcp-servers.yaml

@@ -1,13 +1,13 @@
-tag: FINTECH
-section: mcp-servers
-servers:
-  - name: stripe
-    description: "Stripe API integration — payments, subscriptions, invoices, and customer management"
-    command: npx
-    args: ["-y", "@stripe/mcp-server"]
-    tags: [FINTECH]
-    category: general
-    tier: recommended
-    env:
-      STRIPE_SECRET_KEY: ""
-    url: "https://github.com/stripe/agent-toolkit"
+tag: FINTECH
+section: mcp-servers
+servers:
+  - name: stripe
+    description: "Stripe API integration — payments, subscriptions, invoices, and customer management"
+    command: npx
+    args: ["-y", "@stripe/mcp-server"]
+    tags: [FINTECH]
+    category: general
+    tier: recommended
+    env:
+      STRIPE_SECRET_KEY: ""
+    url: "https://github.com/stripe/agent-toolkit"