Discussion: a Programme QEP — codifying the grammar's top tier, and ordering projects within it

[mmcky]

Per QEP-1, this is the optional discussion issue preceding a draft proposal. The question: should the Programme layer — the top tier of the org's work grammar — be formalised as a QEP, and what should that QEP decide? Raised while QEP-6 (#18) is in Draft; its scope deliberately reserves this layer ("the programme layer is outside"), so this is the designated next document, not a reopening.

The grammar, as practised

Three tiers are in use across the org. The lower two are codified or in flight; the top one is working practice with no stated convention.

Tier	Working definition	Where codified today	Exemplar
Programme	A standing family of projects that may or may not have direct crossover, coordinating between them where — and only where — coordination is required	Registry concept only: programmes: in the QuantEcon/status-projects registry (slug, name, one-line summary, front_door, status_page, lead); eight today	Translation
Project	One tracker issue carrying the native Project issue type; its work items are its direct native sub-issues; order is positional; phases are milestones	QEP-6 (Draft, #18)	QuantEcon/status-projects#1
Work item	An issue whose closing advances a project's definition of done; an unparented issue is the normal case, not a gap to be filled	QEP-6 §1	—

The practice exists; the convention doesn't

• The registry side works: 29 registered projects across eight programmes (2026-08-28), every project row naming its programme; programme roll-ups (projects / active / now / flagged) are computed nightly from the projects; the programme's front_door is a link the collector never reads for observed facts.
• The structural side is trialled, not ruled. The 2026-08-23 structure audit measured 9 of 28 registered trackers nested under a programme tracker (five under QuantEcon/project-translation#39, three under QuantEcon/workspace-lectures#56), four three-level trees org-wide, and 0 tracker-level dependency edges against 12 on work items. QuantEcon/status-projects#10 holds the open question — is the programme layer structure on GitHub (nesting) or a venue (coordination only where required) — with four options, a stated leaning (dependencies for required coordination plus the dashboard row for visibility; nesting allowed but never required or read), and a decision date after the collector's first month of data.
• The two documents in flight nearly contradict. The registry schema requires programme on every project; QEP-6 rules that "an unparented project tracker is likewise normal: not every project answers to a programme." These reconcile — membership is optional in the org-wide grammar, while a total partition is this one dashboard's presentation constraint — but no document states that, and left unstated it reads as a conflict.
• Vocabulary drift is live: a project row named "Benchmarking programme"; a programme whose registry name is "Translation" but which is spoken of as "Internationalisation & translation"; phase (within-project sequencing, QEP-6) vs stage (lifecycle position, registry) split in the documents but nowhere stated as a rule.

The prior question: an entity, or a unit of account?

Before any definition comes a fork this discussion should settle first: is a Programme a thing in the org — a standing entity with duties — or a unit of measure the dashboard uses to organise and roll up projects? Today one word covers both, and the two populations are visibly different. Four of the eight registered programmes have no front door; Software is a pure shelf — one project, no lead, no front door, no status page — a category the portfolio page needs, coordinating nothing. Translation is the opposite pole: a lead, a private front door parenting five project trackers, its own status page, and real between-project traffic.

The leaning this issue proposes: define the entity; leave the unit of account where it is already codified. Grouping, required membership and roll-up mechanics are the dashboard's presentation contract and already have a normative home (the registry schema and published-data schema in QuantEcon/status-projects); they need no QEP. What has no home is the entity: what a Programme is, when a family of projects warrants one, and what its duties are — managing the cross-project gates below, carrying ordering where it exists, a lead who answers for the family. A registry group may be backed by a Programme or may be a mere shelf, and the definition should welcome that distinction rather than force every category to become a coordinating body. A candidate membership test, in the spirit of QEP-6's definition-of-done test: a family of projects is a Programme when coordination between its projects is somebody's job. No coordination to do, no Programme — just a group.

The honest alternative stays on the table: if the discussion concludes that Programme is only a unit of measure, the outcome is no new QEP — QuantEcon/status-projects#10 is ruled dashboard-side, and QEP-6 gains one scope sentence recording that the grammar has two tiers.

The ordering question

Within a project, order is settled: QEP-6 makes the sub-issue list the plan — position is the order, the topmost open item is next, and sequence never enters names.

Between the projects of a programme the honest default is parallel: most projects in a family progress concurrently, so a total order would assert something false. But "unordered" is not right either, and three things are already on the table:

1. What exists. The registry declares a coarse priority (now / next / later) per project — nine projects org-wide are now today, three of them in Translation. Real cross-project constraints have a native carrier already specified: QEP-6 §3 lets dependency edges cross project boundaries and defines the tracker-to-tracker gate for a project that waits on another in its entirety. At the tracker level that mechanism is so far unused (0 of 28), and nothing yet names who manages such gates — the natural owner is the programme.
2. Evidence the QuantEcon/status-projects#10 options predate. That issue's for/against table was written 2026-08-23, before QEP-6 made list position the order carrier. Under nesting (its option A), a front door's sub-issue list is itself positional — the programme tier would inherit QEP-6's ordering mechanism for free, and position survives private-repo redaction (the same property that selected it within projects; Translation's front door is itself private). Nesting is thereby also an ordering carrier, not only a venue, and the option weighing should be re-run with that on the table.
3. Why order matters here at all: dispatch. The dashboard should assist workload management and assignment — for humans and for AI agents. A grammar in which every tier answers "what is next" gives a deterministic resolution path from portfolio to next action — programme → next project → that project's topmost open work item — with no prose parsing. The field evidence (on Discussion: a QEP for work-plan tracking issues — genres, the body/comment discipline, and succession #15, 2026-08-26) says the honest shape is a partial order: a mechanism that can only rank would push "these two run concurrently" back into prose, so expressing parallelism must be as natural as expressing "this leads", with genuine constraints as dependency edges.

What the QEP would settle

1. The prior fork: entity, or unit of account. If the entity — the definition of Programme with its membership test, and a one-page grammar table for all three tiers (informative for the lower two, citing QEP-6 as their normative home). If only a unit of account — no QEP, with the disposition recorded as above.
2. Membership, stated through that split: every project files into a registry group (presentation — a total partition is fine), while answering to a Programme happens only where a Programme exists (grammar, optional — the half QEP-6 already states).
3. Structure or venue: the QuantEcon/status-projects#10 options, decided on the September data and re-weighed for nesting's ordering property.
4. Ordering between projects: the carrier (declared priority, list position under nesting, dependencies only — or a combination), the parallel-by-default semantics, and the "next" resolution path for dispatch.
5. Cross-project gates: the programme as their manager — where a gate is stated (QEP-6 §3 places it in the body of the project that waits), what the front door adds, and how blocked-ness surfaces on the programme row.
6. Discovery: whether a programme tracker carries a Programme issue type so that type:Project discovery does not mistake one for a project (the fallback noted on QuantEcon/status-projects#10).
7. Roll-up semantics: programme progress is computed over its projects; a front door's own sub-issue percentage counts projects, not work, and is never published as progress.
8. Lifecycle and words: programmes are standing families (retiring one is a registry edit, not a stage machine); pin phase vs stage, and lead (programme) vs owner (project).

Case study: the Translation programme

The org's richest programme grounds every question above. Seven registered projects of three kinds — finite projects, a steady loop (translation maintenance, which has no end state), and a release work package (engine v0.27.0) — with a private front door (QuantEcon/project-translation#39) that parents five of the seven as native sub-issues while the engine work package roots its own tree. Three projects are now at once and the family otherwise runs in parallel with zero declared tracker dependencies — exactly the shape the ordering mechanism must serve without asserting false sequence. The name is itself a membership test: if the family is really Internationalisation & translation, does author-and-translator attribution (today under Content & books) belong to it? The definition should be strong enough to decide such cases, the way QEP-6's definition-of-done test decides work-item membership. The coordination test also grades the current registry honestly: Translation passes it — as, arguably, does Lecture estate, whose front door and weekly plan chain live in QuantEcon/workspace-lectures — while Software does not and stays a shelf; both outcomes are correct.

What this discussion is not

Not a reopening of QEP-6's unit — that definition is being field-tested in Draft and its scope already reserves this layer. And not a "project management procedures" omnibus: the 2026-08-23 ruling on #15 deliberately kept genres, ledgers and succession in the qe skills, which cite the QEPs; bundling taxonomy with procedure would re-tangle what that ruling split. One focused QEP, sibling to QEP-6.

Suggested path

Let the evidence windows converge. QEP-6's comment window opens on the collector's first month of data (late September 2026), and QuantEcon/status-projects#10 is scheduled for the same data, before QEP-6 leaves Draft. Rule the dashboard-side half on QuantEcon/status-projects#10 first, then draft the Programme QEP (next free number — QEP-7 as of this writing) from this discussion, that ruling, and a re-run of the structure audit against the 2026-08-23 baseline.

[mmcky]

Ruling: the prior fork is settled as unit of account. A Programme is a named collection of Projects — a grouping the QuantEcon/status-projects registry maintains as its yml project list — and there will be no Programme QEP. This is the outcome this issue itself kept on the table ("the honest alternative"), now chosen deliberately: the starting point is to work QEP-2 and QEP-6 as they stand and discover limitations over time rather than forecast them.

Why. The programme tier has exactly one producer and one consumer of its facts — the registry and its collector — and a contract with one writer and one reader is that repo's schema, not an org standard. The entity case rests on one real coordinating exemplar (Translation) against a population where half the registered programmes are shelves, which is below the second-instance bar the org applies elsewhere. And there is no field drift to arrest at this tier — the forcing conditions that produced QEP-6 are absent. The only real justification for a Programme entity would be if it simplified status-projects, and it does not: that repo manages a list of projects as yml either way.

The residue all has homes. Front-door discovery: the registry's front_door field — not a Programme issue type, which QEP-6 §2 now forecloses (hierarchy level never enters the type set, and Programme fails the admission test: closing one means nothing distinct), so item 6 above is answered. Coarse cross-project ordering: the registry's now/next/later priority. Genuine cross-project blockers, if they eventuate: native dependency edges, which QEP-6 §4 already lets cross project boundaries. Deliberate project-to-project relationships: the tracker body's Related work section (QEP-6 §7), one line per link. Coordination practice: the qe skills, per the 2026-08-23 ruling that keeps procedure out of the QEPs. Structure-vs-venue (QuantEcon/status-projects#10) is ruled dashboard-side on its own September schedule — nesting stays allowed under QEP-6's homogeneity rule, never required or read as structure.

Documents updated. QEP-6 records the ruling as one scope sentence — two normative tiers, project and work item, and no third — in 361be8c on the PR #18 branch. Correction for the record: this issue's references to "QEP-6 §3" (cross-boundary edges, gate placement) now point at §4 after the section renumbering in PR #18.

Revival trigger. A Programme QEP becomes worth drafting if a second coordinating programme emerges whose practice drifts from Translation's, or a second machine consumer needs programme facts beyond the registry schema — at which point it drafts from two exemplars instead of one. Until then, closing per QEP-2's discuss discipline: decision summarised, follow-ups placed.