Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242)

Closing ref inventory — disposition every ref consumer and producer against the ref contract

Phase 4 of the aggregator ref-contract design (design issue #6242; design doc files/designs/code-aggregator-ref-contract.md in the keep-the-four-repos-healthy goal workspace). Gated on Phases 1–3 of #6242 (#6174 + #6195, #6210 + #6211, #6224).

The contract this phase closes out (from #6242): a ref is an annotation, not identity; validity is isValidRef only; an invalid ref is dropped at the consumption step beside its gate (the item survives, the drop is traced), producers mint only valid refs, and rendering/deriving reaches refUrl for stored/feed-derived refs only through the safe-link helper — never a throw.

Scope

An inventory of every refUrl( / parseRef( consumer in pm-stack/aggregator/src (25 refUrl sites at the design audit HEAD, origin/main 955ed23) and every ref-carrying gate, scrape, derivation and store path in pm-stack/aggregator + pm-stack/projector, each dispositioned against the contract with file:line evidence: gate-dropped (rule 2) / producer-filtered (rule 3) / safe-helper (rule 4) / internal-constructed-safe (code-built refs, parseRef throw retained) / fixed-in-this-phase.
The contract statement landed in pm-stack/aggregator/src/model.ts beside the pm-stack(aggregator): validateNewComment/validateNewAction accept ref keys parseRef rejects (GH_REF number unbounded) #4952 isValidRef comment, so the disposition rules live where the validity rule lives.
Required dispositions (name each explicitly on this issue, with the evidence or the follow-up issue if one is owed):
1. queue-view.ts:113,139 — stored refs reaching refUrl unguarded.
2. sources/live.ts:368 — the session-row row.url ?? refUrl(row.ref, …) fallback.
3. comments.ts:494 — githubCommentUrl against the post-pm-stack(aggregator): validateNewComment/validateNewAction accept ref keys parseRef rejects (GH_REF number unbounded) #4952 store-load gates: is every stored comment's githubRef now guaranteed valid, or is a guard owed?
4. render.ts:3574 — ensure()'s refUrl fallback in the overview path (post-pm-stack(aggregator): overview front door throws on a lined-up task with a non-GitHub ref — reconciledInProgress reaches refUrl unguarded #6205 state), and render.ts:6756.
5. sessionRecordLine (render.ts:1912) — align its omit-the-link treatment with rule 4's plain-text treatment, or record why this surface differs.
6. A recount of stored pmp_links rows (projector registry) whose ref fails isValidRef: how many exist, and confirmation that Phase 2's consumption filtering disarms them (no hand-deletion required for safety).
7. Any raw matchAll ref scrape outside titleRefs / refsInText (rule 3) — the pm-stack(aggregator): overview front door throws on a lined-up task with a non-GitHub ref — reconciledInProgress reaches refUrl unguarded #6205 fix's second vector (a title re-scrape beside refsInText) is the shape to grep for.
Probe evidence: for each surface this phase changes, a bad-ref case (unsafe-integer and non-GitHub forms) rendering/deriving without a throw, with a valid-ref control unchanged.

Acceptance criteria

The inventory is posted on this issue (or in the model.ts contract statement it lands) with a disposition per site and no site left unclassified.
The contract statement is on main in model.ts beside the pm-stack(aggregator): validateNewComment/validateNewAction accept ref keys parseRef rejects (GH_REF number unbounded) #4952 comment.
All seven required dispositions are recorded with evidence or a linked follow-up issue.
Any site fixed in this phase carries pinning tests in the aggregator suite; the bun test aggregator suite passes (via CI per fleet policy).
The design issue A ref that cannot link is plain text — one ref contract for the aggregator (design) #6242 is commented with the closing state so its acceptance can be checked off.

CODE-1826

🤖 Agent note · design phase filed

Agent: design architect (repo-design-architect-code), pass 55
Task: this issue is Phase 4 (closing inventory) of design A ref that cannot link is plain text — one ref contract for the aggregator (design) #6242, "A ref that cannot link is plain text — one ref contract for the aggregator" (linked as its sub-issue). It is GATED on Phases 1–3 (pm-stack(aggregator): /today render 500s on a lined-up task with a non-GitHub ref — objectives call refUrl unguarded and the section gate never checks linedUp ref #6174 + pm-stack(aggregator): one lined-up task with a non-GitHub ref silently deletes the board's whole in-flight lane — inFlightBoardItems parseRef throws into an unlogged catch #6195, pm-stack(aggregator): board render throws on a lined-up task whose title carries an unsafe-integer ref in a non-first link — titleRefs mints refs parseRef rejects, inFlightBoardItems validates only the first #6210 + pm-stack(aggregator): a projector registry link with an unsafe-integer ref 500s /search and the project page — projector gate admits it, projectorLinks never validates, renderSearch + roadmap rows call refUrl unguarded #6211, pm-stack(aggregator): a pool item with an invalid blockedBy/blocks edge 500s the project page and throws the brief — isProjectPoolItem validates edges by shape only, brief + pool-graph + epic-graph call refUrl unguarded #6224) and carries status/blocked for that reason.
Queue: triage packet enqueued this run as task 10567 in queue repo-health-code-pilot (verified by dedupe re-read: same row, status=queued, attempts=0, last_error=null).
Expectation: triage records the gating and keeps the issue blocked until Phases 1–3 land, then enqueues the implementation follow-up with the acceptance intact — do not start the inventory early, and do not re-litigate the contract rules recorded on A ref that cannot link is plain text — one ref contract for the aggregator (design) #6242.
Design doc: files/designs/code-aggregator-ref-contract.md (keep-the-four-repos-healthy goal workspace).

🤖 Agent note · state: handed off

Agent: queue worker (repo-worker-code), lane code-o
Session / ID: task 10567
Found via: queue claim
Task: triage of issue Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242) #6243 is assigned to the opencode execution lane — handed off to the opencode claimant, which launches a bound session to drive task 10567 to its terminal state.
Expectation: claimant launches the bound opencode session during the park window; if unbound at lease expiry, task 10567 returns to the queue.
Links: issue Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242) #6243

Agent note - handed off

Agent: opencode claimant (opencode-claimant)
Session / ID: queue task 10567; bound session ses_e5e5390d1d9ffeElqscEdtvx39
Found via: queue task handoff on the opencode execution lane
Task: Triage Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242) #6243 — Phase 4 closing ref inventory of design A ref that cannot link is plain text — one ref contract for the aggregator (design) #6242
Expectation: the bound worker session works task 10567 to a terminal queue state and must not claim another task. It revalidates the issue/PR before acting.
Links: Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242) #6243

