@prism-d1/cli 1.0.99 → 1.2.0

package/dist/assets/github-workflows/prism-agent-eval.yml

@@ -6,7 +6,8 @@
 #   - OIDC provider configured for GitHub Actions in your AWS account
 #   - IAM role with bedrock:InvokeModel and events:PutEvents permissions
 #   - Repository secret PRISM_METRICS_ROLE_ARN set to the OIDC role ARN
-#   - .prism/config.json committed to the repo (created by: bash prism-cli bootstrapper install-git-hooks)
+#   - .prism/config.json committed to the repo with a "team_id" key; add it by hand, e.g.
+#     {"team_id": "team-payments"} (prism-cli enable codewatch keeps existing keys in this file)
 #   - .prism/eval-harness/ installed (run: bash prism-cli bootstrapper install-eval-harness)
 #   - (Optional) Agent entry point supports --mock flag for dry-run execution
 

package/dist/assets/github-workflows/prism-eval-gate-kiro.yml

@@ -4,7 +4,8 @@
 #
 # Required setup:
 #   - Kiro API key stored as repository secret: KIRO_API_KEY
-#   - .kiro/steering/code-review.md in your repo (review rules)
+#   - .prism/review/rules.md (shared with the local pre-push review) or
+#     .kiro/steering/code-review.md in your repo (review rules)
 #   - (Optional) PRISM_METRICS_ROLE_ARN for EventBridge metrics emission
 #   - (Optional) AWS Continuum configured for security scanning
 #
@@ -236,6 +237,15 @@ jobs:
             exit 0
           fi
 
