QEP-6 field report: building a conformant tracker from an existing issue set

[quantecon-services]

Field report for QEP-6 — Project Tracker Structure and Order (Draft, #18). Filed as an issue rather than a PR comment because of its length; proposed amendments to the draft follow as a comment below, so they can be discussed separately from the findings.

What was tested

On 2026-08-26 we built a QEP-6-conformant project tracker from scratch against a real, pre-existing issue set: QuantEcon/cli#20 — 17 work items, five phases, over a repo whose issues had accumulated since 2026-06. This is the "registered existing tracker brought into layout" case from Adoption clause 2, not a greenfield one: the items already existed, already had a parent, and already carried their own history.

Method and its ceiling

The tracker itself was built for real, and the ordering behaviour in finding 3 was verified live. The gh capability claims below are source-derived, not executed — no gh binary was available in the session, and api.github.com was repo-gated. They come from cli/cli source at pinned release tags, github/rest-api-description OpenAPI 1.1.4, and github/docs markdown — the artefacts the rendered doc sites are generated from, which is stronger provenance than the doc pages, but is still reading rather than running. One smoke test on a throwaway repo should confirm before anything is built on them.

---

What the draft got right

Worth recording first, because it is the larger share of the result.

• The Project issue type applied cleanly at creation and reads back reliably. Unit identity is the least troublesome carrier in the set.
• Appendix A's body skeleton was sufficient — nothing missing, nothing to mirror. Goal → stamp → Next: → phase table → gates → sequencing rationale → out-of-scope covered every fact the structure could not hold. We never once wanted a field it lacked.
• Order is positional, and the mechanism works end to end. See finding 3 — this is now verified rather than assumed.
• The restraint on dependencies proved correct at scale. Of 17 items, only four pairs were genuine hard blocks. "Edges are reserved for constraints that are real" is not merely defensible; soft ordering is the overwhelming majority, and position absorbed it without strain.

---

Findings

1. Creating a tracker is a destructive operation on whatever hierarchy the items already belonged to — silently

The ten items claimed from QuantEcon/meta#358 were detached from it by the act of linking them to the new tracker. Sub-issues are single-parent, so this is inherent. What makes it a finding is that it is silent and non-optional in the standard tooling: both gh issue edit P --add-sub-issue C and gh issue edit C --parent P pass replace_parent=true unconditionally, with no opt-out flag, while the REST endpoint exposes it as optional. Adding an item and stealing it from another tracker are the same gesture, indistinguishable at the call site.

The consequence in the field: meta#358 — the org's QEP-2 rollout tracker — was left holding only the one item that had been closed, and therefore reported {total: 1, completed: 1, percent_completed: 100}. A programme whose pilot has not started displayed as complete. No error, no warning; the rollup simply changed in a repository nobody was looking at while the new tracker was being built.

Repaired 2026-08-26: cli#20 is now a sub-issue of meta#358, and the closed item moved into cli#20 where its history is legible. meta#358 now reads 0% of 1 child.

2. Progress arithmetic breaks in two ways the draft does not cover

• Mixed-granularity children. A programme tracker holding one project tracker (17 items) alongside leaf issues weights them equally. The draft's existing rule — measure direct children only, never deeper — is right, but needs a companion: a tracker's direct children should be homogeneous in kind, all leaf work items or all project trackers. Mixing them makes the percentage meaningless rather than merely coarse.
• Closed-but-not-done children. sub_issues_summary.completed appears to count every closed child regardless of state_reason, so scope cut with not_planned or duplicate would read as progress. Unverified — a cheap addition to the smoke test.

Observed rather than theorised: meta#358 is a hybrid — part programme (delegating to cli), part project (org default labels is real leaf work), with four of its six sections tracked as body checkboxes. The draft's clean programme/project split has no slot for this shape, and this shape is what exists.

3. Order is the weakest-supported carrier — but the read-back contract holds ✅

Of the six carriers, order is the only one with no gh verb at all (a repo-wide grep for reprioriti|after_id|before_id across cli/cli returns zero matches). It is reachable only through gh api, with the most error-prone signature in the set: the parent is an issue number in the path while the children are integer database IDs in the body. Both are bare integers; the API cannot distinguish them. And no --json field yields an issue's database ID (fullDatabaseId exists on PullRequestFields only), so each reference costs a resolution call unless batched off the sub-issues list endpoint.

The open question was whether the read-back reflects position — the draft assigns order to "sub-issue list position", and the write mechanism being GA says nothing about the reader. Verified live on cli#20:

initial:              14,15,16,17,19,13,12,18,7,9,6,2,3,4,5,11,10,8
move #10 → first:     10,14,15,16,17,19,13,12,18,7,9,6,2,3,4,5,11,8
restore + place #8:   14,15,16,17,19,8,13,12,18,7,9,6,2,3,4,5,11,10

A reprioritize write is reflected in the list read-back, every other item holds its relative position, and the resulting order is neither ascending nor descending by issue number. QEP-6's ordering thesis has a verified reader. (Verified via REST; the UI and GraphQL orderings were not cross-checked.)

4. The status stamp is the only carrier where a second writer destroys the first's work

There is no partial-body update and no compare-and-swap on either the CLI or REST path — body writes are whole-replace. Two agents, or an agent and a human, refreshing the same tracker inside one window clobber each other, including body content unrelated to the stamp. The draft places the stamp in the body correctly — GitHub has no freshness primitive — but should say that a refresh is a read-modify-write inside a single turn, and that everything outside the stamp must survive it.

5. The milestone naming rule is vindicated on a second, purely mechanical ground

gh issue list --milestone runs strconv.ParseInt on its argument first, so a milestone titled "2026" is looked up as milestone number 2026 and fails. The draft already bans sequence tokens for identity reasons; purely numeric names break tooling for an unrelated reason and should be banned alongside them.

6. Templates reach further than expected, but cannot emit the draft's own stamp

type: is a real issue-template front-matter key (GA 2025-04-09), so a tracker template can stamp type: Project at creation — Adoption clause 1's identity requirement, satisfied for free. Templates provably cannot set milestone, parent/sub-issue edge, dependencies, or list order; those are post-creation for every producer.

The trap: an issue form converts field labels into body headings (### <label>), so it structurally cannot emit ## Where we stand (verified YYYY-MM-DD) — wrong heading level, and the date is dynamic while a label is static. A markdown template passes body text through verbatim and can still set type:. Two corollaries: markdown: elements in a form are never submitted, so skeleton text must be a prefilled textarea value; and the issues webhook payload carries no template identifier at all, so automation should key on issue.type.name — the type is the template's signature.

7. Two facts the draft leaves open, both with native answers

• Superseded items. "Closed" is not "done", and the list cannot hold a third state — encoding one would repeat the error the draft rejects for sequence tokens. GitHub already has the carrier: state_reason (completed / not_planned / duplicate with duplicate_of). The item keeps its place; why it closed is the item's business, not the list's. Subject to the caveat in finding 2.
• Parked vs. merely last. Parked-ness is not a fact to carry — it is a query: an open item with an open blocker is parked. Where the gate is an issue, a dependency edge says it exactly (--add-blocked-by is a core gh verb, so this is cheap). Where the gate is a decision, create the issue for the decision. Where it is phase-level, the body's gates section already covers it. Stating the derivation explicitly stops anyone inventing a carrier for it.

8. Scope: the order carrier has no known writer on GHES

The four sub-issue REST endpoints are absent from every GHES OpenAPI description 3.14–3.18 (verified against a control — ordinary issue paths are present in the same files). The native gh flags route through GraphQL and may work, but reordering exists only as a REST endpoint that is not in the GHES spec. The draft should say GitHub.com explicitly rather than let GHES support be inferred from a release note.

---

On the org's working assumption

The assumption under test was: any mechanism not supported by GitHub infrastructure must instead be carried in the issue body via templates.

On GitHub.com, that trigger never fires for any QEP-6 carrier. All six are natively readable and writable through gh. The body carries exactly one thing — the stamp — and does so because GitHub has no freshness primitive, by design rather than as fallback.

The test is worth keeping, with its two halves kept distinct: does GitHub have a carrier? (no → body, legitimately) versus can our tooling write it? (no → fix the tooling; do not move it to the body). Body-carriage of a natively-carried fact manufactures precisely the mirror the draft's Alternatives considered section rejects: the fact would live natively for producers that can write it and in prose for those that cannot, and the two would diverge — with the draft itself declaring the prose non-authoritative. cli#20 is currently in that degraded state, carrying its four constraints as body prose because the session's tool surface exposes no dependency write. That paragraph becomes a lie the moment anyone adds a real edge, and it is labelled as provisional for exactly that reason.

Tooling consequence

Most of the friction we first attributed to the platform was an artefact of one agent surface. gh gained native sub-issue support in v2.94.0, and dependencies and issue types are core verbs. What genuinely warrants a wrapper is narrow: number → database-id (with the batch form), milestone-title → number (state-aware), reorder-children, and a re-parent guard. QuantEcon/cli#11 has been rescoped accordingly — its original premise, that sub-issue and dependency linking needs bespoke helpers, no longer holds.

Open verification items

1. Does percent_completed count not_planned / duplicate closures as completed? (finding 2)
2. Is the template type: key silently dropped for openers without push access, as the REST API is?
3. Does a markdown template's type: key work as documented in prose?
4. Do the UI and GraphQL sub-issue orderings agree with the REST ordering verified in finding 3?

On the fixture. Adoption clause 4 calls for the dashboard ordering change to be verified "against a deliberate re-order on a public tracker." QuantEcon/cli is private, so cli#20 exercises the redaction path but cannot serve as that fixture. QuantEcon/meta#358 is public and now carries a child, so it is a candidate once it has enough children to re-order meaningfully.

[quantecon-services]

Proposed amendments to the QEP-6 draft

Eight edits, each pinned to the section it belongs in and written to match house style — compressed claims folded into existing sections, no new top-level section. Separable: include, drop, or defer each independently.

Process note: QEP-6 is Draft and unmerged, so these are ordinary edits to #18 and no version field may be added (check.mjs fails a new QEP that carries one).

1. Scope the standard to GitHub.com — ## Proposal opening, or §7 Scope

This QEP is scoped to GitHub.com. The sub-issue reordering endpoint is absent from GitHub Enterprise Server API descriptions through 3.18, so the ordering rule has no verified mechanism there.

2. Ban purely numeric milestone names — §4 Phases are milestones

Extend the existing naming rule with the mechanical reason:

Milestone names are descriptive ("Phase 1 — Foundations"), never sequence tokens, and never purely numeric: gh issue list --milestone parses its argument as a number first, so a milestone titled "2026" is looked up as milestone number 2026 and fails.

3. Re-parenting obligation — ## Adoption clause 2

The strongest single finding. Clause 2 currently says registered trackers "are brought into this layout by the conform tooling"; that tooling needs an explicit obligation:

Claiming a work item that already has a parent detaches it from that parent: sub-issue membership is single-parent, and both gh issue edit --add-sub-issue and --parent set replace_parent unconditionally, with no opt-out. The conform tooling MUST read an item's existing parent before linking, and re-link that parent to the new tracker or record the detachment. A programme tracker silently emptied this way reports its remaining closed children as complete.

4. Homogeneous children — §1 The unit, after the progress sentence

A tracker's direct children should be homogeneous in kind — all leaf work items, or all project trackers. Progress is a count over direct children, so mixing a multi-item project with leaf issues weights them equally and makes the percentage meaningless.

5. Superseded items and state_reason — §1 or §2

Closing a work item records whether it was done, not merely that it stopped: use state_reason (completed, not_planned, or duplicate with duplicate_of). A superseded item keeps its position; why it closed is recorded on the item, never as a third list state.

⚠️ Hold pending open verification item 1. If percent_completed counts not_planned as complete, this needs an added caveat rather than standing bare.

6. Parked-ness is derived — §3 Constraints are dependencies

Closes the gap the field test hit, with a rule that needs no new mechanism:

Whether an item is parked is derived, not carried: an open item with an open blocker is parked. Position states where an item sits in the plan; dependencies state whether it can start. Where a gate is a decision rather than an issue, create the issue for the decision rather than describing the park in prose.

7. Stamp concurrency — §5 The status stamp

Body writes are whole-replace: GitHub offers no partial update and no compare-and-swap. Refresh the stamp as a read-modify-write within a single turn, preserving all body content outside the stamp section; concurrent writers otherwise silently discard each other's edits.

8. Template guidance — ## Adoption clause 3, or an Appendix A note

A tracker is created from a markdown template, not an issue form: forms render field labels as ### headings and cannot emit the stamp's ## Where we stand (verified YYYY-MM-DD) form or its dynamic date. Templates can set type:, labels, assignees, and title; they cannot set milestone, parent, dependencies, or order, which are post-creation for every producer. Automation keys on issue.type.name — the webhook payload carries no template identifier.

---

Deliberately NOT proposed

• No change to the body/structure split. The field test found Appendix A's skeleton sufficient with nothing missing. One-fact-one-carrier held.
• No weakening of the dependency-restraint rule. At 17 items only four pairs were genuine hard blocks; the draft's restraint is correct at real scale.
• No programme-layer definition. The draft scopes it out deliberately. Findings 1 and 2 argue only for handling the transition into a project tracker, which is in scope — not for defining the layer above.

---

Generated by Claude Code

[quantecon-services]

Verification item 1 — settled, and it changes amendment 5

Tested live against QuantEcon/cli#20 on 2026-08-26 (probe: QuantEcon/cli#21).

Step	sub_issues_summary
baseline (18 children, one closed completed)	{total: 18, completed: 1, percent_completed: 5}
probe attached, still open	{total: 19, completed: 1, percent_completed: 5}
probe closed as not_planned	{total: 19, completed: 2, percent_completed: 10}
probe detached	{total: 18, completed: 1, percent_completed: 5}

percent_completed counts a not_planned closure as completed. GitHub's progress arithmetic does not distinguish work finished from work dropped — so a tracker whose scope is cut reads as more complete than it is, and the more scope you drop, the better it looks. This is the same failure class as the meta#358 100% misreport in the report above: an honest structural operation producing a dishonest number.

Revised amendment 5

The original wording — keep a superseded item in place, record state_reason — is now known to inflate the parent's percentage. Two ways out:

• (a) Keep dropped items in the list and caveat the number. Requires every consumer to re-derive progress from state_reason rather than trusting percent_completed. The dashboard could; a human glancing at the sidebar will not.
• (b) Dropped items leave the list. ✅ Recommended. Membership is the sub-issue edge, and an item that is no longer part of the plan is no longer a member. This keeps the native percentage honest with no consumer changes and no reliance on GitHub distinguishing the two closure kinds.

Option (b) also sharpens the draft's existing rule rather than complicating it. Proposed replacement text for §1 or §2:

Completed items keep their place; the list stays readable as the plan with progress visible in it. An item dropped from the plan — closed not_planned, or superseded — is removed from the sub-issue list instead: membership is the plan, and work no longer in the plan is not a member. The issue itself persists with its own state_reason and its cross-references intact, so the record is not lost; only the membership edge goes. This matters mechanically, not just semantically: sub_issues_summary.completed counts every closed child regardless of state_reason, so a dropped item left in place inflates the tracker's reported progress.

The state_reason guidance still holds for why an item closed (completed / not_planned / duplicate with duplicate_of) — it is the right native carrier, and it is what tells a reader which of the two treatments applies. What changes is that it is no longer sufficient on its own.

Note this is exactly what was done with the probe: attached, closed not_planned, then detached — leaving cli#20 back at a truthful 5%.

Remaining open items

Items 2 and 3 (template type: behaviour) are not testable via API — issue templates apply through the UI issue-creation path, and the permission case needs a second, lower-privileged identity. They need a human with a throwaway repo. Item 4 (UI/GraphQL vs REST ordering) is also unresolved here: this session's GitHub access is mediated by an MCP server with no GraphQL passthrough, and direct api.github.com calls are blocked by the session's egress proxy irrespective of credentials.

---

Generated by Claude Code

[mmcky]

Results for the #20 follow-up items (executed 2026-08-27)

Environment: gh 2.98.0, authenticated shell (mmcky). Verdicts per item; commands and read-backs as specified in #20.

1. Dependency edges — written and verified. All four edges exist on QuantEcon/cli (3 ← 2, 4 ← 3, 10 ← 9, 6 ← 12), confirmed via blockedBy read-back on each. --add-blocked-by accepted plain issue numbers; the database-id fallback was not needed. One residue: deleting the "Constraints — pending native edges" paragraph from the cli tracker body was blocked by this session's permission layer (issue-body overwrite denied); the edited body is prepared and the deletion is pending a permitted run.

2. Ordering cross-check — REST and GraphQL agree, and match expected. Both surfaces return [14,15,16,17,19,8,13,12,18,7,9,6,2,3,4,5,11,10], identical to the expected order in #20. The third surface (rendered UI) was not independently checked — the repo is private and this session has no browser; one human glance at the tracker remains. On two-of-three agreement, finding 3 stays closed.

3. Markdown template type: key — fixture ready, UI submission remains; two adjacent facts established. Throwaway repo QuantEcon/qep6-template-test now carries .github/ISSUE_TEMPLATE/tracker.md with type: Project front matter and the Appendix A skeleton, and the org defines a Project issue type. What could be established without a browser: (a) non-interactive gh issue create cannot apply a template at all — -T only seeds the interactive prompt, and non-interactive runs demand explicit --title/--body — so scripted tracker creation must pass --type explicitly no matter what the template key does; (b) explicit --type Project works and the skeleton arrives verbatim, ## Where we stand (verified YYYY-MM-DD) intact at H2 (probe: QuantEcon/qep6-template-test#1). To finish the item: open the template chooser at https://github.com/QuantEcon/qep6-template-test/issues/new?template=tracker.md, submit, then gh issue view <N> --repo QuantEcon/qep6-template-test --json issueType. Delete the throwaway repo afterwards (this session's token lacks delete_repo).

4. Low-permission opener — impractical here (single identity, and it is an org admin). Per #20's stated fallback, amendment 8 should mandate a post-creation read-back assertion (gh issue view N --json issueType) rather than trusting the template. Item 3's finding (a) points the same way independently: since scripted creation can never route through a template, the read-back is required regardless of how the UI question lands.

[mmcky]

Follow-up results, part 2 (2026-08-27) — items 2 and 3 closed

Item 2 — closed on all three surfaces. mmcky confirmed the rendered UI order on the cli tracker matches the REST and GraphQL read-backs exactly: [14,15,16,17,19,8,13,12,18,7,9,6,2,3,4,5,11,10] on all three. List position is an unambiguous order carrier; finding 3 stays closed. (Item 1 is also now fully complete — the prose constraints paragraph is deleted from the tracker body, leaving the native edges as sole authority.)

Item 3 — closed: the markdown template type: key works. An issue opened through the web template chooser in QuantEcon/qep6-template-test (probe: issue 2 there, opened by an admin identity) arrived with issueType: Project and the Appendix A skeleton verbatim — ## Where we stand (verified YYYY-MM-DD) intact at H2, sidebar Type prefilled before submission. The report's recommendation of markdown templates for trackers stands. The part-1 caveat is unchanged: non-interactive gh issue create never applies templates, so scripted creation still needs explicit --type plus a read-back.

Item 4 — delegated, result pending. A low-permission run as quantecon-services (being granted read on the throwaway repo) is queued in a separate session and will report here. Whatever it finds, part 1's conclusion for amendment 8 holds: mandate a post-creation issueType read-back, since scripted creation cannot route through a template at all.

The throwaway repo is retained until item 4's run completes, then deleted.

[quantecon-services]

Item 4 — closed as won't-test (no result to report)

Closing the loop this thread opened: part 2 promised that the delegated low-permission run as quantecon-services would report its result here. There is no result — item 4 is closed unrun, and the rationale is recorded on #20.

The short form: both possible read-back values (Project or null) lead to the same action, because the post-creation read-back is already mandated on two independent grounds — non-interactive gh issue create never applies a template at all, and REST documents type as silently dropped without push access. A test whose branches produce identical actions changes nothing.

The delegated run also could not have answered it: the session's GitHub access is scoped by a repository allowlist, and add_repo attaches a repo for API use only at push level. Granting push to make the attach succeed would have removed the very condition under test. The fixture repo has since been deleted, so the browser path is no longer available either.

Still open here, pending a call

Two related edits to the amendments above, which I have not made:

1. Amendment 8 gains the read-back mandate — proposed wording on #20, including an implementation note that the assertion must read the issue itself rather than validate against GET /orgs/{org}/issue-types, which returns 403 Resource not accessible by integration for app identities even where the repo-scoped read succeeds.
2. The field report's "untyped = untriaged" line is the one claim that leaned on item 4. Recommend dropping it as a load-bearing justification for type-over-label rather than testing it — that choice stands on native, structured, org-wide types versus repo-local labels.

Happy to draft both as a single follow-up once the second is decided.

---

Generated by Claude Code

[quantecon-services]

Amendment 9 — a membership criterion (new finding, 2026-08-27)

The field test produced one more finding, and it is the sharpest of the set because the standard could not detect the error.

What happened

cli#20 was built by linking every open issue in the repo — 17 items — and it passed as a conformant tracker: Project type, native sub-issue work items, stamp, plan-ordered list, order-free names. Every rule in the draft was satisfied.

It was not a project. It was a repository sweep with a goal written afterwards to fit it. On review, 5 of 19 items did not belong: three were a separate capability (repo settings / profiles / onboarding), one was packaging hygiene, and one was tooling for QEP-6 itself — an item that came out of this field test and had been swept into the project under test.

Why the draft cannot catch it

Every mention of membership in QEP-6 specifies where it is recorded:

Its work items are its direct native sub-issues… Membership lives in the sub-issue edges: body checkboxes, plan tables, and legacy tasklists are never work items.

That is a carrier rule. The draft never says what qualifies an issue as a work item. §1 requires a goal and definition of done in the body, but never connects them to membership as a test — so a tracker whose goal is written to cover its roster is fully conformant, and the goal silently becomes a description of the list rather than a constraint on it.

This matters more with agents than with people: an agent asked to "set up a tracker for this repo" will reach for the issue list, because the standard gives it no reason not to.

Proposed text — §1 The unit, after the membership sentence

An issue is a work item of a project if closing it advances the project's definition of done. If the definition of done can be met without it, it is not a member — however much it shares a repository, a theme, or an owner. If the goal must be widened to justify an item's membership, the item is not a member. Not every issue belongs to a project; an unparented issue is the normal case, not a gap to be filled.

The emphasised sentence is the diagnostic that would have caught this one. The final sentence matters independently: the instinct to parent everything is what produces sweeps.

Companion smell, worth a sentence in §4

A phase whose intent describes a capability area rather than a step toward done is probably holding non-members. In cli#20 the offending phase was "Grow the surface — settings, profiles, onboarding on the same conventions": four of its five items were non-members, and the phase boundary turned out to be the membership boundary. Phases are a diagnostic for membership, not merely a grouping.

Second-order effect

Removing the non-members shrank the tracker's constraint list from four dependency edges to two. The two that went (#3←#2, #4←#3) were real constraints — but between items belonging to a different project, so they were never this tracker's to carry. Bad membership had smuggled in bad constraints, which is an argument that the membership rule protects the dependency rule rather than being independent of it.

Applied

cli#20 is now 14 items with a terminal goal; the review is recorded in its comment thread. The five removed items are unparented, and three of them (#2/#3/#4) cohere as a separate project with their own dependency chain — a tracker for them when that work starts, not before.

---

Generated by Claude Code

[quantecon-services]

Amendment 10 — cross-project relationships: Gates and Related work

Follows from amendment 9. Once membership is owned by exactly one project, the question "what about work in other projects?" becomes live — and the draft has no answer for it. Two sections, but they carry different kinds of fact and want different rules.

Single-parent is affirmed, not worked around. It is what makes progress arithmetic sound: multi-parent would double-count an item across trackers with no non-arbitrary way to split credit. One owner is the reason the number means anything.

1. Gates — extend the existing concept, but prefer the native edge

The draft currently says phase-level gates are stated in the body, "not encoded as pairwise edges". That reasoning is sound for phases and does not transfer to projects:

• a phase has no issue representing it, so a phase gate would need N×M edges — hence the body
• a project is an issue: the tracker. gh issue edit <trackerB> --add-blocked-by <trackerA> expresses "project B waits on project A" in one edge, on the exact objects involved

Item-level cross-project gates are likewise already native — dependencies are independent of the parent hierarchy, so an item in B can be blocked-by an item in A directly, across repositories within an owner.

So a Gates section that states a cross-project constraint mirrors an available carrier, which Alternatives considered rejects. Proposed rule:

Gates cover phase-level and project-level constraints. A phase-level gate is stated in the body, because no object represents a phase. A project-level gate MUST also carry the native dependency edge between the two tracker issues; the body then carries only the rationale — why the gate exists, what its exit criterion means, and what is risked by lifting it early.

2. Related work — a genuine body-only fact

GitHub records that a mention happened — cross-references are automatic, unordered, and indistinguishable from someone linking in passing. It has no carrier for "these two projects are deliberately related, and here is how." That is an assertion, and assertions with no native carrier are what the body is for.

Related work (optional) names sibling projects and, in one line each, how they relate — informs, spawned by, shares an engine, competes for the same surface. Never work items: listing individual issues is either the sub-issue list restated or dependency prose, both already forbidden.

The "projects, not items" bound is what keeps this from decaying into the mirror the draft spends its Alternatives section rejecting.

Field evidence for why it earns a slot: QuantEcon/cli#11 exists because cli#20's field test surfaced it. When amendment 9's review removed #11 from that tracker, the only trace of that provenance disappeared — a real relationship with nowhere to live.

3. Why name them rather than rely on free sections

The draft already permits this: "Free sections (Findings, Premises, Notes) may follow — the skeleton is a floor, not a ceiling." So no amendment is strictly needed to allow either section.

What naming them buys is convention instead of permission, and amendment 9 supplies the argument: agents fill the slots that exist and invent none. The repository sweep happened because nothing told me not to; cross-project context will go unrecorded for the same reason. Where the producers include automation, an unnamed affordance is an unused one.

Proposed Appendix A addition

**Gates:** … (phase-level; project-level gates also carry a tracker-to-tracker
dependency edge — state only the rationale here)

## Related work

- [Project name](tracker-url) — one line on the relationship.

Unverified

Amendment 10 rests on a claim I have asserted but not tested: that a native dependency edge between two tracker issues is accepted and renders as a blocker. It follows from dependencies being hierarchy-independent, but no session here could write a dependency edge to check. Added to #20 as a verification item — if it fails, the project-level half of §1 collapses back to body prose.

---

Generated by Claude Code

[quantecon-services]

Addendum to amendment 9 — a heuristic for finding project boundaries

Not a change to the proposed text. Amendment 9 supplies the test for whether an item belongs to a given project; this is a practical way to find where the project boundaries are in the first place, which came out of applying the amendment to a tool repository.

The pattern

In a repository that builds tooling for org standards, organise trackers one per standard being delivered — "deliver what QEP-N needs" — rather than keeping a standing tracker ("compliance tooling", "audit tooling") that accretes items as each new QEP lands.

Four reasons, all of which are amendment 9's own arguments applied one level up:

1. The definition of done terminates. "Deliver what QEP-2 requires" ends. "Compliance tooling" never does — the goal recedes as fast as it is approached, which is amendment 9's unreachable-goal failure institutionalised rather than accidental.
2. Membership is arbitrated externally. "Does QEP-2 require this?" is settled by a ratified document that cannot be quietly widened to fit the roster. Amendment 9's diagnostic — if the goal must be widened to admit the item, it is not a member — only has teeth when the goal is anchored outside the tracker.
3. Progress means something. A per-QEP tracker's percentage has a fixed denominator. A standing tracker's grows whenever a QEP is accepted, making the number the same class of dishonest as the not_planned inflation recorded above.
4. Closure is observable. "QEP-2 tooling delivered" is a fact the adoption programme can act on. A standing tracker never reports it.

The corollary that makes single-parent workable

A standard will often impose a requirement on work that already exists for its own reasons. Since membership is single-parent, two projects cannot share that issue.

When a standard imposes a requirement on existing work, file the requirement as its own issue and let the standard's project own that. Do not re-parent the host issue.

Live case: QuantEcon/cli#4 (qe gh repo onboard) predates QEP-3 and exists to automate first-time repo setup. Once QEP-3 is accepted, onboarding must also validate the repo name against its type registry. A QEP-3 delivery project should own "validate repo names against the QEP-3 registry" — not #4, which keeps its own home. Without this rule, every accepted standard pulls host issues away from wherever they were, and single-parent turns into a tug-of-war.

Limits, stated so this is not over-applied

• Not every project descends from a standard. In the same repository, packaging, a README defect and a structured-output feature answer to no QEP and stay unparented — the normal case, per amendment 9's closing sentence.
• Not every standard spawns a project. A process QEP has nothing to adopt.
• This is a heuristic, not a replacement for the test. Membership remains "advances this project's definition of done", never "mentions QEP-N" — otherwise the result is a QEP-shaped sweep, which is the original error wearing better clothes.

Where this belongs

Not in QEP-6. §7 puts surrounding practice in the qe skills rather than the standard, and this is practice. Recorded here because it is evidence for amendment 9 rather than a separate proposal — the amendment's test is what makes the heuristic safe to use.

---

Generated by Claude Code

[quantecon-services]

Amendment 10, field results — the first two-project repository (2026-08-27)

Amendment 10 was proposed from a hypothetical. QuantEcon/cli now carries two project trackers, so it has been exercised. Three results, one of which weakens the amendment as written.

What was built

QuantEcon/cli#20 — deliver the QEP-2 label migration, 11 items, four phases.
QuantEcon/cli#24 — test infrastructure for production readiness, 6 items, two phases.

#24 was not new work invented to make a second project. It was an existing strategy issue that had been written as a sub-issue of #20 and was already tracker-shaped — goal, tiers, sequencing, enumerated work — but carried no Project type and no sub-issues. Amendment 9's test is what exposed it: closing #20's definition of done does not require any of the testing work, and the testing work serves every future change rather than QEP-2 specifically. It was promoted rather than created.

Two trackers in one repository worked with no collision, no ambiguity about which owned what, and no pressure on single-parent. The Out of scope sections in both bodies do the disambiguating work, and each names the other by number.

1. ⚠️ The gate that emerged was phase-level, not project-level — §1's project half is unexercised

This is the finding that matters. Amendment 10 §1 argued that a project-level gate MUST carry the native tracker-to-tracker dependency edge, because a project is an issue and one edge expresses it exactly.

The first genuine case produced no project-level gate. What the work actually needs is:

Nothing in #20's Safe migration phase runs before #24's offline phase is complete.

Both halves are phases. #20's One source of truth phase can proceed in full while #24 is untouched, and #24's integration phase is gated on an org action and a credential decision, not on #20 at all. A tracker-to-tracker edge — #20 blocked-by #24 — would have been wrong: it asserts the whole project waits, which is false, and it would have parked #20 in every consumer that derives parked-ness from open blockers (amendment 6). The precision that amendment 10 §1 claims for the native edge is precision about the wrong objects.

So: project-level gates may be considerably rarer than §1 assumes, with phase-level the common shape. The reasoning in §1 still stands where a whole project genuinely waits on a whole project — I have not found a counter-argument, only an absence of instances. But it should not be written as though it were the default case. Suggested softening of the §1 rule:

Gates cover phase-level and project-level constraints. Most cross-project gates are phase-level in practice — one phase of A waits on one phase of B, while the rest of both proceeds — and are stated in the body, because no object represents a phase. Where a project genuinely waits on a project in its entirety, that gate MUST also carry the native dependency edge between the two tracker issues, with the body carrying only the rationale. State the constraint at the granularity that is actually true: a tracker-to-tracker edge asserts that nothing in A may start, and parks A wholesale in any consumer deriving parked-ness from blockers.

The last sentence is the field lesson. Over-coarse gating is not a harmless approximation once amendment 6 makes parked-ness a derived query.

Consequence for #20 item 5. That item asks whether a native dependency edge between two tracker issues is accepted and renders as a blocker. This exercise does not test it — there was no occasion to write one. Item 5 stays open, and it is now less urgent: if it fails, the half of §1 that collapses is the half nothing has yet needed.

2. ✅ Related work earned its slot immediately, and needs a placement rule

§2 predicted the section would carry relationships with no native home. Both trackers used it on the first attempt, for two distinct kinds of fact:

• The gate's counterpart. Discussion: a Programme QEP — codifying the grammar's top tier, and ordering projects within it #24's entry names QEP-6 field test: follow-up actions needing a gh-equipped environment #20 and states that this project gates it. QEP-6 field test: follow-up actions needing a gh-equipped environment #20's entry names Discussion: a Programme QEP — codifying the grammar's top tier, and ordering projects within it #24 and states that it is gated.
• A coupling with no direction at all. QEP idea: Contributor registry, AI-use attestation, and a PR gate #12 (read the schema from qeps) and #27 (schema lockstep test) sit in different projects and interact — if QEP idea: Contributor registry, AI-use attestation, and a PR gate #12 lands first, #27 becomes a check that the pin resolves rather than a comparison of two copies — but neither blocks the other and either order works. This is not a dependency, not a gate, and not expressible in any native carrier. It is exactly the assertion §2 was written for.

Writing both sides surfaced a gap the amendment does not cover: where does a gate's text live when two bodies could hold it? Restating the constraint in both is the mirror the draft rejects, and the two copies will diverge. The rule that fell out of doing it:

A gate is stated once, in the body of the project it constrains — the side that must wait. The other project's Related work entry names the relationship and points at where the gate is stated; it does not restate the constraint.

Applied: the gate text lives in #20 (which waits), and #24's Related work entry says the gate is recorded there. This is one-fact-one-carrier applied to the new sections, and without it the two sections generate exactly the duplication the rest of the standard forbids.

Note the §2 bound held under pressure. The #12 ↔ #27 coupling is between work items, not projects, and §2 forbids naming items in Related work. Both entries name it anyway — as the relationship between the two projects, with the item numbers as the specifics. That is arguably a violation of the letter. I have left it in both bodies rather than quietly conforming, because it is the more useful record and the honest test of whether the bound is drawn in the right place. If §2 is adopted as written, these two lines should be deleted, and something real is lost when they are.

3. A project tracker with no parent is fine, and progress arithmetic is not comparable across membership changes

Two smaller observations.

#24 is unparented. #20 is a sub-issue of QuantEcon/meta#358 (the QEP-2 adoption programme); #24 answers to no programme, because it answers to no QEP. This is the limit case the amendment-9 addendum explicitly allowed — "not every project descends from a standard" — and it held: a project tracker sitting at the root of the hierarchy reads perfectly well and loses nothing. Worth stating in the draft that an unparented project tracker is normal, for the same reason amendment 9 says an unparented issue is normal: agents fill slots that exist, and an empty parent field reads as an omission unless the standard says otherwise.

A denominator change moves the percentage with no work done. #20 went from 14 items to 11 as the testing work moved to #24. Its one completed child was unaffected. Its reported progress went from 7% to 9%.

Nothing happened. The tracker got more honest and simultaneously reported more progress. This is the same arithmetic that produced the not_planned inflation recorded above, from the opposite direction — there the numerator was dishonest, here the denominator moved — and it is a second reason not to read percent_completed as a trend. A tracker's percentage is comparable to itself only across a stable membership; any conformance operation on the roster resets the baseline. Worth one sentence wherever finding 2's progress rules land:

percent_completed is a snapshot over current direct children, not a time series. Membership changes — items dropped, items moved to another project, a tracker split — move the number without work occurring. Do not read progress across a membership change as progress.

Status of amendment 10

§2 (Related work) — strengthened, plus the placement rule in result 2 and the open question about its work-item bound.
§1 (Gates) — softened, per result 1. The project-level half remains both unexercised and unverified.

---

Generated by Claude Code

[quantecon-services]

Amendment 7 has a hazard I did not anticipate: the read half of read-modify-write can be lossy

Found while about to correct a stale sentence in #20's body. Caught before writing, not after.

What happened

Amendment 7 mandates that a stamp refresh be a read-modify-write inside a single turn, preserving all body content outside the stamp. That is correct as far as it goes, and it silently assumes the read returns what is stored.

It does not, on at least one agent surface. Reading this very issue's body through the GitHub MCP server returns finding 6's template sentence as:

converts field labels into body headings (`### `)

The stored body, confirmed by fetching the rendered page, is:

converts field labels into body headings (`### <label>`)

The <label> placeholder is gone from the read. The read path HTML-sanitises the body: " and ' and > come back as " / ' / >, and anything shaped like an unknown HTML tag — <label>, <parent>, <child>, <N> — is dropped entirely, without trace or warning. #20's body loses three placeholders from its gh snippet the same way, and there is no marker in the returned text to indicate anything was removed.

A read-modify-write on that basis is a silent content-destroying operation. It would have deleted every angle-bracket placeholder in the body while faithfully preserving everything else — the failure mode amendment 7 exists to prevent, arriving through the half of the operation the amendment does not examine.

Nothing has been damaged: no body in this field test was produced by round-tripping, and the correction to #20 was made as a comment instead. The stale sentence in its body stays stale rather than being fixed by an unsafe mechanism, which is the right trade.

Proposed addition to amendment 7

The read half of a read-modify-write must be lossless. Agent surfaces may return a sanitised rendering of an issue body rather than its source: HTML entities substituted, and anything resembling an HTML tag — <placeholder> in a code snippet, for example — silently removed. Writing such a read back destroys content while appearing to preserve it. Verify that a body read round-trips byte-for-byte before performing any read-modify-write against it, and where it does not, treat the body as append-only from that surface and record the correction as a comment.

Two wider consequences

1. It generalises past the stamp. Amendment 7 is scoped to the status stamp, because that is where two writers collide. This hazard applies to every body write from an agent surface — a conform tool rewriting a phase table, an automation refreshing Next:, anything. The rule belongs wherever the draft first says a body may be rewritten programmatically, not only in §5.

2. It sharpens the org's working assumption test. The field report drew the distinction: does GitHub have a carrier? (no → body) versus can our tooling write it? (no → fix the tooling). Here is a third case neither half covers — the tooling can write it, and can read it, but the read and the write are not inverses. That is worse than an inability to write, because inability announces itself and this does not. The body is the one carrier where this can happen at all: every other QEP-6 carrier is a structured field that round-trips as a typed value.

Which is an argument the draft can use directly. The body's weakness is not that it is prose — it is that it is the only carrier without a schema, so no layer between GitHub and the agent can tell a faithful copy from a mangled one. Every fact moved out of the body and into a native carrier removes it from this failure class, and that is a better reason for one-fact-one-carrier than tidiness.

---

Generated by Claude Code