Repository navigation
feat(framework): a task document has no end of life, and a superseded one has no forward pointer #730
Description
Activity
- changed the title
[-]tasks/ folders have no end of life[/-][+]feat(framework): a task document has no end of life, and a superseded one has no forward pointer[/+]on Aug 30, 2026 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 reviewfor 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/supersededinto 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.
supersededis not enough — a third value is needed for abandonment. I marked a 2026-04 design assuperseded_bya 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 | blockedwork axis thatplan-status.mdalready defines.Thanks for the concrete evidence. I agree the stale-document problem is real, but I do not think
aidd_docs/tasks/should own a document lifecycle.A task folder is an execution snapshot: a brainstorm, a plan, phases, and a review for one attempt at a change. It may cover one unit inside a larger functional need. Once reviewed, it should remain legible as historical context, not be expected to keep asserting whether its design is still current.
Adding
current/superseded/abandonedto every task document would create a second source of truth beside the backlog. It also creates an ongoing maintenance obligation: old folders would need to be re-audited whenever the product changes, otherwise the new frontmatter becomes stale in exactly the way this issue is trying to prevent.The durable relationship belongs between a task and its canonical backlog item. The framework already has a narrow
backlog-link.jsonmechanism for some newly created folders, but that should be treated as an interim shape, not as a second long-term contract.The emerging task-record design is a better place to settle this: one versioned task card, created once, carries the backlog reference and an optional generic parent relation. It must not copy fields the backlog already owns, such as type, priority, or status. If that record becomes the contract, it should absorb or replace
backlog-link.json, rather than coexist with it.The remaining question is therefore backlog-level: which relationships and lifecycle facts need a durable, portable representation, and which can remain native to the destination. That needs to be challenged with a concrete consumer before introducing successor or abandonment fields.
For that reason, I would not add document-validity frontmatter or migrate historical task folders. I suggest reframing this issue around task-to-backlog linkage and backlog-level lifecycle, while leaving the task-record implementation to the dedicated task work.
Closing as not planned after the backlog review.
The stale-document evidence is valid. The requested lifecycle on
aidd_docs/tasks/will not
be introduced: these folders are historical delivery records, not the canonical statement of
the current design. Addingcurrent,superseded,abandoned,superseded_byor
amended_bythere would create the second source of truth described in the maintainer comment
above.#649 was delivered, after an explicit rescope, by #706. Its durable contract is
backlog-link.json: one upward reference from a delivery folder to its canonical backlog item,
plus writing provenance. The omittedmetadata.jsonfields were deliberately rejected because
steps and files belong to the journal, while branch and pull request are derived from Git and
the forge.The current backlog contracts now keep lifecycle and relations on that canonical item:
destination-native fields where supported, Markdown otherwise;supersedesis stored once on
the owning backlog artefact and inverse links are derived. Task delivery documents remain
historical snapshots.If a concrete consumer later exposes a missing portable backlog-level relation, it should be a
separate issue scoped around that consumer rather than document-validity metadata.Reacted by Jérémy Leherpeur
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, plusblocked. Every one of those values describes how far the work got. None describes whether the document is still true. A plan that reachedreviewedsix 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
supersedesnaming 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
statusvocabulary beyond the kanban axis, so a document can state whether it still describes the design in force:currentfor one that does,supersededfor one wholly replaced. These sit beside the work-tracking values rather than replacing them — a document can be bothreviewedandsuperseded, and the two answer different questions.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.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 binarycurrent/supersededcannot express without lying in one direction or the other.Acceptance criteria
aidd_docs/tasks/can tell from its frontmatter alone whether it describes the design in force, without consulting the code.supersedednames its replacement in the document itself; no repository-wide search is needed to find 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 atreviewed.plugins/aidd-pm/skills/06-product-brief/references/persistence.md:7-9— the only supersede mechanism in the framework:current/supersededplussupersedes. This proposal borrows its vocabulary rather than inventing a competing one.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
reviewedand keeps specs, and either policy needs the status field this issue asks for.