+          # Shared rule set: .prism/review/rules.md is the one source for this
+          # gate and the local pre-push review (prism-cli enable security).
+          # kiro-cli loads rules from .kiro/steering/, so sync it in for this run.
+          if [ -f .prism/review/rules.md ]; then
+            mkdir -p .kiro/steering
+            cp .prism/review/rules.md .kiro/steering/code-review.md
+            echo "Review rules: .prism/review/rules.md"
+          fi
+
           # Get all changed source files in this PR
           FILES=$(git diff --name-only "${BASE_SHA}..${HEAD_SHA}" \
             | grep -E '\.(ts|js|py|go|java|rs|tsx|jsx)$' \

package/dist/assets/gitlab-workflows/prism-eval-gate.yml

@@ -186,6 +186,14 @@ prism-eval-gate:
       elif [ -z "${BASE_SHA}" ] || [ -z "${HEAD_SHA}" ]; then
         echo "⚠️  Missing base/head SHA — review skipped."
       else
+        # Shared rule set (also used by the local pre-push review). kiro-cli
+        # loads rules from .kiro/steering/, so sync it in for this run.
+        if [ -f .prism/review/rules.md ]; then
+          mkdir -p .kiro/steering
+          cp .prism/review/rules.md .kiro/steering/code-review.md
+          echo "Review rules: .prism/review/rules.md"
+        fi
+
         FILES=$(git diff --name-only "${BASE_SHA}..${HEAD_SHA}" \
           | grep -E '\.(ts|js|py|go|java|rs|tsx|jsx)$' \
           | grep -vE '\.test\.|\.spec\.|__test__|_test\.' \

package/dist/assets/infra/lib/constructs/otel-collector-construct.ts

@@ -24,6 +24,9 @@ import * as cognito from 'aws-cdk-lib/aws-cognito';
 import * as s3 from 'aws-cdk-lib/aws-s3';
 import * as kms from 'aws-cdk-lib/aws-kms';
 import * as logs from 'aws-cdk-lib/aws-logs';
+import * as events from 'aws-cdk-lib/aws-events';
+import * as targets from 'aws-cdk-lib/aws-events-targets';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
 import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { HttpJwtAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
@@ -32,6 +35,7 @@ import * as ssm from 'aws-cdk-lib/aws-ssm';
 import * as path from 'path';
 import { Construct } from 'constructs';
 import { NagSuppressions } from 'cdk-nag';
+import { PRICES_KEY } from '../lambda/pricing/prices-key';
 
 /** codeburn sync fixed loopback callback ports (see codeburn src/sync/auth.ts). */
 const CODEBURN_CALLBACK_PORTS = [19876, 19877, 19878];
@@ -49,6 +53,57 @@ export interface OtelCollectorConstructProps {
   externalClientId?: string;
   /** JWT claim used as the user identity key (default: username for Cognito, sub for BYO). */
   identityClaim?: string;
+
+  // ---------------------------------------------------------------------------
+  // Federated IdP on the Cognito pool (Okta, Entra ID, any OIDC provider).
+  //
+  // Distinct from the BYO-IdP props above. Those REPLACE Cognito as the token
+  // issuer and drop the machine-to-machine client with it. These keep Cognito as
+  // the issuer and add an upstream provider behind it, so the coding agent's
+  // client-credentials path survives.
+  //
+  // All five must be supplied together; a partial set throws rather than
+  // half-configuring an IdP that fails at first login.
+  // ---------------------------------------------------------------------------
+
+  /** Provider name, e.g. 'CorpIdP'. Becomes the `<name>_` username prefix. */
+  idpName?: string;
+  /** OIDC issuer URL, e.g. https://idp.example.com */
+  idpIssuer?: string;
+  /** OAuth client id registered with the IdP for this user pool. */
+  idpClientId?: string;
+  /**
+   * ARN or name of a Secrets Manager secret holding the IdP client secret.
+   *
+   * A REFERENCE, never the value: the secret is resolved by a CloudFormation
+   * dynamic reference at deploy time, so the plaintext is never written to the
+   * template, CloudFormation state, or CI logs. Passing the secret itself
+   * through CDK context would put it in `cdk.context.json` and the synthesized
+   * template, which is the antipattern the reference exists to avoid.
+   *
+   * Provide either a plain-text secret whose whole value is the client secret,
+   * or a JSON secret with a `clientSecret` key (set idpClientSecretJsonKey).
+   *
+   * CAVEAT: CloudFormation resolves a dynamic reference only when the resource
+   * containing it is created or updated. Rotating the secret in Secrets Manager
+   * does NOT reach Cognito on its own — the IdP resource must change too.
+   */
+  idpClientSecretArn?: string;
+  /** JSON key inside the secret holding the client secret. Omit for a plain-text secret. */
+  idpClientSecretJsonKey?: string;
+  /**
+   * Scopes Cognito requests FROM the IdP. Defaults to 'openid email'.
+   *
+   * `email` is load-bearing and the default exists because of it: without it the
+   * IdP returns no email claim, Cognito stores `email: null` on every federated
+   * user, and the identity falls back to the `<provider>_<alias>` username —
+   * which never matches the git author emails the CI census emits, silently
+   * splitting each developer into two identities on the dashboards.
+   *
+   * NOT the same as the app client's AllowedOAuthScopes, which governs
+   * app→Cognito rather than Cognito→IdP.
+   */
+  idpScopes?: string;
 }
 
 export class OtelCollectorConstruct extends Construct {
@@ -117,6 +172,84 @@ export class OtelCollectorConstruct extends Construct {
         cognitoDomain: { domainPrefix },
       });
 
+      // -----------------------------------------------------------------
+      // Optional federated IdP in front of the pool.
+      //
+      // Created BEFORE the app client so the client's
+      // supportedIdentityProviders can reference it; CloudFormation rejects a
+      // client naming a provider that does not exist yet, and addDependency
+      // below makes that ordering explicit rather than incidental.
+      // -----------------------------------------------------------------
+      const idpFields = [props.idpName, props.idpIssuer, props.idpClientId, props.idpClientSecretArn];
+      const idpConfigured = idpFields.some((f) => f !== undefined);
+      if (idpConfigured && idpFields.some((f) => f === undefined)) {
+        throw new Error(
+          'Federated IdP requires idpName, idpIssuer, idpClientId and idpClientSecretArn together '
+          + '(context: -c otelIdpName=... -c otelIdpIssuer=... -c otelIdpClientId=... -c otelIdpClientSecretArn=...)',
+        );
+      }
+
+      let federatedIdp: cognito.CfnUserPoolIdentityProvider | undefined;
+      if (idpConfigured) {
+        // Build the dynamic reference as a LITERAL string.
+        //
+        // The obvious CDK spelling — Secret.fromSecretNameV2(...).secretValueFromJson(k)
+        // .unsafeUnwrap() — composes the ARN with `Ref: AWS::Partition`, so the
+        // property renders as an Fn::Join whose OUTPUT happens to be a
+        // {{resolve:...}} string. CloudFormation resolves dynamic references
+        // during template processing and does not reliably resolve one produced
+        // by an intrinsic; the risk is Cognito storing the literal
+        // "{{resolve:secretsmanager:...}}" as the client secret, which fails at
+        // first federated login with an upstream "invalid_client" and no failed
+        // resource to point at. Verified by synthesizing both forms.
+        //
+        // The secret id comes from CDK context, so it is a plain string and
+        // interpolation yields a literal with no intrinsic. Secrets Manager
+        // accepts either a friendly name (same account and region) or a full ARN.
+        const secretId = props.idpClientSecretArn!;
+        if (!/^(arn:[a-z0-9-]+:secretsmanager:[a-z0-9-]+:\d{12}:secret:[A-Za-z0-9/_+=.@-]+|[A-Za-z0-9/_+=.@-]+)$/.test(secretId)) {
+          throw new Error(
+            `idpClientSecretArn "${secretId}" is not a valid Secrets Manager secret name or ARN. `
+            + 'Expected a friendly name or a full arn:...:secretsmanager:...:secret:... ARN.',
+          );
+        }
+        const jsonKey = props.idpClientSecretJsonKey ?? '';
+        if (jsonKey && !/^[A-Za-z0-9_.-]+$/.test(jsonKey)) {
+          throw new Error(`idpClientSecretJsonKey "${jsonKey}" must be alphanumeric with . _ - only.`);
+        }
+        // Trailing `::` selects the current version stage (AWSCURRENT), so the
+        // reference tracks rotation without pinning a version id.
+        const clientSecretRef = `{{resolve:secretsmanager:${secretId}:SecretString:${jsonKey}::}}`;
+
+        federatedIdp = new cognito.CfnUserPoolIdentityProvider(this, 'FederatedIdp', {
+          userPoolId: this.userPool.userPoolId,
+          providerName: props.idpName!,
+          providerType: 'OIDC',
+          // A SUPERSET of what the console-created provider had, never a
+          // replacement. `username: sub` is what Cognito uses to derive the
+          // native federated username (`<ProviderName>_<sub>`); dropping it
+          // changes the username shape, which mints a second set of user
+          // records and splits every developer's history a second time. Only
+          // `email` and the name claims are additions.
+          //
+          // `email` is the load-bearing one: it is what lets the identity match
+          // the git author emails the CI census emits.
+          attributeMapping: {
+            username: 'sub',
+            email: 'EMAIL',
+            given_name: 'GIVEN_NAME',
+            family_name: 'FAMILY_NAME',
+          },
+          providerDetails: {
+            oidc_issuer: props.idpIssuer!,
+            client_id: props.idpClientId!,
+            client_secret: clientSecretRef,
+            authorize_scopes: props.idpScopes ?? 'openid email',
+            attributes_request_method: 'GET',
+          },
+        });
+      }
+
       // Public client (no secret) — codeburn does Authorization Code + PKCE
       // with loopback redirects. Cognito allows http:// for localhost, 127.0.0.1,
       // and [::1] (per CreateUserPoolClient API docs). codeburn uses 127.0.0.1.
@@ -132,10 +265,97 @@ export class OtelCollectorConstruct extends Construct {
           scopes: [cognito.OAuthScope.OPENID, cognito.OAuthScope.EMAIL, cognito.OAuthScope.PROFILE],
           callbackUrls,
         },
+        // Declared here so it cannot drift. Setting this in the console instead
+        // leaves CloudFormation believing the client is Cognito-only, and the
+        // next deploy of this stack silently reverts it — breaking federated
+        // login with no failed resource to point at.
+        supportedIdentityProviders: idpConfigured
+          ? [
+              cognito.UserPoolClientIdentityProvider.COGNITO,
+              cognito.UserPoolClientIdentityProvider.custom(props.idpName!),
+            ]
+          : [cognito.UserPoolClientIdentityProvider.COGNITO],
         preventUserExistenceErrors: true,
         accessTokenValidity: cdk.Duration.hours(1),
         refreshTokenValidity: cdk.Duration.days(30),
       });
+      if (federatedIdp) {
+        this.userPoolClient.node.defaultChild?.node.addDependency(federatedIdp);
+      }
+
+      // -----------------------------------------------------------------
+      // Pre token generation (V2_0) — puts `email` in the ACCESS token.
+      //
+      // Attached only when a federated IdP is configured: for admin-created
+      // users the username IS the email, so the trigger would be a no-op that
+      // still billed an invocation on every token issuance.
+      //
+      // Inert without `identityClaim: 'email'` — see the note in
+      // pre-token-generation.ts. The warning below fires on the one
+      // half-configured combination that looks like it should work.
+      // -----------------------------------------------------------------
+      if (idpConfigured) {
+        // props.identityClaim is not yet folded into `identityClaim` at this
+        // point in the branch, so resolve the same default inline.
+        const claimForWarning = props.identityClaim ?? 'username';
+        if (claimForWarning !== 'email') {
+          cdk.Annotations.of(this).addWarning(
+            'A federated IdP is configured and the pre-token-generation trigger will add an `email` '
+            + 'claim to access tokens, but identityClaim is '
+            + `"${claimForWarning}" — the receiver checks that claim (and then \`username\`, which is `
+            + 'always present) before `email`, so the trigger has no effect. Deploy with '
+            + '-c otelIdentityClaim=email to key identities on email.',
+          );
+        }
+
+        const preTokenGen = new lambda.Function(this, 'PreTokenGeneration', {
+          functionName: 'prism-d1-pre-token-generation',
+          runtime: lambda.Runtime.NODEJS_22_X,
+          handler: 'pre-token-generation.handler',
+          // Deliberately NOT in the VPC: Cognito invokes this synchronously on
+          // the token-issuance path, and it makes no network calls, so a VPC
+          // attachment would add cold-start ENI latency to every sign-in for
+          // nothing.
+          code: lambda.Code.fromAsset(path.join(__dirname, '..', 'lambda'), {
+            bundling: {
+              image: lambda.Runtime.NODEJS_22_X.bundlingImage,
+              command: [
+                'bash', '-c',
+                [
+                  'npm init -y > /dev/null 2>&1',
+                  'npm install --save esbuild > /dev/null 2>&1',
+                  'npx esbuild pre-token-generation.ts --bundle --platform=node --target=node22 --outfile=/asset-output/pre-token-generation.js --external:@aws-sdk/*',
+                ].join(' && '),
+              ],
+              local: {
+                tryBundle(outputDir: string): boolean {
+                  try {
+                    const { execSync } = require('child_process');
+                    execSync(
+                      `npx esbuild ${path.join(__dirname, '..', 'lambda', 'pre-token-generation.ts')} --bundle --platform=node --target=node22 --outfile=${path.join(outputDir, 'pre-token-generation.js')} --external:@aws-sdk/*`,
+                      { stdio: 'pipe' },
+                    );
+                    return true;
+                  } catch {
+                    return false;
+                  }
+                },
+              },
+            },
+          }),
+          // Token issuance blocks on this call, so keep the budget tight: the
+          // function reads one attribute off the event and returns.
+          timeout: cdk.Duration.seconds(5),
+          memorySize: 128,
+          logRetention: logs.RetentionDays.ONE_MONTH,
+        });
+
+        this.userPool.addTrigger(
+          cognito.UserPoolOperation.PRE_TOKEN_GENERATION_CONFIG,
+          preTokenGen,
+          cognito.LambdaVersion.V2_0,
+        );
+      }
 
       issuer = `https://cognito-idp.${cdk.Aws.REGION}.amazonaws.com/${this.userPool.userPoolId}`;
       clientId = this.userPoolClient.userPoolClientId;
@@ -293,9 +513,101 @@ export class OtelCollectorConstruct extends Construct {
 
     props.aiUsageTable.grantReadWriteData(receiver);
     this.archiveBucket.grantPut(receiver);
+    // The LiteLLM price table the refresh Lambda maintains (pricing/price-source.ts).
+    // Exact key, read only. KMS decrypt comes from grantEncryptDecrypt below.
+    const pricesObjectArn = this.archiveBucket.arnForObjects(PRICES_KEY);
+    receiver.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['s3:GetObject'],
+      resources: [pricesObjectArn],
+    }));
     props.kmsKey.grantEncryptDecrypt(receiver);
     this.receiverFunction = receiver;
 
