# Webdev Agent OS v14 — Product Digital Twin and Code Traceability

## Purpose

The Product Digital Twin creates an evidence-backed representation of how an approved product decision exists in code and production.

It is designed to answer six questions that normal repositories and project boards usually answer only partially:

1. **Why does this code exist?**
2. **Which requirement and product evidence justify it?**
3. **How is the behavior tested?**
4. **Which change, build, and deployment introduced it?**
5. **What runtime evidence shows whether it works?**
6. **What requirements, tests, releases, metrics, and incidents are affected if it changes?**

The digital twin does not replace Git, CI, deployment systems, observability tools, incident systems, or the Product Continuum. It connects their evidence into one traceable graph.

## Evidence chain

```text
Product evidence
→ Continuum requirement
→ source file / API route / migration / configuration
→ automated test
→ commit / pull request / change set
→ build artifact
→ verified deployment
→ runtime telemetry
→ incident provenance
→ impact analysis
```

## Main records

### Digital twins

A twin identifies the product contract, portfolio project, repository root, default branch, environment, owner, and current health state.

### Artifacts

Supported artifact types are:

- `source_file`
- `api_route`
- `database_migration`
- `automated_test`
- `configuration`
- `dependency`
- `runbook`

Each artifact can record:

- Relative repository path
- Expected and observed SHA-256 hashes
- Hash state
- Criticality
- Requirement links
- Automated test links
- Artifact dependencies
- Current version and owner

### Trace links

Trace links can represent relationships such as:

- `implements`
- `verified_by`
- `depends_on`
- `introduced_by`
- `packaged_in`
- `deployed_as`
- `observed_by`
- `affected_by`

The current implementation stores both explicit links and direct identifiers on important records so the graph remains readable and portable.

### Code changes

Changes preserve commit, pull-request, or change-set evidence including:

- SHA or external identifier
- Branch
- Author
- Status
- Artifacts changed
- Requirements affected
- Review or test evidence

### Builds

A passing or verified build requires:

- A known code change
- Automated test artifacts
- Evidence references

### Deployments

A deployment cannot be marked deployed or verified without:

- A passing build
- Reviewer authority
- Approval identity
- Evidence
- A rollback reference

The engine records deployment evidence. It does not silently execute production commands.

### Telemetry

Runtime telemetry must link to:

- A verified deployment
- A requirement
- One or more artifacts
- Evidence

This prevents operational dashboards from becoming detached from the product behavior they are intended to measure.

### Incidents

An incident must identify:

- The affected deployment
- Requirements
- Artifacts
- Severity and status
- Evidence

Resolution requires reviewer authority, a root cause, and supporting evidence.

### Impact analyses

Impact analysis calculates a change blast radius across:

- Requirements
- Implementation artifacts
- Automated tests
- Builds and deployments
- Runtime signals
- Related incidents

Risk rises with critical artifacts, missing tests, production deployments, database migrations, and unresolved incidents.

## Trace coverage

Requirement trace coverage uses five dimensions:

1. Implementation artifact
2. Automated test evidence
3. Change and passing build evidence
4. Verified deployment evidence
5. Runtime telemetry

Each dimension contributes 20 points. A requirement with all five dimensions receives 100% trace coverage.

High trace coverage is not the same as healthy production. A twin can have excellent traceability and still be at risk because of drift, missing files, weak testing, or active incidents.

## Health scoring

Twin health begins with average requirement trace coverage and applies evidence penalties for:

- Drifted or missing artifacts
- Orphaned implementation artifacts
- Untested high-criticality or critical artifacts
- Active incidents weighted by severity

Health classifications are:

- **Healthy:** 85–100
- **Watch:** 70–84
- **At risk:** 50–69
- **Blocked:** below 50, or an active critical incident

## Hash verification

`scanTwin` resolves each active artifact path beneath the configured repository root and calculates SHA-256.

Possible states:

- `match`
- `drifted`
- `missing`
- `unverifiable`
- `unknown`

Paths that escape the configured repository root are not read. They are marked `unverifiable`.

Hash verification proves only that the local file matches the registered expectation. It does not prove that the file is deployed or correct.

## Human authority

Developers can register artifacts, changes, builds, telemetry, incidents, and analyses.

Reviewers or owners are required for:

- Deployment evidence
- Incident resolution
- Other consequential decisions defined by connected systems

Clients cannot access internal code traceability through the API.

## Control Center

The Product Digital Twin workspace includes:

- Twin health and drift
- Requirement-to-runtime trace matrix
- Code and infrastructure artifact inventory
- Build and deployment evidence
- Runtime telemetry
- Incident provenance
- Blast-radius analyses
- Hash verification
- JSON export and HTML report generation

## CLI

```bash
npm run digital-twin:stats
npm run digital-twin:report
node scripts/digital-twin-cli.js view
node scripts/digital-twin-cli.js view twin-opportunity-recovery
```

Verify registered artifact hashes:

```bash
node scripts/digital-twin-cli.js scan \
  twin-opportunity-recovery \
  examples/product-digital-twin/source
```

Run an impact analysis from JSON:

```bash
node scripts/digital-twin-cli.js impact impact-request.json
```

Example request:

```json
{
  "twinId": "twin-opportunity-recovery",
  "artifactId": "artifact-auth-source"
}
```

## API

Primary endpoints:

```text
GET  /api/digital-twin
GET  /api/digital-twin/stats
GET  /api/digital-twin/export
POST /api/digital-twin/twins
POST /api/digital-twin/artifacts
POST /api/digital-twin/links
POST /api/digital-twin/changes
POST /api/digital-twin/builds
POST /api/digital-twin/deployments
POST /api/digital-twin/telemetry
POST /api/digital-twin/incidents
POST /api/digital-twin/incidents/:id/resolve
POST /api/digital-twin/twins/:id/scan
POST /api/digital-twin/impact
POST /api/digital-twin/report
```

## Included demonstration

The bundled Opportunity Recovery twin contains actual fixture files whose hashes can be independently verified. The records for commits, builds, deployment, telemetry, and incidents are clearly labeled illustrative and do not claim live external-system activity.

The baseline intentionally contains:

- A missing critical runtime-policy file
- An acknowledged authorization-related incident
- Strong requirement traceability

This shows why trace coverage and operational health must remain separate measurements.