Choose the canonical Support bundle specification and implementation handoff

[frankieramirez]

Question

Where should the canonical, implementation-ready Support bundle specification live, what exact structure must it use, and what implementation handoff shape preserves the four settled decisions without duplicating or weakening them?

Choose:

• the canonical artifact path and ownership;
• its required sections, schemas, field manifest, static disclosure copy, acceptance traceability, and versioning rules;
• whether implementation is handed off as one issue/PR or a deliberately ordered stack, with review boundaries and dependencies; and
• the exact checklist that closes this planning map while keeping implementation out of it.

Settled input

• Define the disclosure-safe Support bundle data contract
• Choose the Support bundle generation and download contract
• Specify the Settings Support bundle interaction
• Lock the Support bundle security and acceptance contract

This is a planning decision only. It must not implement the feature, edit the bug-report template, or silently replace detail owned by the settled tickets.

[frankieramirez]

Resolution

The durable specification is a checked-in specification set with one human entry point and one machine-readable v1 contract package. GitHub decisions retain rationale and rejected alternatives; checked-in files become the normative implementation and review surface. The original report remains the implementation tracker.

Canonical locations

The human entry point is:

docs/architecture/support-bundle-spec.md

It follows the repository's locked-spec precedent in docs/architecture/dashboard-spec.md and starts with status, date, owner, the Wayfinder map, all decision links, the originating report, contract version, and an explicit “implementation is a separate handoff” statement.

The immutable machine-readable contract lives in a real Python package so wheels and source installs contain the exact bytes used at runtime:

comicarr/app/system/support_bundle_contract/
├── __init__.py
└── v1/
    ├── __init__.py
    ├── README.txt
    ├── manifest.schema.json
    ├── diagnostics.schema.json
    └── field-manifest.json

The implementation adds the explicit pyproject.toml package-data rule and an installed-wheel test proving all four non-Python assets are present and byte-identical to the source tree. Runtime generation and tests load these assets through importlib.resources; they do not carry second Python-string copies.

field-manifest.json is a review artifact, not a fourth archive member. It enumerates every emitted JSON path with its meaning, source authority, sensitivity classification, primitive or enum, exact allowed values, cardinality/size/numeric bound, complete/partial behavior, and contract version. The two schemas are the executable closed shape; the field manifest explains and classifies that shape. A parity test proves neither can drift from the other.

The terminology evolution gate uses a separate contributor-tooling allowlist:

scripts/support_bundle_legacy_terms_allowlist.txt

It contains only exact path-and-match entries for unavoidable legacy implementation identifiers and historical tests. It is version-controlled but is not part of the archive contract.

Ownership of truth

docs/architecture/support-bundle-spec.md owns the cross-layer contract and implementer reading order:

1. purpose, operator, threat model, and canonical terminology;
2. v1 archive and packaged-asset inventory;
3. exact HTTP, module, lifecycle, concurrency, bounds, and failure contracts;
4. active-runtime source authority and complete/partial semantics;
5. Settings placement, disclosure flow, exact UI states, accessibility, and documentation copy;
6. disclosure guards, acceptance matrix, live dialect coverage, human artifact review, and template-restoration gate;
7. versioning and compatibility rules;
8. implementation stack, review ownership, and out-of-scope boundary; and
9. traceability from each normative section to the decision ticket that owns its rationale.

The document points to the packaged schemas, field manifest, and README.txt for exact field-level or byte-level content rather than duplicating them in Markdown. It consolidates normative cross-layer behavior so implementers do not have to reconstruct it from comments, while the linked decision tickets remain the source for evidence, trade-offs, and rejected alternatives. The map stays an index and never absorbs the full spec.

CONTEXT.md remains glossary-only. SECURITY.md, CONTRIBUTING.md, and the bug-report template contain operator guidance only after activation; none becomes a second technical specification. No ADR is added now: the feature spec plus linked decisions already explain the trade-offs. A future ADR is warranted only if the allowlist-first public-diagnostics rule is generalized beyond Support bundles.

Versioning

The Support bundle has one independent integer contract version. Product versions and Changesets do not alter it automatically.

