Repository navigation
Remove internal planning and downstream-app references from source, tests and docs - #73
Merged
ottonomy merged 1 commit intoOct 20, 2026
Conversation
5 tasks
Source comments ship in the published JavaScript and type declarations, so shorthand from a process readers cannot see showed up in consumers' editor hovers. Every such comment is rewritten as a statement of the behaviour and why it holds: - plan labels, numbered phases, question numbers, dated plan names and links into the untracked docs plans folder are gone, along with the ignore rule for that folder; - named downstream apps no longer justify library behaviour; the reason is stated directly instead; - the prompt-ready appendices in the API guides are removed, with them the mentions in the README, the architecture doc and the unreleased 2.0.0 changelog section; the verification-results appendix duplicated the UI rendering recipe it followed; - comments no longer narrate earlier states of the code; - broken file references are fixed: the deleted defaults module (now default-suites.ts), a non-existent constants module cited for the bitstring error strings, and a comment naming the result-ref check wrongly and describing a refactor the OpenBadges Zod module records as rejected. The envelope schema header now describes the schema as it is, composed top-to-bottom, rather than as a partial state. The rationale for the status suite owning status checking outright now sits in the architecture doc's hexagonal section as well as inline. SuitePhase and its lowercase values are untouched, as are the README migration section and released changelog entries.
ottonomy
force-pushed
the
nightshift/51-remove-internal-planning-and-downstream-app-refe
branch
from
October 20, 2026 19:23
a00fb9c to
4805ac0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #51
Stacked on #72 — review and merge that first (or merge the stack together).
Departures
None in substance. Two things worth knowing about how far the deletions went:
rewritten into a neutral "worked example". I started to keep its JSON
example and snippets under a new heading, then compared them with §6 (the
UI rendering recipe) a few hundred lines above: the grouping snippet, the
failureDetailhelper and the layout tree were duplicates of §6, and theSuiteSummarytype listing duplicates §4. What was left unique was a longJSON blob whose content §1–§5 already describe in prose. So the whole
section is gone, and the guide ends at "Backwards compatibility".
"Inclusive top-level convention" and its recipes in "Recipes".
Both guides' tables of contents, the README's and the architecture doc's
pointers to them, and the unreleased 2.0.0 changelog entry were updated to
match.
Decisions not in the issue
rationale worth keeping moves to the architecture doc. The reason the proof
path passes a no-op
checkStatusis local to that constant, so it staysinline in
src/services/data-integrity-crypto.ts, reworded to say whatwould go wrong otherwise (two fetches, two possible answers). The same
reason is now also stated in the architecture doc's "What's not yet
hexagonal" bullet that previously carried the plan label.
src/types/check.tscited the deleted defaults module for "the defaultsuite ordering". That ordering now lives in
src/default-suites.ts, so Irepointed the
@seethere rather than deleting it.No such module exists here; the two strings are raised by
@digitalcredentials/vc-bitstring-status-listand are not part of its typedsurface. The comment now says that, which is also the reason they are pinned
as literals.
schemas called it
obv3-result-ref-checkand said it had been refactored toconsume the strict normalized form. Its id is
schema.obv3.result-refandthe Zod module records that refactor as considered and rejected, so the
comment now names it correctly and says it parses with the tolerant shapes
in
openbadges-zod.ts.src/types/crypto-service.tssaidVerificationContext(phase 2). Readas a planning phase, not a
SuitePhasevalue (those are lowercase words),so the parenthetical is gone.
SuitePhaseitself is untouched everywhere.(Q2 invariant),(Phase 7 backfills)and twodescribetitles carrying(P-E)lost the labels. Check ids and assertionsare unchanged.
src/openbadges/problem-types.tsexplains itsinternal const name by "the file's historical naming and the
obv3/knowledge folders". The folder reference is obscure, but it is not plan
shorthand and not caught by the acceptance grep, so I did not touch it.
Agent-Run: 4343479a-f1f1-4359-9fb2-2c1777ead08c