sc30gsw/skills/vcsdd-coherence-scan

/vcsdd-coherence-scan — Coherence Graph Scan

What

Rebuild the Conditioned Evidence Graph (CEG) from coherence: or codd: frontmatter declared in the feature's spec files. The CEG tracks dependency relationships between spec documents and declared implementation modules so that change-impact analysis is always current.

When to use

• After writing or editing any spec file that contains a coherence: or codd: block
• Before running /vcsdd-coherence-impact to ensure the graph is up to date
• Whenever you want to initialise coherence tracking for a new feature

Prerequisites

• An active VCSDD feature pipeline (.vcsdd/features/<name>/ exists)
• At least one spec file with a coherence: or codd: frontmatter block

Frontmatter format

Add a coherence: block to the top of any Markdown spec file. For upstream CoDD compatibility, codd: is also accepted. Prefer coherence: in VCSDD-authored docs, but do not rewrite imported CoDD docs solely for key naming.

---
coherence:
  node_id: "design:api-design"     # Required — unique ID with prefix
  type: design                      # Optional — inferred from prefix if omitted
  name: "API Design"                # Optional — display name
  depends_on:
    - id: "design:system-design"
      relation: derives_from        # Optional, default: depends_on
    - id: "req:auth-requirements"
      relation: specifies
  depended_by:
    - id: "design:ui-design"        # Nodes that depend on this doc
  modules:
    - "auth"
    - "module:session"              # CoDD-style implementation module links
  conventions:
    - targets:
        - "module:auth"             # Node IDs that must be reviewed when this doc changes
      reason: "Auth policy applies to all modules"
  data_dependencies:
    - table: "users"
      column: "tenant_id"
      affects:
        - "module:billing"          # Nodes impacted when this column changes
      condition: "multi-tenant isolation"
  source_files:
    - "src/api/routes.ts"           # File-path traceability metadata
---

modules: participates in impact propagation by creating concrete module:* nodes. source_files: records file paths for reference but does not, by itself, drive forward BFS propagation.

Allowed node_id prefixes: req:, design:, db_table:, db_column:, module:, file:, test:, config:, endpoint:, infra:, governance:, doc:, db:, detail:, plan:, ops:

Steps

1. Identify the active feature name from .vcsdd/active-feature.txt
2. Run the CEG rebuild:

const { rebuildFromFrontmatter, summarize } = require('./scripts/lib/vcsdd-coherence');
const featureName = /* active feature name */;
const ceg = rebuildFromFrontmatter(featureName);
const summary = summarize(ceg);

3. Report the result:

Coherence scan complete
  Nodes  : <nodeCount>
  Edges  : <edgeCount>
  Green  : <green>   (≥90% confidence, ≥2 evidence)
  Amber  : <amber>   (≥50% confidence)
  Gray   : <gray>    (<50% confidence)
  Cycles : <hasCycles ? "⚠ CYCLES DETECTED" : "none">

4. If cycles are detected, list them and advise the user to resolve the circular dependencies before continuing.

Output

• .vcsdd/features/<name>/coherence.json is created or updated
• A summary is printed to the conversation

Troubleshooting

| Symptom | Resolution | |---------|------------| | "No spec files with coherence: frontmatter found" | Add coherence: blocks to spec files | | Cycle detected | Check depends_on / depended_by for circular references; resolve before proceeding | | Unknown node_id prefix | Use one of the allowed prefixes listed above |