Skip to content

[Feature]: Support incremental, versioned artifact history across project iterations #414

Description

@pbarone

Description

Real projects don't happen in a single pass. They evolve iteratively — initial build, then performance improvements, bug fixes, new features. Currently, all AIDLC artifacts get mixed into the same flat structure with no separation between iterations, making it impossible to trace what was done when, what the original scope was, and how the project evolved over time.

When re-ideation happens for a new feature, the original ideation artifacts get overwritten or amended in-place, losing the historical record of what was decided and why.

The desired behavior is full historical documentation preserved across iterations:

  1. Preserve prior state — When re-ideation or a new iteration happens, original artifacts remain intact and accessible for reference
  2. Amendments reference prior versions — New iterations should clearly indicate what they're building upon / changing from the previous state
  3. Clear chronological tracing — A human (or agent) should be able to follow the project's evolution from initial ideation through each subsequent iteration
  4. Useful for both humans and agents — Historical context helps humans audit decisions and helps agents make better-informed choices in future iterations

Use Case

  1. Developer starts a new project with AIDLC, goes through ideation → inception → construction, arrives at v1
  2. Later, developer wants to add a new feature — this requires re-ideation
  3. The original ideation should remain intact for reference, and the new ideation should amend/extend it rather than overwrite it
  4. Both the human and the agent should be able to see the full history: "Here's what we started with, here's how it evolved"

This improves the iterative development workflow by providing a full audit trail of project evolution. Developers can understand past decisions, agents can leverage historical context for better outcomes, and teams get visibility into how scope and design evolved over time.

Version

v2 (alpha)

Area

Documentation

Additional Context

In aidlc-docs/construction/code-generation/, the learnings files show multiple iterations crammed together with no delineation for a project I am building to test the workflow:

.learnings-selections.json           ← initial build
.learnings-selections-perf.json      ← performance iteration
.learnings-selections-bugfix.json    ← bug fix iteration

In aidlc-docs/construction/s3-browser/, three distinct sprints (initial creation, performance improvements, sharing link feature) are lumped into one directory with no separation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions