.github/workflows/portfolio-check.yaml

te updateDependencyGraph(product: ProductManifest): void { const deps = new Set<string>(); product.dependencies.forEach(dep => deps.add(dep.product_id)); this.dependencyGraph.set(product.metadata.id, deps); }

// Query: Get all products with 'active' lifecycle getActiveProducts(): ProductManifest[] { return Array.from(this.products.values()).filter( p => p.metadata.lifecycle === 'active' ); }

// Query: Detect circular dependencies detectCircularDependencies(): string[][] { const cycles: string[][] = []; const visited = new Set<string>(); const stack = new Set<string>();

const dfs = (node: string, path: string[]) => {
  if (stack.has(node)) {
    const cycleStart = path.indexOf(node);
    cycles.push(path.slice(cycleStart).concat(node));
    return;
  }
  if (visited.has(node)) return;

  visited.add(node);
  stack.add(node);
  path.push(node);

  const deps = this.dependencyGraph.get(node) || new Set();
  deps.forEach(dep => dfs(dep, [...path]));
  
  stack.delete(node);
};

this.products.forEach((_, id) => dfs(id, []));
return cycles;

}

// Query: Aggregate cost by team getCostByTeam(): Record<string, number> { const teamCosts: Record<string, number> = {}; this.products.forEach(p => { const team = p.metadata.owner.team; // In production, this would query a cost API using p.assets.infra.costCenter const estimatedCost = 1000; // Placeholder for API integration teamCosts[team] = (teamCosts[team] || 0) + estimatedCost; }); return teamCosts; } }

#### 3. CLI Tool for Developers
Provide a CLI to validate manifests locally and query the portfolio.