Once v1 ships, its asset directory is immutable. A change to member inventory/order, filename, schemas, emitted fields, meanings, enums, bounds, source authorities, omission semantics, digests, static README.txt disclosure meaning, or public-sharing promise creates a reviewed v2/ package and changes the response contract header and fixed filename. There is no unreviewed minor/additive evolution: additive fields are disclosure changes and require the next integer version.

A bug fix that only makes implementation conform to the already-published v1 bytes and semantics does not bump the contract. Pure spelling or punctuation correction in human-only architecture prose also does not bump it. Supporting two versions simultaneously would require a new decision; v1 exposes no caller version selector.

Schemas use local references only and validation performs no network access. The manifest inventory lists all three ZIP members in fixed order but follows the settled non-circular integrity rule: SHA-256 values cover README.txt and diagnostics.json; manifest.json is validated by its closed schema, fixed position/name, response length, and archive bounds.

Implementation handoff

No CarePackage button in the UI remains intact as the single implementation tracker. After the remaining exact-content decision closes, it receives one handoff comment linking the locked spec, all decisions, the contract assets, the ordered PR checklist, and acceptance evidence. Creating another implementation issue would split status from the request that motivated the work.

Implementation uses an ordered three-PR stack, not a monolith:

1. Contract and backend — land the locked spec and packaged v1 assets; add comicarr.app.system.support_bundle, the authenticated POST adapter, typed failures, archive/disclosure/security tests, package-data checks, and live SQLite/PostgreSQL/MySQL CI coverage. It neither imports the legacy collector nor changes public issue instructions.
2. Frontend interaction — depend on the backend contract; add the dedicated binary helper, Settings → About interaction, full state/accessibility tests, and authenticated smoke coverage. It still does not advertise the feature in issue-reporting documentation.
3. Disclosure activation — after every required automated gate passes, record maintainer/security review of one seeded complete and one seeded partial artifact; add the terminology guard; atomically correct SECURITY.md, CONTRIBUTING.md, and the bug template; and add the operator-facing Changeset. This is the only layer allowed to restore the public attachment instruction.

Each PR must be reviewable and green against its own base. Backend/security review owns archive shape, source projection, schema closure, guards, bounds, lock release, safe errors/logging, and dialect equivalence. Frontend review owns binary validation, Blob lifetime, the dialog/state machine, accessibility, and Settings isolation. The activation review owns public language, complete/partial artifact inspection, guard allowlist, and proof that documentation did not lead the implementation.

The first two layers may merge sequentially while the feature remains undiscoverable. The third cannot merge until both are on its base and every acceptance gate from “Lock the Support bundle security and acceptance contract” is green. Rollback before activation removes no advertised workflow; after activation, a disclosure regression removes/disables the UI and template instruction rather than weakening validation or falling back to legacy CarePackage output.

Planning-map completion

This Wayfinder map ends when, and only when:

• the exact v1 schemas, field manifest, static README.txt, fixed error sentences, enums, bounds, and copy are locked in the remaining decision;
• that resolution supplies complete content for the future checked-in specification set;
• the implementation handoff comment is posted to the originating report; and
• the map indexes every closed decision and has no open child or remaining fog.

The map does not wait for implementation PRs to merge. Its destination explicitly separates an implementation-ready specification from implementation; making merge status part of map completion would turn decision planning into delivery tracking and leave two competing trackers.

Rejected alternatives

• GitHub comments as the permanent specification: good rationale history, poor versioned runtime/audit surface, and no package-presence guarantee.
• One Markdown file containing schemas and static copy: creates copy/paste drift between prose, runtime bytes, and tests.
• Assets under docs/: source checkouts can read them, installed wheels cannot unless packaging reaches outside the application package.
• One large implementation PR: couples security-critical projection, UI state, CI, and public disclosure so reviewers cannot establish each boundary independently.
• A separate issue for each PR: fragments overall completion; one implementation tracker with an ordered stack preserves the originating request and one visible status.
• Closing the map only after implementation: contradicts the planning-only destination and duplicates the implementation tracker.