Skip to content

Remove internal planning and downstream-app references from source, tests and docs - #73

Merged
ottonomy merged 1 commit into
nightshift/44-make-the-verification-result-docs-match-what-thefrom
nightshift/51-remove-internal-planning-and-downstream-app-refe
Oct 20, 2026
Merged

ottonomy merged 1 commit into
nightshift/44-make-the-verification-result-docs-match-what-thefrom
nightshift/51-remove-internal-planning-and-downstream-app-refe

Conversation

@ottonomy

Copy link
Copy Markdown
Contributor

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:

  • The verification-results appendix was removed outright rather than
    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
    failureDetail helper and the layout tree were duplicates of §6, and the
    SuiteSummary type listing duplicates §4. What was left unique was a long
    JSON blob whose content §1–§5 already describe in prose. So the whole
    section is gone, and the guide ends at "Backwards compatibility".
  • The timing appendix went the same way — its invariants are already in
    "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

  • Where the status-ownership rationale landed. The issue says a design
    rationale worth keeping moves to the architecture doc. The reason the proof
    path passes a no-op checkStatus is local to that constant, so it stays
    inline in src/services/data-integrity-crypto.ts, reworded to say what
    would 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.ts cited the deleted defaults module for "the default
    suite ordering".
    That ordering now lives in src/default-suites.ts, so I
    repointed the @see there rather than deleting it.
  • The bitstring status check's "Error patterns from constants/external.ts".
    No such module exists here; the two strings are raised by
    @digitalcredentials/vc-bitstring-status-list and are not part of its typed
    surface. The comment now says that, which is also the reason they are pinned
    as literals.
  • The wrongly-named result-ref check. The comment in the Open Badges class
    schemas called it obv3-result-ref-check and said it had been refactored to
    consume the strict normalized form. Its id is schema.obv3.result-ref and
    the 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.ts said VerificationContext (phase 2). Read
    as a planning phase, not a SuitePhase value (those are lowercase words),
    so the parenthetical is gone. SuitePhase itself is untouched everywhere.
  • Test names changed: (Q2 invariant), (Phase 7 backfills) and two
    describe titles carrying (P-E) lost the labels. Check ids and assertions
    are unchanged.
  • Noticed, left alone: src/openbadges/problem-types.ts explains its
    internal 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

@ottonomy ottonomy added the agent-authored Opened by an unattended agent — review before trusting label Oct 14, 2026
@ottonomy
ottonomy added this pull request to stack #74 October 15, 2026 01:19
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
ottonomy force-pushed the nightshift/51-remove-internal-planning-and-downstream-app-refe branch from a00fb9c to 4805ac0 Compare October 20, 2026 19:23
@ottonomy
ottonomy merged commit 546f3f7 into main Oct 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-authored Opened by an unattended agent — review before trusting

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove internal planning and downstream-app references from source, tests and docs

1 participant