```typescript
// src/cli/index.ts
import { Command } from 'commander';
import fs from 'fs/promises';
import { PortfolioRegistry } from '../registry/portfolio-registry';

const program = new Command();

program
  .name('portfolio-cli')
  .description('Manage your digital product portfolio');

program
  .command('validate')
  .argument('<path>', 'Path to product-manifest.yaml')
  .action(async (path: string) => {
    try {
      const content = await fs.readFile(path, 'utf-8');
      const yaml = await import('js-yaml');
      const manifest = yaml.load(content);
      
      const registry = new PortfolioRegistry();
      await registry.ingestManifest(manifest);
      console.log('✅ Manifest valid and ingested.');
    } catch (error) {
      console.error('❌ Validation failed:', error.message);
      process.exit(1);
    }
  });

program
  .command('graph')
  .action(async () => {
    // Logic to load all manifests and output DOT graph
    console.log('Generating dependency graph...');
  });

program.parse();

4. CI/CD Integration

Enforce the matrix in the pipeline.

# .github/workflows/portfolio-check.yaml
name: Portfolio Validation
on:
  pull_request:
    paths:
      - 'product-manifest.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx portfolio-cli validate ./product-manifest.yaml
      
      - name: Check Dependencies
        run: |
          # Run dependency check against registry
          npm run check:deps

Pitfall Guide

Common Mistakes

1. The YAML Trap: Over-Specification

   • Mistake: Defining 50+ fields in the manifest, including runtime configurations or deployment parameters.
   • Impact: Developers treat the manifest as a configuration file rather than a portfolio descriptor. Changes become frequent and error-prone.
   • Correction: Separate portfolio metadata from deployment configuration. The manifest should describe what the product is, not how to deploy it.

2. Ignoring Dependency Criticality

   • Mistake: Listing dependencies without marking criticality.
   • Impact: During outages, teams cannot prioritize. A non-critical data dependency failure blocks deployment of a critical service.
   • Correction: Enforce criticality in the schema. Use this data to implement fallback strategies and blast radius analysis.

3. Static Lifecycle States

   • Mistake: Setting lifecycle to "active" and never updating it.
   • Impact: Technical debt accumulates in "zombie" products. Resources are not reclaimed.
   • Correction: Automate lifecycle transitions. If a product has no deployments in 90 days, flag it for maintenance review.

4. Cost Attribution Without Granularity

   • Mistake: Tagging resources at the account level instead of the product level.
   • Impact: Cost variance remains high. Teams cannot optimize spend.
   • Correction: Mandate costCenter in the manifest. Use infrastructure-as-code to inject this tag into all resources provisioned for the product.

5. Dependency Drift

   • Mistake: Updating code dependencies without updating the manifest.
   • Impact: The registry becomes inaccurate. Dependency graphs are useless.
   • Correction: Integrate manifest updates into the dependency upgrade workflow. If package.json changes, the CI should verify the manifest reflects new runtime dependencies.

6. Security Silos

   • Mistake: Treating security as a separate scan rather than a portfolio policy.
   • Impact: Vulnerabilities are reported per repo, not per product. Risk assessment is fragmented.
   • Correction: Aggregate security findings by product_id. Block deployments if the aggregate product risk exceeds the policy threshold.

7. Neglecting Developer Experience

   • Mistake: Building a complex registry with no DX tools.
   • Impact: Developers bypass the system. Shadow portfolios emerge.
   • Correction: Provide autocomplete, validation, and clear error messages in the CLI. Integrate with IDEs. Make compliance easier than non-compliance.

Best Practices from Production

• Schema Versioning: Always include apiVersion in the manifest. This allows you to evolve the schema without breaking existing products.
• Read-Only Registry: The registry should be built from manifests. Never allow direct writes to the registry. The source of truth is the Git repository.
• Graph Database for Scale: For portfolios >200 products, migrate the dependency graph to a graph database (Neo4j) for efficient traversal and impact analysis.
• Automated Onboarding: Create a portfolio init command that scaffolds the manifest with sensible defaults based on detected tech stack.

Production Bundle

Action Checklist

• Define Product Schema: Create the Zod schema for product-manifest.yaml covering metadata, assets, dependencies, and policies.
• Build Registry Service: Implement the PortfolioRegistry class with ingestion, validation, and query capabilities.
• Develop CLI Tool: Create a CLI to validate manifests locally and provide feedback to developers.
• Implement CI Gate: Add a pipeline step that validates manifests and checks for dependency cycles on PRs.
• Tag Infrastructure: Update IaC templates to inject costCenter and product_id tags derived from the manifest.
• Configure Cost Aggregation: Set up a daily job to query cloud billing APIs using cost centers and update portfolio metrics.
• Enable Dependency Scanning: Integrate a tool (e.g., Dependabot, Renovate) to auto-update manifest dependencies when code dependencies change.
• Create Dashboard: Build a visualization of the asset matrix showing lifecycle distribution, cost by team, and dependency health.

Decision Matrix

Configuration Template

Copy this template to product-manifest.yaml in your repository root.

# product-manifest.yaml
apiVersion: cc20-3-1-digital-asset-matrix/v1
kind: Product

metadata:
  id: user-auth-service
  name: User Authentication Service
  owner:
    team: identity-platform
    slackChannel: "#eng-identity"
    email: team-identity@company.com
  lifecycle: active
  tags:
    tier: critical
    data-classification: pii

assets:
  repositories:
    - https://github.com/company/user-auth-service
  infra:
    provider: aws
    region: us-east-1
    costCenter: CC-IDENTITY-001
  telemetry:
    logs: https://logs.company.com/query?service=user-auth
    metrics: https://metrics.company.com/dashboard?service=user-auth
    traces: https://traces.company.com/trace?service=user-auth

dependencies:
  - product_id: user-db
    type: runtime
    criticality: mandatory
  - product_id: audit-logger
    type: data
    criticality: optional

policies:
  security_scan: true
  performance_budget_ms: 200
  sla_percent: 99.95

Quick Start Guide

1. Initialize: Run npx @codcompass/portfolio-cli init in your repository. This creates a valid product-manifest.yaml with detected defaults.
2. Edit: Fill in metadata.owner, assets.infra.costCenter, and dependencies.
3. Validate: Run npx @codcompass/portfolio-cli validate ./product-manifest.yaml to ensure schema compliance.
4. Commit: Push the manifest to your repository. The CI pipeline will automatically ingest it into the portfolio registry.
5. Verify: Query the registry API or dashboard to confirm your product appears in the matrix with correct tags and dependencies.