QEP-6: Project Tracker Structure and Order (Draft)

[quantecon-services]

Adds QEP-6: Project Tracker Structure and Order as a Draft — the one-page unit spec scoped by the 2026-08-23 ruling on the discussion issue, extended with the ordering question that arrived from the field (QuantEcon/textstrata#8, QuantEcon/skills#55) and answered on that thread.

What it decides

• The unit: a Project is one tracker issue carrying the native org Project issue type (a type, not a label — QEP-2 untouched; resolves QEP-2 field report: no type label fits plan/tracking issues #11); work items are native sub-issues, progress on direct children only, never body checkboxes (unmeasured ≠ 0%).
• Order is positional: the sub-issue list is the plan's order — top open item = next, completed items keep their place, phases contiguous, new items placed on arrival. Re-ordering moves items (drag or the reprioritize API) and never renames them; sequence never appears in issue titles or milestone names.
• Constraints are dependencies: a real sequencing constraint is a native blocked-by edge (optional; a constraint, not a presentation order). Phase gates stay in the body.
• Phases are milestones (optional): descriptive names only — a milestone is referenced, not copied, so a phase rename is one propagating edit; cross-repo work items fall back to the body's phase table.
• One machine-read body element: the status stamp (## Where we stand (verified YYYY-MM-DD) canonical; banner fallback). The stamp section sits at the top and may open with a single Next: resume line — the body's only "what's next" claim; the list is the authority if they disagree.
• The no-mirror body: goal, narrative, phase intents/exit criteria, gates, rationale, scope boundaries — never rosters, checkbox work lists, milestone→issue tables, hand-written progress, or dependency prose. Informative skeleton in Appendix A.
• Scope: the programme layer is outside; genres/ledgers/succession stay in the qe skills, which cite this QEP.

Points where input is most useful

1. The plan-order semantics (top = next; completed items keep their place) vs any appetite for queue semantics.
2. The single Next: resume line — right affordance, right home?
3. Whether the phase table + gates belong in the normative body section or should move wholly to Appendix A.
4. The Adoption obligations on the dashboard side (child order published as list order — currently its contract re-sorts by issue number; the amendment is a one-row change plus a sort removal, references are on the discussion issue and 404 for non-members).

Process

Opened as a draft, consistent with the 2026-08-23 ruling that the spec is field-tested in Draft: the conform tooling (QuantEcon/skills#49) brings registered trackers into the layout and the collector reports compliance nightly. The QEP-1 comment window and decision deadline will be set after the collector's first month of data lands (late September 2026), so the decision is made on evidence. Note the ordering half cannot be observed until the child-order amendment ships — the collector currently re-sorts children, which is itself part of the motivation.

qep-checks parity: new QEP, unversioned (implicitly v0), README index row added as standard / Draft / –; both check scripts pass locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_013WNYd4EW71564zVcW81yx7

---

Generated by Claude Code

[mmcky]

Applied the field-test amendment set from #19 (the consolidated 12-amendment checklist in its final comment), plus the two edits from its producer-tooling finding, in commit 1a0f063. The four review calls landed as:

Gates (amendment 10 §1) — the softened, granularity-first form: most cross-project gates are phase-level and stay in the body; a whole-project gate carries the tracker-to-tracker dependency edge, stated once in the body of the project that waits. The edge mechanism is now verified live rather than inferred (see the closing results on #20): an edge between two sub-issue-carrying tracker issues is accepted, reads back on REST blockedBy and GraphQL blockedBy/blocking, and the UI timeline records it — so the whole-project case keeps must.

Stamp concurrency (amendment 7) — the read half is specified as read-from-a-source-returning-surface (the REST endpoint returns raw markdown) rather than an unactionable byte-for-byte round-trip check; where only a sanitising surface is available the body is append-only and corrections go to comments.

"untyped = untriaged" — dropped from §1 as a load-bearing justification for type-over-label; the Motivation's audit observation stands as an observation.

Related work — bound relaxed to: entries name projects, never work items, but item numbers may appear as the specifics of a project-level relationship.

Also in: amendment 2 upgraded from source-derived to executed (gh issue list --milestone "2026" fails with no milestone found with number '2026' while a descriptive name resolves fine), the §6 named-replacements paragraph, and the Adoption-3 sentence making this QEP authoritative over the dashboard's tracker contract wherever they disagree during the handover gap.

Per process: Draft and unmerged, so no version field; both check scripts pass.

[mmcky]

e61b1da adds §2 Issue types, settling the type/label question from the tracker discussion: native issue types carry structural role (what kind of object an issue is in the tracking system), QEP-2 labels carry content at triage, and the axes compose — a work item whose content is a bug is Task + bug, never a Bug type.

The set is three roles, each admitted by having its own meaning of "closed": Project (definition of done met), Task (work shipped), Decision (choice recorded). Decision composes with §4's dependency mechanics so "parked on a decision" is derivable, and the §4 gate-as-decision sentence now names the type. Hierarchy level is never encoded in type — a programme tracker is still a Project.

Adoption gains a one-time org-level precondition: reshape the type set via four reversible API calls — Bug/Feature disabled, not deleted (assignments stay latent; one call undoes it), Task re-described, Decision created — so it ships at field-test start rather than acceptance. Alternatives records the rejection of content-classifying types. Sections 2–7 renumbered to 3–8; both check scripts pass.