feat(framework): a task document has no end of life, and a superseded one has no forward pointer

[amenophis]

Issue-first, no PR opened. Reported from a repository running aidd-context 2.6.2, aidd-dev 2.4.1, aidd-orchestrator 2.2.1, aidd-pm 2.4.2, aidd-refine 3.0.0 and aidd-vcs 2.3.1 on Claude Code.

Problem

Four skills write working documents into aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/, and none of them ever returns to a folder it created.

The only status such a document carries is the plan lifecycle: pending → in-progress → implemented → reviewed, plus blocked. Every one of those values describes how far the work got. None describes whether the document is still true. A plan that reached reviewed six months ago and a plan written yesterday read identically — same shape, same present tense, no signal between them.

The framework does have a supersede mechanism, but it is scoped to product briefs, unavailable to specs and plans, and it points backwards only: a reader who opens a superseded document gets no pointer to what replaced it, and would have to grep the tree for a supersedes naming the file they are holding.

What that costs. A repository following this framework accumulated 56 documents and 37,041 lines under a pre-AIDD equivalent of tasks/. A field renamed during one epic survived, described in the present tense, in five of them. Nothing marked those five, so agents reading the directory built a model of the system that had not been true for months — and two blind spots in a later plan came from exactly that.

The documents ageing is not the defect. The defect is that nothing in the framework asks anyone to notice.

Scope

• Extend the status vocabulary beyond the kanban axis, so a document can state whether it still describes the design in force: current for one that does, superseded for one wholly replaced. These sit beside the work-tracking values rather than replacing them — a document can be both reviewed and superseded, and the two answer different questions.
• Add a forward pointer, superseded_by, naming the replacement as a project-relative path. Backwards-only linking makes the reader do a repository-wide search at the exact moment they have least reason to suspect they need one.
• Add a partial-invalidation field, amended_by, for a document still broadly current whose specific claims a later effort overturned. This is the common case in practice and the one a binary current / superseded cannot express without lying in one direction or the other.
• State, in the skills that create task folders, what becomes of an existing folder when the work it describes changes. Today the answer is nothing, which is why the gap reopens on its own.

Acceptance criteria

• A reader opening any document under aidd_docs/tasks/ can tell from its frontmatter alone whether it describes the design in force, without consulting the code.
• A document marked superseded names its replacement in the document itself; no repository-wide search is needed to find it.
• A document invalidated in part can say so without being marked wholly superseded.
• The supersede vocabulary is reachable from specs and plans, not from product briefs alone.
• A skill that creates or updates a task folder has documented instructions for what to do with the documents already in it.

Prior art in this repo

• plugins/aidd-dev/skills/01-plan/references/plan-status.md:12-23 — the five status values and the linear rule. Purely kanban; line 20 confirms the intended progression ends at reviewed.
• plugins/aidd-pm/skills/06-product-brief/references/persistence.md:7-9 — the only supersede mechanism in the framework: current / superseded plus supersedes. This proposal borrows its vocabulary rather than inventing a competing one.
• The four write sites this would cover: plugins/aidd-refine/skills/01-brainstorm/references/persistence.md:7, plugins/aidd-pm/skills/04-spec/actions/01-build.md:21, plugins/aidd-dev/skills/01-plan/actions/04-plan.md:11, plugins/aidd-dev/skills/05-review/SKILL.md:26.

Out of scope

• Whether a shipped document is deleted or kept. That is a project decision, not a framework one; the repository this came from deletes plans at reviewed and keeps specs, and either policy needs the status field this issue asks for.
• A CI check enforcing the header. Worth having, but it depends on the vocabulary existing first.
• Migrating existing task folders. A project's own concern once the fields are defined.

[amenophis]

Field evidence, found after opening this — and two corrections to what I asked for.

The repository this came from carries sixteen documents with a hand-written **Status:** line in the body. Five different phrasings, two different syntaxes, none machine-readable:

> **Status:** approved by user, awaiting implementation plan.
**Status:** design approved 2026-08-09 from clickable mockups. Nothing implemented.
> **Status:** awaiting user review.
**Status:** decided, not implemented. The tiered price exists in Stripe test mode; no code reads it yet.
**Status:** implemented (WEH-323).

Authors invented the field the framework does not give them. aidd-pm:04-spec/assets/ defines a spec by Target, Hard constraints, Non-goals, Done-when, Stakeholders and Context — no status of any kind — so a spec written by the skill today has the same hole.

Those hand-written lines then went stale, because nothing owns them. Thirteen of the sixteen were false when I checked them against the code: ten claimed work was unbuilt that had shipped months earlier, and one said awaiting user review for a design that had merged in two pull requests.

Three corrections

1. The truth axis is orthogonal to the work axis, and both belong in frontmatter. As written above, this issue invites an implementer to fold current / superseded into the existing enum. That forces a false choice: a spec can legitimately be approved but not implemented and still describe the design in force. Those are answers to different questions. Collapsing them is what made those sixteen documents readable two ways.

2. superseded is not enough — a third value is needed for abandonment. I marked a 2026-04 design as superseded_by a later pricing document, then found the later document replaces nothing of it: different subject, and the feature was never built at all. It was dropped, not replaced. A superseded document lost an argument to a successor and the reader should go read that one; an abandoned document describes something nobody built and nobody will, and there is nowhere to send the reader. Marking the second as the first invents a successor, which is worse than saying nothing. abandoned, with no companion pointer.

3. Each value needs a stated evidentiary standard, or the field will lie. This one is my own mistake, and it is the strongest argument for saying so explicitly. Writing this up, I certified a document as current on the strength of two checks: its last commit was nine days old, and the database tables it named still existed. Both were true. The document described a two-plan price grid; the code had carried four plans for a week, under different names, with a different billing period. Neither check could have caught that, because neither read the content.

A status field with no evidentiary standard does not remove the guesswork — it industrialises it, and gives the guess the authority of a machine-readable field. Whatever shape this takes, it should say what justifies each value: for current, that the claims were read against the code, not that the file looks recent.

Suggested shape, revised

status: current | superseded | abandoned   # truth axis
superseded_by: <project-relative path>     # required when superseded
amended_by: [<project-relative path>]      # later work that invalidated part of a current document

sitting beside, never merged into, the pending | in-progress | implemented | reviewed | blocked work axis that plan-status.md already defines.