+    // -------------------------------------------------------
+    // Price refresh + reprice — daily
+    // Keeps the receiver's LiteLLM fallback table current in S3, then
+    // corrects spans stored at $0 whose model has since been priced.
+    // See lib/lambda/pricing-refresh.ts.
+    //
+    // Deliberately NOT in the VPC: the PRISM VPC has no NAT gateway, and this
+    // function's one job that needs a network path is an HTTPS GET to
+    // raw.githubusercontent.com. It accepts no inbound traffic, and reaches
+    // only S3 and DynamoDB besides, both over their public endpoints with IAM.
+    // -------------------------------------------------------
+    const pricingRefresh = new lambda.Function(this, 'PricingRefresh', {
+      functionName: 'prism-d1-pricing-refresh',
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: 'pricing-refresh.handler',
+      code: lambda.Code.fromAsset(path.join(__dirname, '..', 'lambda'), {
+        bundling: {
+          image: lambda.Runtime.NODEJS_22_X.bundlingImage,
+          command: [
+            'bash', '-c',
+            [
+              'npm init -y > /dev/null 2>&1',
+              'npm install --save @aws-sdk/client-dynamodb @aws-sdk/client-s3 esbuild > /dev/null 2>&1',
+              'npx esbuild pricing-refresh.ts --bundle --platform=node --target=node22 --outfile=/asset-output/pricing-refresh.js --external:@aws-sdk/*',
+            ].join(' && '),
+          ],
+          local: {
+            tryBundle(outputDir: string): boolean {
+              try {
+                const { execSync } = require('child_process');
+                execSync(
+                  `npx esbuild ${path.join(__dirname, '..', 'lambda', 'pricing-refresh.ts')} --bundle --platform=node --target=node22 --outfile=${path.join(outputDir, 'pricing-refresh.js')} --external:@aws-sdk/*`,
+                  { stdio: 'pipe' },
+                );
+                return true;
+              } catch {
+                return false;
+              }
+            },
+          },
+        },
+      }),
+      // A full-table scan plus, on the first run, a read of the raw archive to
+      // recover cache-token counts for spans stored before they were kept.
+      timeout: cdk.Duration.minutes(15),
+      memorySize: 1024,
+      environment: {
+        AI_USAGE_TABLE: props.aiUsageTable.tableName,
+        ARCHIVE_BUCKET: this.archiveBucket.bucketName,
+      },
+      logRetention: logs.RetentionDays.ONE_MONTH,
+      description: 'Daily: refresh the LiteLLM price table in S3, then reprice usage spans stored at $0',
+    });
+    props.aiUsageTable.grantReadWriteData(pricingRefresh);
+    // Read the raw archive (to recover cache-token counts), and read/write the
+    // one price-table object. No delete: an old table is only ever overwritten.
+    this.archiveBucket.grantRead(pricingRefresh, 'otlp/*');
+    pricingRefresh.addToRolePolicy(new iam.PolicyStatement({
+      actions: ['s3:GetObject', 's3:PutObject'],
+      resources: [pricesObjectArn],
+    }));
+    props.kmsKey.grantEncryptDecrypt(pricingRefresh);
+
+    new events.Rule(this, 'PricingRefreshSchedule', {
+      ruleName: 'prism-d1-pricing-refresh-daily',
+      description: 'Refresh LiteLLM prices and reprice $0 spans',
+      // 06:17 UTC: off the hour so it is not queued behind other schedules.
+      schedule: events.Schedule.cron({ minute: '17', hour: '6' }),
+      // No retry: a failed run already repriced what it could and the next day's
+      // run starts from the same state. Errors surface on the Lambda metric.
+      targets: [new targets.LambdaFunction(pricingRefresh, { retryAttempts: 0 })],
+    });
+
+    NagSuppressions.addResourceSuppressions(pricingRefresh, [
+      {
+        id: 'AwsSolutions-IAM5',
+        reason: 'grantRead scopes S3 reads to the otlp/* prefix of the single archive bucket (raw OTLP batches, read to recover cache-token counts); grantReadWriteData adds the AI-usage table GSI index wildcard.',
+        appliesTo: [
+          'Action::s3:GetObject*', 'Action::s3:GetBucket*', 'Action::s3:List*',
+          { regex: '/^Resource::<OtelCollectorArchiveBucket.*\\.Arn>\\/otlp\\/\\*$/g' },
+          { regex: '/^Resource::<AiUsageTable.*\\.Arn>\\/index\\/\\*$/g' },
+        ],
+      },
+    ], true);
+
     // -------------------------------------------------------
     // CloudWatch Custom Widget: Developer Productivity
     // Invoked by CloudWatch dashboards with the VIEWING user's IAM creds

