[Feature]: Restore CodeFile nodes and implementation traceability in the v2 knowledge graph

[jeromevdl]

Problem

The v2 Intent knowledge graph no longer contains code nodes, while the former Sprint graph exposed CodeFile vertices.

The graph currently connects requirements, stories, artifacts, and units of work, but stops before the implementation. We cannot navigate from an intent or unit to the files it created or changed, nor answer questions such as:

• Which files implement this requirement or story?
• Which intent or unit changed this file?
• Which implementation or test files are associated with an acceptance criterion?

This is a significant loss of end-to-end SDLC traceability.

Previous v1 model

The v1 graph used this model:

Sprint ─────CONTAINS───────> CodeFile
Task ───────IMPLEMENTED_BY─> CodeFile
UserStory ──IMPLEMENTED_BY─> CodeFile  (optional shortcut)

The complete implementation chain was:

Requirement ─BREAKS_INTO─> UserStory
UserStory ───BREAKS_INTO─> Task
Task ────────IMPLEMENTED_BY─> CodeFile

A CodeFile contained:

id
file_path
repository
commit_ref
summary
sprint_id

Its UUID identity meant that the node represented a file in the context of a particular Sprint/implementation revision, rather than one mutable global node per repository path.

Proposed v2 model

Restore the same concepts using the v2 equivalents:

Intent ──────CONTAINS───────> CodeFile
UnitOfWork ──IMPLEMENTED_BY─> CodeFile
Story ───────IMPLEMENTED_BY─> CodeFile  (evidence-backed shortcut)

UnitOfWork is the natural v2 equivalent of the v1 Task.

Preserve the existing label, edge vocabulary, and properties where possible:

CodeFile:
  id
  file_path
  repository
  commit_ref
  summary
  intent_id
  unit_slug
  stage_instance_id
  file_kind             # implementation | test | configuration | documentation
  traceability_source   # git | aidlc-traceability

Use a deterministic, revision-scoped identity such as:

hash(intent_id, repository, commit_ref, file_path)

This preserves the v1 semantics and code history while making ingestion idempotent. A repository-and-path-only identity would overwrite revision provenance and make commit_ref ambiguous.

A canonical global SourceFile node and CodeFile ─REVISION_OF─> SourceFile relationship can be considered later if cross-intent file history requires it.

Use AIDLC structured traceability when available

Recent AIDLC v2 workflows introduced stable element IDs and per-stage traceability.json artifacts in awslabs/aidlc-workflows#401.

For code-generation, each coverage entry maps an upstream ID such as an AC, NFR, BR, FR, or NFR to an existing workspace-relative implementation or test file:

{
  "stage": "code-generation",
  "unit": "u1-auth",
  "coverage": [
    { "id": "AC1.1.1", "status": "OK", "target": "src/auth/login.ts" },
    { "id": "NFR1.1", "status": "OK", "target": "src/cache/redis.ts" }
  ]
}

When this artifact is present and valid, ingest it as authoritative evidence and create IMPLEMENTED_BY edges between matching graph elements and CodeFile nodes.

Backward compatibility

Compatibility must be capability-based, not based on a numeric workflowVersion. Versions are local to each workflow, and custom or forked workflows may gain structured traceability at any version.

• All workflows: use the Git results already captured after stage execution to create revision-scoped CodeFile nodes and link them to the Intent and UnitOfWork.
• Traceability-capable workflows: detect and validate a produced traceability artifact, then add precise specification-to-file edges from its coverage entries.
• Older workflows: retain code topology without fabricating requirement or acceptance-criterion links. Missing structured traceability is a supported degraded mode, not an execution failure.
• Historical intents: allow lazy enrichment or an explicit graph rebuild where sufficient Git/artifact data still exists.

This also lets custom workflows emit the same contract without depending on a specific upstream AIDLC version.

Tests

As in v1, test files can initially remain CodeFile nodes, identified through file_kind: test. Dedicated TestCase, TestExecution, and test-result nodes should be introduced separately once executable test evidence is available.

Acceptance criteria

• Files created or modified by v2 construction stages appear as CodeFile nodes in the Intent graph.
• The model retains the v1 CodeFile label and IMPLEMENTED_BY edge semantics.
• Intent ─CONTAINS─> CodeFile and UnitOfWork ─IMPLEMENTED_BY─> CodeFile relationships are created.
• Code file identity is revision-scoped using intent, repository, commit, and workspace-relative path.
• Code nodes retain provenance to the intent, unit, stage instance, repository, and commit SHA.
• Reprocessing the same stage and commit is idempotent.
• A valid traceability.json is ingested when present.
• OK coverage targets create evidence-backed IMPLEMENTED_BY links between known graph elements and implementation/test files.
• Workflows without traceability.json still produce code nodes and intent/unit links.
• Missing structured traceability never causes legacy workflow execution to fail.
• The Intent graph API and existing graph UI expose and render the restored code nodes and relationships.
• Coverage includes both traceability-capable and legacy workflow fixtures.

Follow-ups

• Promote acceptance criteria to first-class graph nodes with stable IDs.
• Add dedicated TestCase, TestExecution, and test-result evidence.
• Add a canonical SourceFile model if cross-intent revision history is needed.
• Link code symbols where language-aware indexing is available.
• Add reverse impact analysis from changed code to affected requirements and tests.