KNOWN_ISSUES.md maintains a second issue register parallel to this tracker: entries carry their own IDs (IOS-PUSH-001, IOS-PERF-012, …), live in a mandatory-load index plus routed detail files under Companion/Process/Current/KnownIssues/, and are mirrored into GitHub issues whose titles repeat the register ID. The register then maps back the other way, including "retired mapping" lines for entries whose issues are closed.
Maintaining both halves costs real effort and creates drift: two places to update, two places to search, and a mapping table that has to be hand-maintained in a file every agent loads on every task. The tracker alone can carry this.
Proposed migration
- Resolved entries → close the corresponding GitHub issue with the disposition recorded in the closing comment.
- Accepted limitations / deliberately-unfixed entries → keep the issue open or closed as appropriate, labeled
wontfix, with the acceptance rationale and any re-escalation fence in the body. Several register entries exist specifically as fences against re-litigating a decision (for example, an accepted limitation that may only be re-escalated if a new condition is demonstrated) — that fencing language must survive the move verbatim, since it is the whole reason the entry exists.
- Still-open defects → ordinary open issues with appropriate labels.
- Retire
KNOWN_ISSUES.md and the Companion/Process/Current/KnownIssues/ tree only once every entry has a tracker home, preserving routed history rather than deleting it.
- Update the repo instructions so the routing protocol points at the tracker instead of the register.
Workflow change this enables
Once migrated, an agent starting work on an issue should consult the tracker's wontfix items first, so a deliberately-rejected approach is not silently reimplemented. Today that safeguard depends on searching the register; afterwards it is a label query on the tracker.
Note on the removed known issue label
The known issue label meant "mirrors an entry in the canonical register" rather than "an issue we know about", which reads as tautological on an issue tracker. It has been deleted. The register IDs it marked are still visible in the issue titles, so nothing is lost. At time of removal it was applied to issues #2 through #21:
#2 IOS-AI-004 · #3 IOS-AI-005 · #4 IOS-BILLING-002 · #5 IOS-CAL-010 · #6 IOS-CLEANUP-001 · #7 IOS-COMPOSE-002 · #8 IOS-COMPOSE-003 · #9 IOS-IMAP-015 · #10 IOS-IMAP-016 · #11 IOS-PERF-008 · #12 IOS-PERF-009 · #13 IOS-PERF-010 · #14 IOS-PERF-011 · #15 IOS-PERF-012 · #16 IOS-PUSH-001 · #17 IOS-QUEUE-010 · #18 IOS-SEARCH-004 · #19 IOS-TEST-001 · #20 IOS-UI-005 · #21 (quoted-text viewport jump)
Status
Deferred by owner decision — not scheduled. Filed so the intent is recorded rather than rediscovered.
KNOWN_ISSUES.mdmaintains a second issue register parallel to this tracker: entries carry their own IDs (IOS-PUSH-001,IOS-PERF-012, …), live in a mandatory-load index plus routed detail files underCompanion/Process/Current/KnownIssues/, and are mirrored into GitHub issues whose titles repeat the register ID. The register then maps back the other way, including "retired mapping" lines for entries whose issues are closed.Maintaining both halves costs real effort and creates drift: two places to update, two places to search, and a mapping table that has to be hand-maintained in a file every agent loads on every task. The tracker alone can carry this.
Proposed migration
wontfix, with the acceptance rationale and any re-escalation fence in the body. Several register entries exist specifically as fences against re-litigating a decision (for example, an accepted limitation that may only be re-escalated if a new condition is demonstrated) — that fencing language must survive the move verbatim, since it is the whole reason the entry exists.KNOWN_ISSUES.mdand theCompanion/Process/Current/KnownIssues/tree only once every entry has a tracker home, preserving routed history rather than deleting it.Workflow change this enables
Once migrated, an agent starting work on an issue should consult the tracker's
wontfixitems first, so a deliberately-rejected approach is not silently reimplemented. Today that safeguard depends on searching the register; afterwards it is a label query on the tracker.Note on the removed
known issuelabelThe
known issuelabel meant "mirrors an entry in the canonical register" rather than "an issue we know about", which reads as tautological on an issue tracker. It has been deleted. The register IDs it marked are still visible in the issue titles, so nothing is lost. At time of removal it was applied to issues #2 through #21:#2 IOS-AI-004 · #3 IOS-AI-005 · #4 IOS-BILLING-002 · #5 IOS-CAL-010 · #6 IOS-CLEANUP-001 · #7 IOS-COMPOSE-002 · #8 IOS-COMPOSE-003 · #9 IOS-IMAP-015 · #10 IOS-IMAP-016 · #11 IOS-PERF-008 · #12 IOS-PERF-009 · #13 IOS-PERF-010 · #14 IOS-PERF-011 · #15 IOS-PERF-012 · #16 IOS-PUSH-001 · #17 IOS-QUEUE-010 · #18 IOS-SEARCH-004 · #19 IOS-TEST-001 · #20 IOS-UI-005 · #21 (quoted-text viewport jump)
Status
Deferred by owner decision — not scheduled. Filed so the intent is recorded rather than rediscovered.