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

Start with plugins/aidd-dev/skills/01-plan/references/plan-status.md and plugins/aidd-pm/skills/06-product-brief/references/persistence.md to compare the existing status and supersede vocabularies. Then inspect the four listed task write sites and document the new fields and folder-update behavior there. Done means the acceptance criteria are met for task documents, specs, plans, and the relevant skills.

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.