rfc: DX-3 bootstrap design — boundary, regeneration, standalone validation#29
Merged
Conversation
… one validator Design only. Defines the generated/scaffold/governance-complete boundary as data in the document (metadata x-bootstrap ledger: section hashes + awaitingAuthorship; deletion = graduation), regeneration as a refusal table with no --force and no merge, standalone validation as two stages of the one existing harness (--file mode, then a published thin CLI), and export's transition (current-spec emission, ledger, npm publication, --out) with a behavioral-contract preservation checklist against ADOPTING.md. Evidence from the DX-2 walkthrough (F1-F8) separated from proposals; owner decisions enumerated. Co-Authored-By: Claude Fable 5 <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new DX-3 RFC design document that defines a three-state bootstrap boundary (via metadata.x-bootstrap), strict regeneration refusal semantics, and a standalone validation distribution plan, plus the intended dspack-export transition and explicit owner decisions required before implementation.
Changes:
- Introduces a three-state boundary model (snapshot / scaffold / governance-complete) encoded in-document via an
x-bootstrapledger. - Specifies regeneration behavior via a refusal table with a “never overwrite human-authored content” invariant (no
--force, add--out). - Proposes standalone validation via
--filemode in the existing harness and a thin published CLI wrapping the same code path.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | # | Observation (fact) | Source | | ||
| |---|---|---| | ||
| | F1 | The only way to validate an adopter contract is copying it into a dspack checkout's `examples/` directory; `scripts/validate.mjs` has no file argument. | walkthrough step 10; `scripts/validate.mjs` (`EXAMPLES_DIR` fixed) | | ||
| | F2 | dspack-export is unpublished (`private: true`, install from source) and emits `"dspack": "0.2"` hard-coded (`src/emit/assemble.ts:130`); adopters relabel to `0.4` by hand. These were the only mechanical rough edges in an otherwise smooth Phase 1. | walkthrough steps 1–2 | |
| | F3 | Export output is deterministic, and its metadata stamps: hand-authored sections "are not generated and will be overwritten on regeneration." Destructive-by-default regeneration is documented, not guarded. | export README; generated `metadata` | | ||
| | F4 | The workflow that worked in practice — *snapshot → commit → enrich the committed copy → never regenerate over enrichments* — is now the documented behavioral contract (ADOPTING.md Phase 1). | walkthrough; ADOPTING.md step 1 | | ||
| | F5 | Output filename derives from `package.json` `name` (placeholder fallback) — surprising, documented, harmless. | walkthrough step 1 | | ||
| | F6 | Emit profiles are consumer-authored data against the published dspack-emit package; contracts need no ecosystem-repo changes to be used. (Correction inherited by the roadmap in dx-adoption-review.md's status section.) | DX-2; studio `astryx-profile.ts` | |
| | F5 | Output filename derives from `package.json` `name` (placeholder fallback) — surprising, documented, harmless. | walkthrough step 1 | | ||
| | F6 | Emit profiles are consumer-authored data against the published dspack-emit package; contracts need no ecosystem-repo changes to be used. (Correction inherited by the roadmap in dx-adoption-review.md's status section.) | DX-2; studio `astryx-profile.ts` | | ||
| | F7 | `metadata` legally carries extension keys today: `additionalProperties: true` in the v0.4 schema, with `x-upstream` in the astryx contract as live precedent. | `schema/dspack.v0.4.schema.json` `$defs/metadata`; `examples/astryx.dspack.json` | | ||
| | F8 | The spec's versions are strictly additive; a v0.2-shaped document relabeled `"0.4"` validates (proven by the harness's back-compat step and by the walkthrough). | `scripts/validate.mjs` step 3; walkthrough step 10 | |
Comment on lines
+49
to
+65
| "metadata": { | ||
| "generatedBy": "dspack-export@<version>", | ||
| "x-bootstrap": { | ||
| "spec": "0.4", | ||
| "generated": { | ||
| "tokens": "<content-hash>", | ||
| "components": "<content-hash>", | ||
| "frameworkBindings": "<content-hash>", | ||
| "themes": "<content-hash>", | ||
| "layout": "<content-hash>" | ||
| }, | ||
| "awaitingAuthorship": ["categories", "intents", "rules", "examples", | ||
| "patterns", "antiPatterns", | ||
| "components.*.whenToUse", "components.*.accessibility", | ||
| "components.*.composition", "components.*.constraints"] | ||
| } | ||
| } |
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.
First DX-3 deliverable — design, not implementation, per the accepted DX-series RFC and the DX-2 handoff.
metadata.x-bootstrapledger (schema-legal today —additionalProperties: true,x-upstreamprecedent). Section content-hashes make ownership mechanical; deleting the ledger is graduation; no empty governance blocks, no completeness markers.--force. Merge stays out of scope by design. The ADOPTING.md "warning" becomes a guarantee (strict strengthening).--filemode on the existing harness, then a published thin CLI wrapping the same code path. Distribution, never a fork.--out; the "separate snapshot vs bootstrap commands" question resolves as no. Behavioral-contract preservation checklist against ADOPTING.md included; §6 pre-declares the exact doc deltas.🤖 Generated with Claude Code