Triage — scope confirmed; Phase 4 remains gated (2026-11-05)

I confirmed the scope against design #6242 and the current main ref at 00a294a. The design's audit HEAD 955ed23 and its 25 refUrl count are historical; the implementation follow-up must recount at its current HEAD. This triage does not start the inventory.

Phases 1–3 have not all landed:

Phase 1: pm-stack(aggregator): /today render 500s on a lined-up task with a non-GitHub ref — objectives call refUrl unguarded and the section gate never checks linedUp ref #6174 and pm-stack(aggregator): one lined-up task with a non-GitHub ref silently deletes the board's whole in-flight lane — inFlightBoardItems parseRef throws into an unlogged catch #6195 are still open. Merged PR pm-stack(aggregator): guard reconciledInProgress against non-GitHub lined-up refs (#6205) #6207 is the separate pm-stack(aggregator): overview front door throws on a lined-up task with a non-GitHub ref — reconciledInProgress reaches refUrl unguarded #6205 fix and does not close these phase issues.
Phase 2: partial. pm-stack(aggregator): a projector registry link with an unsafe-integer ref 500s /search and the project page — projector gate admits it, projectorLinks never validates, renderSearch + roadmap rows call refUrl unguarded #6211 is closed by merged PR fix(pm-stack): drop unsafe-integer registry refs at projectorLinks and the POST /links gate (#6211) #6244; pm-stack(aggregator): board render throws on a lined-up task whose title carries an unsafe-integer ref in a non-first link — titleRefs mints refs parseRef rejects, inFlightBoardItems validates only the first #6210 remains open with no linked PR.
Phase 3: pm-stack(aggregator): a pool item with an invalid blockedBy/blocks edge 500s the project page and throws the brief — isProjectPoolItem validates edges by shape only, brief + pool-graph + epic-graph call refUrl unguarded #6224 remains open; its implementation copy Fix #6224: pm-stack(aggregator): a pool item with an invalid blockedBy/blocks edge #6226 is open/claimed with no PR.

So Phase 4 is still gated. I left this issue open and changed its labels to status/blocked + queue/blocked. The phase is independently implementable once unblocked; no rescope or split is justified now. The implementation follow-up packet is deferred until Phases 1–3 land, per the design gate; do not begin the inventory before then.

When the gate clears, enqueue/split the implementation with this issue's acceptance intact: inventory every aggregator refUrl and parseRef consumer and every ref-carrying gate/scrape/derivation/store path in aggregator + projector; land the contract beside #4952 in model.ts; explicitly disposition (1) queue-view.ts:113,139, (2) sources/live.ts:368, (3) comments.ts:494, (4) render.ts:3574 and :6756, (5) sessionRecordLine, (6) invalid stored pmp_links recount, and (7) raw matchAll ref scrapes; post the inventory here and closing state on #6242. Any owed follow-up must be linked. For changed surfaces, pin unsafe-integer and non-GitHub bad-ref cases with valid-ref controls; run bun test in pm-stack/aggregator via CI (and bun test in pm-stack/projector if changed), per the CI policy. No builds/tests are run for this triage.

Navigation Menu

Repository navigation

Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242) #6243

Closing ref inventory — disposition every ref consumer and producer against the ref contract

Scope

Acceptance criteria

Triage — scope confirmed; Phase 4 remains gated (2026-11-05)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Closing ref inventory — disposition every ref consumer and producer against the ref contract (Phase 4 of #6242) #6243

Description

Closing ref inventory — disposition every ref consumer and producer against the ref contract

Scope

Acceptance criteria

Activity

developing-today commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

Triage — scope confirmed; Phase 4 remains gated (2026-11-05)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions