forgecraft-mcp 1.2.0 → 1.3.2

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"

package/templates/fintech/nfr.yaml

@@ -1,46 +1,46 @@
-tag: FINTECH
-section: nfr
-blocks:
-  - id: fintech-transaction-integrity
-    tier: recommended
-    title: "Transaction Integrity"
-    content: |
-      ## NFR: Transaction Integrity
-
-      ### ACID Compliance
-      - All financial operations wrapped in database transactions.
-      - Double-entry bookkeeping: every debit has a corresponding credit. Ledger always balances.
-      - Idempotency keys on all payment operations — retries must not duplicate charges.
-
-      ### Precision
-      - NO floating-point arithmetic for monetary values. Use integer cents, BigDecimal, or Decimal types.
-      - Currency stored alongside amount. No implicit currency assumptions.
-      - Rounding rules documented and consistent with regulatory requirements.
-
-      ### Reconciliation
-      - Automated reconciliation between internal ledger and external payment providers.
-      - Reconciliation frequency: {{reconciliation_frequency | default: daily}}.
-      - Discrepancies alerted within 1 hour. Unresolved discrepancies escalated.
-
-  - id: fintech-compliance
-    tier: recommended
-    title: "Financial Compliance"
-    content: |
-      ## NFR: Financial Compliance
-
-      ### Regulatory
-      - PCI DSS compliance for card data handling. No raw card numbers stored — tokenize.
-      - KYC/AML processes integrated where required. Document which regulations apply.
-      - SOC 2 Type II audit trail: all access to financial data logged and retained.
-
-      ### Audit Trail
-      - Immutable audit log for every financial transaction.
-      - Log contains: timestamp, actor, operation, before/after state, correlation ID.
-      - Retention: minimum {{audit_retention | default: 7 years}} per regulatory requirements.
-      - Audit logs stored separately, tamper-evident (append-only, hashed).
-
-      ### Disaster Recovery
-      - RPO for financial data: < {{fintech_rpo | default: 5 minutes}}.
-      - RTO: < {{fintech_rto | default: 1 hour}}.
-      - Point-in-time recovery to any second within retention window.
-      - DR drill: quarterly, documented, measured.
+tag: FINTECH
+section: nfr
+blocks:
+  - id: fintech-transaction-integrity
+    tier: recommended
+    title: "Transaction Integrity"
+    content: |
+      ## NFR: Transaction Integrity
+
+      ### ACID Compliance
+      - All financial operations wrapped in database transactions.
+      - Double-entry bookkeeping: every debit has a corresponding credit. Ledger always balances.
+      - Idempotency keys on all payment operations — retries must not duplicate charges.
+
+      ### Precision
+      - NO floating-point arithmetic for monetary values. Use integer cents, BigDecimal, or Decimal types.
+      - Currency stored alongside amount. No implicit currency assumptions.
+      - Rounding rules documented and consistent with regulatory requirements.
+
+      ### Reconciliation
+      - Automated reconciliation between internal ledger and external payment providers.
+      - Reconciliation frequency: {{reconciliation_frequency | default: daily}}.
+      - Discrepancies alerted within 1 hour. Unresolved discrepancies escalated.
+
+  - id: fintech-compliance
+    tier: recommended
+    title: "Financial Compliance"
+    content: |
+      ## NFR: Financial Compliance
+
+      ### Regulatory
+      - PCI DSS compliance for card data handling. No raw card numbers stored — tokenize.
+      - KYC/AML processes integrated where required. Document which regulations apply.
+      - SOC 2 Type II audit trail: all access to financial data logged and retained.
+
+      ### Audit Trail
+      - Immutable audit log for every financial transaction.
+      - Log contains: timestamp, actor, operation, before/after state, correlation ID.
+      - Retention: minimum {{audit_retention | default: 7 years}} per regulatory requirements.
+      - Audit logs stored separately, tamper-evident (append-only, hashed).
+
+      ### Disaster Recovery
+      - RPO for financial data: < {{fintech_rpo | default: 5 minutes}}.
+      - RTO: < {{fintech_rto | default: 1 hour}}.
+      - Point-in-time recovery to any second within retention window.
+      - DR drill: quarterly, documented, measured.