package/dist/assets/infra/lib/dashboard-stack.ts

@@ -215,31 +215,31 @@ export class DashboardStack extends cdk.Stack {
         updateOnResize: false,
         updateOnTimeRangeChange: true,
       })] : []),
-      new cloudwatch.GraphWidget({
-        title: 'AI Spend Trend (Weekly)',
-        left: [weeklySum('AICostUSD', 'Spend ($)')],
+      new cloudwatch.CustomWidget({
+        functionArn: props?.velocityWidgetArn ?? '',
+        title: 'AI Spend Trend',
         width: 8,
         height: 6,
-        leftYAxis: { min: 0, label: 'USD' },
+        params: { view: 'ai-spend-trend' },
+        updateOnRefresh: true,
+        updateOnResize: false,
+        updateOnTimeRangeChange: true,
       }),
-      new cloudwatch.GraphWidget({
-        title: 'Cost per Shipped Commit (Weekly)',
-        left: [
-          // The ROI narrative: spend can rise while this falls, which means AI
-          // is getting more efficient per unit of shipped work.
-          new cloudwatch.MathExpression({
-            expression: 'FILL(IF(FILL(execMerged, 0) > 0, FILL(execCost, 0) / FILL(execMerged, 0)), REPEAT)',
-            usingMetrics: {
-              execCost: weeklySum('AICostUSD'),
-              execMerged: weeklySum('MergedAICommits'),
-            },
-            label: '$ / shipped AI commit',
-            period: cdk.Duration.days(7),
-          }),
-        ],
+      // The ROI narrative: spend can rise while this falls, which means AI is
+      // getting more efficient per unit of shipped work. That reading only holds
+      // if both terms are bucketed by when the work happened — the CloudWatch
+      // version this replaces divided two ingest-timestamped metrics, so a
+      // backfill collapsed the ratio and read as a 94% efficiency gain that
+      // never occurred. See renderCostPerCommitTrend.
+      new cloudwatch.CustomWidget({
+        functionArn: props?.velocityWidgetArn ?? '',
+        title: 'Cost per Shipped Commit',
         width: 8,
         height: 6,
-        leftYAxis: { min: 0, label: 'USD' },
+        params: { view: 'cost-per-commit-trend' },
+        updateOnRefresh: true,
+        updateOnResize: false,
+        updateOnTimeRangeChange: true,
       }),
     );
 
@@ -676,23 +676,6 @@ export class DashboardStack extends cdk.Stack {
       );
 
       // --- Row 1: Org KPIs (NaN-guarded metric math, follow time range) ---
-      const dailyMetric = (metricName: string, id: string): cloudwatch.Metric =>
-        new cloudwatch.Metric({
-          namespace: METRIC_NAMESPACE,
-          metricName,
-          statistic: 'Sum',
-          period: cdk.Duration.days(1),
-          label: id,
-        });
-      const ratioKpi = (title: string, expression: string, using: Record<string, cloudwatch.IMetric>): cloudwatch.SingleValueWidget =>
-        new cloudwatch.SingleValueWidget({
-          title,
-          metrics: [new cloudwatch.MathExpression({ expression, usingMetrics: using, label: title, period: cdk.Duration.days(1) })],
-          setPeriodToTimeRange: true,
-          width: 6,
-          height: 4,
-        });
-
       devDashboard.addWidgets(
         // AI Share and AI Merge Rate are DDB-backed (accurate, no CloudWatch delay)
         new cloudwatch.CustomWidget({
@@ -715,15 +698,31 @@ export class DashboardStack extends cdk.Stack {
           updateOnResize: false,
           updateOnTimeRangeChange: true,
         }),
-        ratioKpi('Cost per Shipped Commit ($)', 'IF(FILL(kMerged2, 0) > 0, FILL(kCost, 0) / FILL(kMerged2, 0))', {
-          kCost: dailyMetric('AICostUSD', 'kCost'), kMerged2: dailyMetric('MergedAICommits', 'kMerged2'),
+        // Both of these read the attribution store rather than CloudWatch metric
+        // math. The metric versions divided/summed AICostUSD and MergedAICommits,
+        // which are ingest-timestamped and subject to CloudWatch's two-week
+        // datapoint cutoff, and carry no user dimension — so they disagreed with
+        // the store-backed figures in row 3 on both terms AND ignored the
+        // Developer variable. See renderCostPerCommitKpi for the measured gap.
+        new cloudwatch.CustomWidget({
+          functionArn: props.velocityWidgetArn ?? '',
+          title: 'Cost per Shipped Commit ($)',
+          width: 6,
+          height: 4,
+          params: { view: 'cost-per-commit-kpi' },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
         }),
-        new cloudwatch.SingleValueWidget({
+        new cloudwatch.CustomWidget({
+          functionArn: props.velocityWidgetArn ?? '',
           title: 'AI Spend (range, $)',
-          metrics: [dailyMetric('AICostUSD', 'AI Spend')],
-          setPeriodToTimeRange: true,
           width: 6,
           height: 4,
+          params: { view: 'ai-spend-kpi' },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
         }),
       );
 
@@ -740,12 +739,15 @@ export class DashboardStack extends cdk.Stack {
           updateOnResize: false,
           updateOnTimeRangeChange: true,
         }),
-        new cloudwatch.GraphWidget({
+        new cloudwatch.CustomWidget({
+          functionArn: props?.velocityWidgetArn ?? '',
           title: 'AI Spend / Day',
-          left: [dailyMetric('AICostUSD', 'Spend ($)')],
           width: 8,
           height: 6,
-          leftYAxis: { min: 0, label: 'USD' },
+          params: { view: 'ai-spend-trend' },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
         }),
         // Merge Rate Trend — DDB-backed line chart replacing CloudWatch AI Merge Ratio Trend
         new cloudwatch.CustomWidget({
@@ -806,6 +808,33 @@ export class DashboardStack extends cdk.Stack {
         }),
       );
 
+      // --- Row 5: Tools the model invoked (codeburn ai.tools) ---
+      // Store-backed like the spend tiles: OTEL#TOOLDAY rollups are bucketed by
+      // the call's own day and keep full history, so a backfilled sync push is
+      // not cut off at CloudWatch's two-week window. Follows the Developer filter.
+      devDashboard.addWidgets(
+        new cloudwatch.CustomWidget({
+          functionArn: props.velocityWidgetArn ?? '',
+          title: 'Tool Usage: Top Tools & MCP Servers',
+          width: 16,
+          height: 9,
+          params: { view: 'tool-usage-top', user: USER_TOKEN },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
+        }),
+        new cloudwatch.CustomWidget({
+          functionArn: props.velocityWidgetArn ?? '',
+          title: 'Tool Calls / Day',
+          width: 8,
+          height: 9,
+          params: { view: 'tool-usage-trend', user: USER_TOKEN },
+          updateOnRefresh: true,
+          updateOnResize: false,
+          updateOnTimeRangeChange: true,
+        }),
+      );
+
       new cdk.CfnOutput(this, 'DevProductivityDashboardUrl', {
         value: `https://${this.region}.console.aws.amazon.com/cloudwatch/home?region=${this.region}#dashboards:name=PRISM-D1-Developer-Productivity`,
         description: 'Developer Productivity Dashboard URL',