container-superposition 0.1.12 → 0.1.13-pr.167.28077292525
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/opportunities/README.md +97 -0
- package/docs/specs/029-versioned-private-catalogs/spec.md +326 -0
- package/docs/specs/030-discovery-surface-and-docs-alignment/spec.md +164 -0
- package/docs/specs/031-preset-led-onboarding-for-common-jobs/spec.md +160 -0
- package/docs/specs/README.md +33 -30
- package/docs/specs/taxonomy.md +22 -16
- package/overlays/git-helpers/setup.sh +10 -0
- package/package.json +1 -1
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Opportunity Backlog
|
|
2
|
+
|
|
3
|
+
Last updated: 2026-06-22
|
|
4
|
+
|
|
5
|
+
## Prioritized
|
|
6
|
+
|
|
7
|
+
### 1. Discovery surface clarity and docs alignment
|
|
8
|
+
|
|
9
|
+
- **type**: UX
|
|
10
|
+
- **status**: prioritized
|
|
11
|
+
- **value summary**: Reduce first-run confusion and failed self-service discovery by making available overlays easier to find and current workflows easier to follow.
|
|
12
|
+
- **urgency**: High
|
|
13
|
+
- **confidence**: High
|
|
14
|
+
- **rough effort/risk**: Low–Medium effort, Low risk
|
|
15
|
+
- **evidence**:
|
|
16
|
+
- Default `list` output omits `messaging` category despite 3 live messaging overlays.
|
|
17
|
+
- `list --category messaging` and other filtered tables render many ports as `[object Object]`.
|
|
18
|
+
- User docs still show deprecated patterns such as category-centric project config (`language:` / `database:`), old CLI examples (`--postgres`, `cs list --presets`), and `_serviceOrder` references.
|
|
19
|
+
- `plan --diff` exists in CLI/help/tests but is lightly surfaced in docs.
|
|
20
|
+
- **recommended next prompt or owner**: Spec captured in `docs/specs/030-discovery-surface-and-docs-alignment/spec.md`.
|
|
21
|
+
|
|
22
|
+
### 2. Versioned private overlay and preset catalogs
|
|
23
|
+
|
|
24
|
+
- **type**: feature
|
|
25
|
+
- **status**: candidate
|
|
26
|
+
- **value summary**: Unlock platform-team adoption by letting orgs publish and pin private catalogs without forking tool.
|
|
27
|
+
- **urgency**: Medium
|
|
28
|
+
- **confidence**: Medium
|
|
29
|
+
- **rough effort/risk**: High effort, High architecture/security risk
|
|
30
|
+
- **evidence**:
|
|
31
|
+
- Draft spec exists: `docs/specs/029-versioned-private-catalogs/spec.md`.
|
|
32
|
+
- Opportunity aligns with platform/team workflow expansion and reproducible pinned project config model.
|
|
33
|
+
- Spec now includes technical-design and routing closure for implementation handoff.
|
|
34
|
+
- **recommended next prompt or owner**: Spec captured in `docs/specs/029-versioned-private-catalogs/spec.md`.
|
|
35
|
+
|
|
36
|
+
### 3. Command and doc model simplification sweep
|
|
37
|
+
|
|
38
|
+
- **type**: documentation
|
|
39
|
+
- **status**: candidate
|
|
40
|
+
- **value summary**: Lower learning cost by aligning README/docs/help/examples around one canonical mental model: `superposition.yml` + flat `overlays:` + discovery commands.
|
|
41
|
+
- **urgency**: High
|
|
42
|
+
- **confidence**: High
|
|
43
|
+
- **rough effort/risk**: Medium effort, Low risk
|
|
44
|
+
- **evidence**:
|
|
45
|
+
- `README.md` quickstart still shows category-based project file fields.
|
|
46
|
+
- `tool/README.md`, `docs/quick-reference.md`, `docs/examples.md`, `docs/team-workflow.md`, `docs/messaging-quick-start.md`, `docs/creating-overlays.md`, `docs/dependencies.md` contain stale CLI/config guidance.
|
|
47
|
+
- **recommended next prompt or owner**: Covered by `docs/specs/030-discovery-surface-and-docs-alignment/spec.md`.
|
|
48
|
+
|
|
49
|
+
### 4. Preset-led onboarding for common jobs-to-be-done
|
|
50
|
+
|
|
51
|
+
- **type**: feature
|
|
52
|
+
- **status**: candidate
|
|
53
|
+
- **value summary**: Increase successful first-run setup by steering users toward opinionated presets instead of large overlay catalogs.
|
|
54
|
+
- **urgency**: Medium
|
|
55
|
+
- **confidence**: Medium
|
|
56
|
+
- **rough effort/risk**: Medium effort, Medium risk
|
|
57
|
+
- **evidence**:
|
|
58
|
+
- 94 catalog items create high choice load.
|
|
59
|
+
- 13 presets already exist for common scenarios (`frontend`, `web-api`, `microservice`, `local-llm`, etc.).
|
|
60
|
+
- Docs emphasize composability, but preset-first guidance appears secondary in some entrypoints.
|
|
61
|
+
- **recommended next prompt or owner**: Spec captured in `docs/specs/031-preset-led-onboarding-for-common-jobs/spec.md`.
|
|
62
|
+
|
|
63
|
+
### 5. Power-user planning workflow visibility
|
|
64
|
+
|
|
65
|
+
- **type**: UX
|
|
66
|
+
- **status**: candidate
|
|
67
|
+
- **value summary**: Improve confidence before generation by surfacing `plan`, `--verbose`, and `--diff` as safer preview workflow.
|
|
68
|
+
- **urgency**: Medium
|
|
69
|
+
- **confidence**: Medium
|
|
70
|
+
- **rough effort/risk**: Low effort, Low risk
|
|
71
|
+
- **evidence**:
|
|
72
|
+
- `plan --diff` fully exists in CLI/help/tests.
|
|
73
|
+
- Main docs center `init`/`regen`; preview workflow less prominent.
|
|
74
|
+
- **recommended next prompt or owner**: Covered by `docs/specs/030-discovery-surface-and-docs-alignment/spec.md`.
|
|
75
|
+
|
|
76
|
+
## Horizon buckets
|
|
77
|
+
|
|
78
|
+
### Quick wins
|
|
79
|
+
|
|
80
|
+
1. Discovery surface clarity and docs alignment
|
|
81
|
+
2. Command and doc model simplification sweep
|
|
82
|
+
3. Power-user planning workflow visibility
|
|
83
|
+
|
|
84
|
+
### Next big bets
|
|
85
|
+
|
|
86
|
+
1. Versioned private overlay and preset catalogs
|
|
87
|
+
2. Preset-led onboarding for common jobs-to-be-done
|
|
88
|
+
|
|
89
|
+
### Longer-term options
|
|
90
|
+
|
|
91
|
+
- Catalog version upgrade assistant after private catalogs foundation exists
|
|
92
|
+
- Usage analytics or feedback loops to validate preset/discovery effectiveness
|
|
93
|
+
|
|
94
|
+
## Notes
|
|
95
|
+
|
|
96
|
+
- Ranking based on repository evidence only. No telemetry, issue volume, or conversion data reviewed.
|
|
97
|
+
- Quick-win items likely compound together and may be worth bundling into one user-facing discovery/onboarding initiative.
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
# Feature Specification: Versioned Private Overlay and Preset Catalogs
|
|
2
|
+
|
|
3
|
+
**Spec ID**: `029-versioned-private-catalogs`
|
|
4
|
+
**Taxonomy**: `PROJECT`
|
|
5
|
+
**Created**: 2026-06-15
|
|
6
|
+
**Author**: Workflow Orchestrator
|
|
7
|
+
**Status**: Draft
|
|
8
|
+
**Input**: Opportunity backlog item 2 from `docs/opportunities/README.md` — add versioned private overlay/preset catalogs for platform teams, covering source options, pinning, trust model, precedence, upgrade workflow, and compatibility with current `superposition.yml` / `regen` architecture.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Request Classification
|
|
13
|
+
|
|
14
|
+
Technical and cross-cutting feature. PM draft now reconciled with architecture pass requirements in this document.
|
|
15
|
+
|
|
16
|
+
## Problem Statement
|
|
17
|
+
|
|
18
|
+
Current product ships single built-in overlay/preset registry inside CLI package. Platform teams that want private, opinionated overlays or presets must currently fork tool, patch internal overlays into source tree, or copy generated output per repo.
|
|
19
|
+
|
|
20
|
+
That blocks:
|
|
21
|
+
|
|
22
|
+
- central platform ownership of shared stacks
|
|
23
|
+
- independent catalog release cadence
|
|
24
|
+
- reproducible pinning for teams and CI
|
|
25
|
+
- explicit trust and upgrade workflow for organization-specific overlays/presets
|
|
26
|
+
|
|
27
|
+
Need: project-level way to consume private overlay/preset catalogs as versioned dependencies while preserving deterministic `superposition.yml` → `regen` model.
|
|
28
|
+
|
|
29
|
+
## User Goals
|
|
30
|
+
|
|
31
|
+
### Platform team
|
|
32
|
+
|
|
33
|
+
- Publish internal overlay/preset catalog without forking CLI.
|
|
34
|
+
- Release catalog updates independently.
|
|
35
|
+
- Control which teams can trust and adopt catalog content.
|
|
36
|
+
- Encode org standards in presets and overlays.
|
|
37
|
+
|
|
38
|
+
### Application team
|
|
39
|
+
|
|
40
|
+
- Declare catalog dependency in `superposition.yml`.
|
|
41
|
+
- Pin exact catalog version for reproducible local and CI runs.
|
|
42
|
+
- Select private overlays/presets alongside built-ins.
|
|
43
|
+
- Upgrade intentionally through reviewable config changes.
|
|
44
|
+
|
|
45
|
+
### Maintainer / security owner
|
|
46
|
+
|
|
47
|
+
- Make trust boundary explicit because catalog content can write files, patch config, and run scripts.
|
|
48
|
+
- Prevent silent override of built-in overlays/presets.
|
|
49
|
+
- Keep credentials out of committed project config.
|
|
50
|
+
|
|
51
|
+
## Current Behavior and Constraints
|
|
52
|
+
|
|
53
|
+
### Current behavior
|
|
54
|
+
|
|
55
|
+
- Overlay registry loads from bundled `overlays/*/overlay.yml` plus bundled presets.
|
|
56
|
+
- `superposition.yml` supports `preset` and `presetChoices`, but no external `catalogs` field.
|
|
57
|
+
- Config validation, schema generation, `list`, `explain`, `doctor`, and composition assume single bundled registry.
|
|
58
|
+
|
|
59
|
+
### Relevant implementation constraints
|
|
60
|
+
|
|
61
|
+
1. Validation currently assumes bundled overlay/preset enums.
|
|
62
|
+
2. Schema generation currently emits static enums from bundled registry.
|
|
63
|
+
3. Preset loading assumes bundled filesystem paths.
|
|
64
|
+
4. Overlay loading assumes local filesystem under single overlays root.
|
|
65
|
+
|
|
66
|
+
Any shipped feature must work consistently across `init`, `regen`, `doctor`, `list`, `explain`, and schema-aware authoring.
|
|
67
|
+
|
|
68
|
+
## Scope
|
|
69
|
+
|
|
70
|
+
### In scope
|
|
71
|
+
|
|
72
|
+
- Project-level declaration of additional catalogs.
|
|
73
|
+
- Supported source types for v1.
|
|
74
|
+
- Pinning and integrity rules.
|
|
75
|
+
- Trust model and credential handling rules.
|
|
76
|
+
- Namespace and collision behavior.
|
|
77
|
+
- Effective merged-registry behavior across commands.
|
|
78
|
+
- Upgrade workflow expectations.
|
|
79
|
+
- Validation/schema behavior for dynamic catalog-backed IDs.
|
|
80
|
+
|
|
81
|
+
### Out of scope
|
|
82
|
+
|
|
83
|
+
- Public marketplace/discovery service.
|
|
84
|
+
- Auto-upgrading floating refs.
|
|
85
|
+
- Storing tokens/keys in project file.
|
|
86
|
+
- Replacing bundled catalog.
|
|
87
|
+
- Arbitrary plugin execution beyond existing overlay/preset model.
|
|
88
|
+
- Transitive catalog dependencies in v1.
|
|
89
|
+
|
|
90
|
+
## Must Preserve
|
|
91
|
+
|
|
92
|
+
- Projects with no external catalogs behave exactly as today.
|
|
93
|
+
- `superposition.yml` remains canonical committed source of intent.
|
|
94
|
+
- `regen` remains non-interactive and deterministic in CI.
|
|
95
|
+
- Built-in bundled catalog remains available without extra setup.
|
|
96
|
+
|
|
97
|
+
## Proposed Product Behavior
|
|
98
|
+
|
|
99
|
+
### 1. `superposition.yml` gains `catalogs:`
|
|
100
|
+
|
|
101
|
+
Project config gains top-level `catalogs:` array. Each entry declares enough data for deterministic replay:
|
|
102
|
+
|
|
103
|
+
- stable catalog ID
|
|
104
|
+
- namespace
|
|
105
|
+
- source type
|
|
106
|
+
- source location
|
|
107
|
+
- immutable pin
|
|
108
|
+
- resolved identity / integrity material
|
|
109
|
+
- optional subpath
|
|
110
|
+
- optional explicit override policy
|
|
111
|
+
|
|
112
|
+
Illustrative shape:
|
|
113
|
+
|
|
114
|
+
```yaml
|
|
115
|
+
catalogs:
|
|
116
|
+
- id: acme-platform
|
|
117
|
+
namespace: acme
|
|
118
|
+
source:
|
|
119
|
+
type: git
|
|
120
|
+
url: ssh://git.example.com/platform/superposition-catalog.git
|
|
121
|
+
ref: v1.4.2
|
|
122
|
+
commit: 9f4c2d1
|
|
123
|
+
subpath: catalog
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### 2. Narrow v1 source matrix
|
|
127
|
+
|
|
128
|
+
Supported v1 source types:
|
|
129
|
+
|
|
130
|
+
1. `git`
|
|
131
|
+
- exact commit required for deterministic replay
|
|
132
|
+
- tag may be retained as advisory metadata
|
|
133
|
+
2. `archive`
|
|
134
|
+
- pinned HTTPS artifact
|
|
135
|
+
- checksum required
|
|
136
|
+
3. `path`
|
|
137
|
+
- local or repo-relative authoring/dev source only
|
|
138
|
+
- treated as non-portable for shared team config unless explicitly repo-relative
|
|
139
|
+
|
|
140
|
+
Unsupported in v1:
|
|
141
|
+
|
|
142
|
+
- OCI artifacts
|
|
143
|
+
- npm package catalogs
|
|
144
|
+
- arbitrary command fetchers
|
|
145
|
+
|
|
146
|
+
### 3. Pinning and integrity rules
|
|
147
|
+
|
|
148
|
+
- Shared/committed remote catalogs MUST use immutable identity.
|
|
149
|
+
- Floating refs like `main`, `master`, or `latest` MUST be rejected.
|
|
150
|
+
- `git` catalogs MUST record exact commit SHA.
|
|
151
|
+
- `archive` catalogs MUST record checksum.
|
|
152
|
+
- Resolved catalog identity used for generation MUST be recorded in generated receipt/manifest for audit and doctor diagnostics.
|
|
153
|
+
|
|
154
|
+
### 4. Trust model
|
|
155
|
+
|
|
156
|
+
External catalogs are trusted-code input.
|
|
157
|
+
|
|
158
|
+
Therefore:
|
|
159
|
+
|
|
160
|
+
- bundled catalog is implicitly trusted
|
|
161
|
+
- external catalogs require explicit declaration in project file
|
|
162
|
+
- credentials come from environment, Git, or host tooling — never project file
|
|
163
|
+
- fetch/auth/integrity failures fail closed
|
|
164
|
+
- tool MUST clearly surface that catalog content can affect generated files and scripts
|
|
165
|
+
|
|
166
|
+
### 5. Namespace and collision rules
|
|
167
|
+
|
|
168
|
+
Default behavior: no silent collisions.
|
|
169
|
+
|
|
170
|
+
- Built-in IDs remain unqualified.
|
|
171
|
+
- External catalogs MUST be addressable through namespace-qualified IDs (example: `acme/web-api`).
|
|
172
|
+
- Unqualified external IDs MUST NOT silently shadow built-ins.
|
|
173
|
+
- Explicit override policy, if supported, must be narrow, reviewable, and deterministic.
|
|
174
|
+
- Same project file must resolve same precedence in every command surface.
|
|
175
|
+
|
|
176
|
+
### 6. Upgrade workflow
|
|
177
|
+
|
|
178
|
+
Minimum supported workflow:
|
|
179
|
+
|
|
180
|
+
1. team edits pinned catalog version in `superposition.yml`
|
|
181
|
+
2. tool resolves new catalog deterministically
|
|
182
|
+
3. `plan`/`regen`/`doctor` surfaces changed catalog identity and invalid references if upgrade removed or renamed items
|
|
183
|
+
4. generated receipt records old/new effective catalog identities for troubleshooting
|
|
184
|
+
|
|
185
|
+
Manual pin editing is acceptable in v1. Dedicated upgrade helper command is follow-on, not required.
|
|
186
|
+
|
|
187
|
+
### 7. Dynamic validation behavior
|
|
188
|
+
|
|
189
|
+
Because full registry is no longer purely bundled/static, validation becomes two-stage:
|
|
190
|
+
|
|
191
|
+
1. parse and minimally validate raw project config structure, including `catalogs:`
|
|
192
|
+
2. resolve effective registry from bundled + external catalogs
|
|
193
|
+
3. run overlay/preset ID validation against resolved registry
|
|
194
|
+
|
|
195
|
+
Static schema/editor validation may remain partially relaxed for dynamic IDs so long as runtime validation remains precise and actionable.
|
|
196
|
+
|
|
197
|
+
## Technical Design Snapshot
|
|
198
|
+
|
|
199
|
+
### Ownership boundaries
|
|
200
|
+
|
|
201
|
+
- **Project config loader** owns raw `catalogs:` parsing and structural validation.
|
|
202
|
+
- **Catalog resolver** owns fetch/cache/materialize/verify for external catalogs.
|
|
203
|
+
- **Registry loader** owns merging bundled and external overlays/presets into one effective registry.
|
|
204
|
+
- **Command surfaces** (`init`, `regen`, `doctor`, `list`, `explain`) consume same resolved registry contract rather than bespoke loading paths.
|
|
205
|
+
- **Schema generation/editor support** owns static authoring experience and must degrade safely when dynamic IDs are present.
|
|
206
|
+
|
|
207
|
+
### Data flow
|
|
208
|
+
|
|
209
|
+
1. discover repository project file
|
|
210
|
+
2. parse project config including `catalogs:` declarations
|
|
211
|
+
3. structurally validate catalog declarations
|
|
212
|
+
4. resolve and verify each catalog source
|
|
213
|
+
5. materialize catalog contents into local cache/work area
|
|
214
|
+
6. load bundled registry + external registry entries
|
|
215
|
+
7. detect namespace/collision/override violations
|
|
216
|
+
8. validate selected overlays/presets against effective registry
|
|
217
|
+
9. execute existing composition/planning/list/explain flows using same effective registry object
|
|
218
|
+
10. emit receipt metadata including resolved catalog identities
|
|
219
|
+
|
|
220
|
+
### Interfaces and contracts
|
|
221
|
+
|
|
222
|
+
#### Project config contract
|
|
223
|
+
|
|
224
|
+
- Add top-level `catalogs:` field.
|
|
225
|
+
- Catalog entry must include `id`, `namespace`, and `source`.
|
|
226
|
+
- Source-specific required fields enforced after `type` discrimination.
|
|
227
|
+
|
|
228
|
+
#### Effective registry contract
|
|
229
|
+
|
|
230
|
+
Resolved registry MUST carry origin metadata per overlay/preset:
|
|
231
|
+
|
|
232
|
+
- source catalog ID
|
|
233
|
+
- namespace
|
|
234
|
+
- resolved version/identity
|
|
235
|
+
- built-in vs external source kind
|
|
236
|
+
|
|
237
|
+
Origin metadata must be available to diagnostics and explain/list output when relevant.
|
|
238
|
+
|
|
239
|
+
#### Cache/materialization contract
|
|
240
|
+
|
|
241
|
+
- Catalog resolution may use local cache.
|
|
242
|
+
- Cache MUST be content-addressed or identity-addressed by immutable pin.
|
|
243
|
+
- Cache hits MUST not change effective output compared with fresh fetch of same identity.
|
|
244
|
+
- Failed or partial fetch MUST not leave ambiguous mixed-version state.
|
|
245
|
+
|
|
246
|
+
### Risks and mitigations
|
|
247
|
+
|
|
248
|
+
| Risk | Impact | Mitigation |
|
|
249
|
+
| ------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
250
|
+
| Dynamic registry breaks static schema enums | weaker editor UX or false validation | use two-stage validation; relax static enum where needed; keep runtime errors precise |
|
|
251
|
+
| Silent shadowing between built-in and private IDs | wrong overlay/preset resolved | require namespace-qualified external IDs by default; explicit override only |
|
|
252
|
+
| Non-deterministic remote sources | CI drift | require immutable pins and integrity metadata |
|
|
253
|
+
| Credential leakage into config | security issue | only use ambient auth/environment; reject inline secrets |
|
|
254
|
+
| Different commands resolve different registries | trust break | centralize resolution behind one shared effective-registry pipeline |
|
|
255
|
+
| Stale cache causes confusing behavior | hidden drift | identity-addressed cache plus doctor/diagnostic visibility |
|
|
256
|
+
|
|
257
|
+
### Implementation slices
|
|
258
|
+
|
|
259
|
+
1. config/schema slice — raw `catalogs:` parsing and structural validation
|
|
260
|
+
2. resolver slice — fetch/verify/materialize supported source types
|
|
261
|
+
3. registry slice — merge bundled + external catalogs with origin metadata and collision rules
|
|
262
|
+
4. command integration slice — route `init`, `regen`, `doctor`, `list`, `explain`, `plan` through same resolved registry
|
|
263
|
+
5. diagnostics slice — receipt metadata, doctor findings, user-facing error/help text
|
|
264
|
+
6. editor/schema slice — clear authoring story for dynamic IDs
|
|
265
|
+
|
|
266
|
+
### Test strategy
|
|
267
|
+
|
|
268
|
+
- unit tests for catalog declaration validation per source type
|
|
269
|
+
- unit tests for pin rejection (`main`, `latest`, missing checksum, missing commit)
|
|
270
|
+
- unit tests for namespace/collision/override rules
|
|
271
|
+
- unit tests for effective-registry merge and origin metadata
|
|
272
|
+
- integration tests for `regen`, `list`, `explain`, `doctor`, and `plan` using sample external catalogs
|
|
273
|
+
- regression tests proving same project file yields same effective registry across commands
|
|
274
|
+
- failure-path tests for auth failure, checksum mismatch, missing overlay ID after upgrade, and stale cache reuse
|
|
275
|
+
|
|
276
|
+
## Non-Goals Within v1 Slice
|
|
277
|
+
|
|
278
|
+
Even if technically possible, v1 does not require:
|
|
279
|
+
|
|
280
|
+
- project-hosted marketplace UI
|
|
281
|
+
- separate lockfile
|
|
282
|
+
- multiple versions of same catalog in one project
|
|
283
|
+
- automatic migration from built-in preset IDs to external ones
|
|
284
|
+
- signed catalogs if immutable pins + integrity checks satisfy org policy
|
|
285
|
+
|
|
286
|
+
## Success Signals
|
|
287
|
+
|
|
288
|
+
- Platform team publishes reusable private catalog without forking CLI.
|
|
289
|
+
- Two repos pinned to same catalog identity generate same result in CI.
|
|
290
|
+
- Upgrade happens through reviewable config diff, not cache drift.
|
|
291
|
+
- Collision behavior fails closed.
|
|
292
|
+
- Same project file yields same effective registry in every command surface.
|
|
293
|
+
|
|
294
|
+
## Open Questions
|
|
295
|
+
|
|
296
|
+
1. Should repo-shared config allow any non-repo-relative `path` source, or should shared configs reject `path` entirely outside local/dev mode?
|
|
297
|
+
2. Does v1 need explicit built-in allowlist/host allowlist policy in addition to immutable pins and integrity checks?
|
|
298
|
+
3. Should override policy exist in v1 at all, or should v1 require strict namespace-only usage with no shadowing escape hatch?
|
|
299
|
+
|
|
300
|
+
## Acceptance Criteria
|
|
301
|
+
|
|
302
|
+
| # | Criterion |
|
|
303
|
+
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
304
|
+
| AC-1 | Product supports project-level declaration of zero or more additional overlay/preset catalogs in canonical `superposition.yml` without changing behavior for projects that omit `catalogs:`. |
|
|
305
|
+
| AC-2 | Shared remote catalog declarations require immutable pinning; floating refs are rejected. |
|
|
306
|
+
| AC-3 | Supported v1 source types are explicitly limited to `git`, `archive`, and `path`, with unsupported kinds rejected clearly. |
|
|
307
|
+
| AC-4 | Credentials are never stored in project file; authentication relies on environment or host tooling. |
|
|
308
|
+
| AC-5 | External catalog overlays/presets are selectable through existing project-file concepts rather than parallel selection model. |
|
|
309
|
+
| AC-6 | Built-in and external catalog collisions fail closed by default; no silent shadowing occurs. |
|
|
310
|
+
| AC-7 | Every command surface that consumes registry data resolves same effective merged registry for same project file. |
|
|
311
|
+
| AC-8 | Generated receipt/manifest records resolved catalog identities sufficient for audit and troubleshooting. |
|
|
312
|
+
| AC-9 | Validation supports dynamic catalog-backed IDs through two-stage resolution and produces actionable errors when referenced items are missing. |
|
|
313
|
+
| AC-10 | Upgrade workflow based on reviewable pin changes is documented, and failures caused by removed/renamed catalog items are surfaced clearly. |
|
|
314
|
+
| AC-11 | Automated tests cover successful resolution plus failure paths for pinning, integrity, collisions, and cross-command consistency. |
|
|
315
|
+
|
|
316
|
+
## Architecture Decision Impact
|
|
317
|
+
|
|
318
|
+
New ADR needed.
|
|
319
|
+
|
|
320
|
+
Reason: feature changes trust boundary, registry resolution order, validation model, cache/materialization responsibilities, and cross-command ownership model.
|
|
321
|
+
|
|
322
|
+
## Routing Decision
|
|
323
|
+
|
|
324
|
+
**PM → Developer**
|
|
325
|
+
|
|
326
|
+
Reason: product scope, UX constraints, technical ownership, risks, implementation slices, and test strategy now explicit. ADR creation remains required alongside implementation planning, but no further discovery is blocking spec readiness.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Feature Specification: Discovery Surface and Canonical Docs Alignment
|
|
2
|
+
|
|
3
|
+
**Spec ID**: `030-discovery-surface-and-docs-alignment`
|
|
4
|
+
**Taxonomy**: `CLI-UX, DOCS-GUIDE`
|
|
5
|
+
**Created**: 2026-06-22
|
|
6
|
+
**Author**: Workflow Orchestrator
|
|
7
|
+
**Status**: Draft
|
|
8
|
+
**Input**: Opportunity backlog items 1, 3, and 5 from `docs/opportunities/README.md` — fix discovery surface gaps, align docs/help/examples to one canonical model, and make preview-first planning workflow easy to find.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Request Classification
|
|
13
|
+
|
|
14
|
+
Existing behavior and repo evidence clear enough for direct spec authoring. No blocker user questions found.
|
|
15
|
+
|
|
16
|
+
This spec intentionally bundles three related backlog items because they share same user problem: users cannot reliably discover current overlays and safest current workflow from first-party surfaces.
|
|
17
|
+
|
|
18
|
+
- Opportunity 1: Discovery surface clarity and docs alignment
|
|
19
|
+
- Opportunity 3: Command and doc model simplification sweep
|
|
20
|
+
- Opportunity 5: Power-user planning workflow visibility
|
|
21
|
+
|
|
22
|
+
## Problem Statement
|
|
23
|
+
|
|
24
|
+
Current product surfaces disagree with current product model.
|
|
25
|
+
|
|
26
|
+
Observed repo evidence:
|
|
27
|
+
|
|
28
|
+
- `docs/opportunities/README.md` records that default `list` output omits `messaging` category despite live messaging overlays.
|
|
29
|
+
- Same opportunity notes filtered `list --category ...` tables can render port values as `[object Object]`.
|
|
30
|
+
- `README.md`, `tool/README.md`, `docs/quick-reference.md`, `docs/examples.md`, `docs/team-workflow.md`, and `docs/messaging-quick-start.md` still teach deprecated category-centric config, stale CLI flags, or manifest-first workflows.
|
|
31
|
+
- `plan`, `--verbose`, and `plan --diff` exist but are not consistently presented as safe preview path before writing files.
|
|
32
|
+
|
|
33
|
+
Result: first-run users learn wrong config shape, power users miss safer preview tools, and discovery trust drops because catalog/docs/help disagree.
|
|
34
|
+
|
|
35
|
+
## User Goals
|
|
36
|
+
|
|
37
|
+
### First-time user
|
|
38
|
+
|
|
39
|
+
- Find current overlays through `list` output without missing live categories.
|
|
40
|
+
- Copy examples that match current canonical `superposition.yml` model.
|
|
41
|
+
- Understand safe path: preview first, then generate.
|
|
42
|
+
|
|
43
|
+
### Returning user / team maintainer
|
|
44
|
+
|
|
45
|
+
- See one consistent mental model across README, docs, examples, and command help.
|
|
46
|
+
- Use `superposition.yml` with flat `overlays:` as default authoring pattern.
|
|
47
|
+
- Avoid deprecated flags/examples that create cleanup or migration work.
|
|
48
|
+
|
|
49
|
+
### Power user
|
|
50
|
+
|
|
51
|
+
- Discover `plan`, `plan --verbose`, and `plan --diff` quickly.
|
|
52
|
+
- Compare intended changes before `init`/`regen` writes output.
|
|
53
|
+
|
|
54
|
+
## Scope
|
|
55
|
+
|
|
56
|
+
### In scope
|
|
57
|
+
|
|
58
|
+
- Fix discovery output gaps in `list` for current overlay categories and port rendering.
|
|
59
|
+
- Rewrite first-party docs/help/examples to teach one canonical config model.
|
|
60
|
+
- Promote preview-first workflow in top-level docs and quick-reference surfaces.
|
|
61
|
+
- Align messaging examples with current command and config model.
|
|
62
|
+
- Define deprecation cleanup for stale examples and stale terminology.
|
|
63
|
+
|
|
64
|
+
### Out of scope
|
|
65
|
+
|
|
66
|
+
- Adding new overlays, presets, or categories.
|
|
67
|
+
- Redesigning preset system itself.
|
|
68
|
+
- New planning engine behavior beyond discoverability and wording.
|
|
69
|
+
- External/private catalog support.
|
|
70
|
+
|
|
71
|
+
## Must Preserve
|
|
72
|
+
|
|
73
|
+
- `superposition.yml` remains canonical generation input.
|
|
74
|
+
- Advanced users can still specify overlays directly without presets.
|
|
75
|
+
- Existing `plan`, `plan --verbose`, and `plan --diff` semantics remain unchanged unless another spec changes them.
|
|
76
|
+
|
|
77
|
+
## Proposed Behavior
|
|
78
|
+
|
|
79
|
+
### 1. Discovery surfaces reflect live catalog
|
|
80
|
+
|
|
81
|
+
Default overlay discovery output MUST include every live top-level category intended for user selection, including `messaging`.
|
|
82
|
+
|
|
83
|
+
Category-filtered tabular output MUST render ports and similar structured fields as human-readable values, never raw object stringification like `[object Object]`.
|
|
84
|
+
|
|
85
|
+
### 2. Canonical docs model becomes flat `overlays:` + project-file-first
|
|
86
|
+
|
|
87
|
+
Primary docs and examples MUST teach:
|
|
88
|
+
|
|
89
|
+
- project-file-first workflow
|
|
90
|
+
- `superposition.yml` / `.superposition.yml` canonical input
|
|
91
|
+
- flat `overlays:` selection as default explicit authoring model
|
|
92
|
+
- `preset` as optional shortcut, not alternate configuration architecture
|
|
93
|
+
|
|
94
|
+
Docs MUST stop teaching deprecated category-centric top-level fields like `language:` / `database:` as primary model except where explicitly documented for backward compatibility or migration context.
|
|
95
|
+
|
|
96
|
+
### 3. Preview-first workflow becomes explicit
|
|
97
|
+
|
|
98
|
+
Top-level onboarding docs MUST present preview path before generation:
|
|
99
|
+
|
|
100
|
+
1. discover overlays/presets
|
|
101
|
+
2. preview with `plan`
|
|
102
|
+
3. inspect reasons with `--verbose`
|
|
103
|
+
4. inspect diff when changing existing config with `plan --diff`
|
|
104
|
+
5. run `init` or `regen`
|
|
105
|
+
|
|
106
|
+
### 4. Stale command examples removed or reframed
|
|
107
|
+
|
|
108
|
+
Docs/help/examples MUST stop presenting stale patterns as current guidance, including:
|
|
109
|
+
|
|
110
|
+
- `--postgres` style examples when canonical examples should use current overlay/config forms
|
|
111
|
+
- `cs list --presets` when current discovery path differs
|
|
112
|
+
- `_serviceOrder` references in end-user docs
|
|
113
|
+
- manifest-first team workflow examples that center `superposition.json` instead of project file
|
|
114
|
+
|
|
115
|
+
Migration-only docs may still mention old patterns when clearly marked as legacy or transition-only.
|
|
116
|
+
|
|
117
|
+
## UX Contract
|
|
118
|
+
|
|
119
|
+
### Information hierarchy
|
|
120
|
+
|
|
121
|
+
- README quickstart leads with `init`, canonical `superposition.yml`, `plan`, `regen`.
|
|
122
|
+
- Quick reference and examples mirror same order.
|
|
123
|
+
- Messaging guide uses same command vocabulary and config model as README.
|
|
124
|
+
|
|
125
|
+
### Copy contract
|
|
126
|
+
|
|
127
|
+
- Say `superposition.yml` is canonical input.
|
|
128
|
+
- Say flat `overlays:` is preferred explicit selection model.
|
|
129
|
+
- Present presets as guided shortcut for common jobs, not hidden expert feature.
|
|
130
|
+
- Present `plan` as preview, `plan --verbose` as explanation, `plan --diff` as change review.
|
|
131
|
+
|
|
132
|
+
### Error/edge presentation
|
|
133
|
+
|
|
134
|
+
- Discovery output never exposes implementation formatting artifacts like `[object Object]`.
|
|
135
|
+
- If category filtering omits results, wording must make absence explicit rather than silently hiding live category families.
|
|
136
|
+
|
|
137
|
+
## Acceptance Criteria
|
|
138
|
+
|
|
139
|
+
| # | Criterion |
|
|
140
|
+
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
141
|
+
| AC-1 | Default discovery output includes all live user-facing overlay categories, including `messaging`, when applicable to current catalog. |
|
|
142
|
+
| AC-2 | Category-filtered discovery tables render port metadata in human-readable form and never display `[object Object]`. |
|
|
143
|
+
| AC-3 | `README.md`, `tool/README.md`, `docs/quick-reference.md`, `docs/examples.md`, `docs/team-workflow.md`, and `docs/messaging-quick-start.md` teach current canonical workflow rather than deprecated manifest-first or category-centric primary guidance. |
|
|
144
|
+
| AC-4 | Primary examples use `superposition.yml` plus flat `overlays:` as preferred explicit selection model, with any legacy syntax clearly labeled as migration/compatibility-only if retained. |
|
|
145
|
+
| AC-5 | First-run docs surface `plan`, `plan --verbose`, and `plan --diff` as preview-first workflow before file generation or regeneration. |
|
|
146
|
+
| AC-6 | End-user docs do not present stale flags, stale examples, or implementation internals (`_serviceOrder`) as current recommended workflow. |
|
|
147
|
+
| AC-7 | Changes preserve current command semantics for `init`, `regen`, and `plan`; this spec only changes discovery rendering and user guidance, not planning/generation behavior. |
|
|
148
|
+
| AC-8 | Automated coverage exists for any CLI rendering bug fixed under this spec, including category presence and human-readable field rendering. |
|
|
149
|
+
|
|
150
|
+
## ADR Impact
|
|
151
|
+
|
|
152
|
+
Aligned.
|
|
153
|
+
|
|
154
|
+
No new architecture decision required. Work stays within existing project-file-first product direction.
|
|
155
|
+
|
|
156
|
+
## Open Questions
|
|
157
|
+
|
|
158
|
+
None blocking spec completion.
|
|
159
|
+
|
|
160
|
+
## Routing Decision
|
|
161
|
+
|
|
162
|
+
**PM → Developer**
|
|
163
|
+
|
|
164
|
+
Reason: UX contract and scope boundaries now explicit; no further architecture pass required.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Feature Specification: Preset-Led Onboarding for Common Jobs-to-be-Done
|
|
2
|
+
|
|
3
|
+
**Spec ID**: `031-preset-led-onboarding-for-common-jobs`
|
|
4
|
+
**Taxonomy**: `CLI-UX, DOCS-GUIDE`
|
|
5
|
+
**Created**: 2026-06-22
|
|
6
|
+
**Author**: Workflow Orchestrator
|
|
7
|
+
**Status**: Draft
|
|
8
|
+
**Input**: Opportunity backlog item 4 from `docs/opportunities/README.md` — steer first-run users toward opinionated presets for common jobs-to-be-done instead of forcing large-catalog selection first.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Request Classification
|
|
13
|
+
|
|
14
|
+
User-facing onboarding problem. Existing repo evidence sufficient for PM+UX finalization without blocker discovery round.
|
|
15
|
+
|
|
16
|
+
## Problem Statement
|
|
17
|
+
|
|
18
|
+
Current product has enough overlays and options to create choice overload for first-run users.
|
|
19
|
+
|
|
20
|
+
Observed repo evidence:
|
|
21
|
+
|
|
22
|
+
- Opportunity backlog records 94 catalog items and 13 existing presets.
|
|
23
|
+
- `docs/presets.md` documents strong preset value, but README and some entry surfaces still emphasize manual composability first.
|
|
24
|
+
- Opportunity notes preset-first guidance appears secondary in some entrypoints.
|
|
25
|
+
|
|
26
|
+
Result: users face catalog breadth before job-oriented starting points, increasing onboarding friction and failed self-service setup.
|
|
27
|
+
|
|
28
|
+
## User Goals
|
|
29
|
+
|
|
30
|
+
### First-time user
|
|
31
|
+
|
|
32
|
+
- Start from common goal like web API, microservice, docs site, or full-stack app.
|
|
33
|
+
- Get sane defaults without understanding full overlay catalog first.
|
|
34
|
+
- Still retain option to customize after preset selection.
|
|
35
|
+
|
|
36
|
+
### Experienced user
|
|
37
|
+
|
|
38
|
+
- Keep direct overlay selection available.
|
|
39
|
+
- Understand when preset path is fastest and when manual overlay path is better.
|
|
40
|
+
|
|
41
|
+
### Team maintainer / docs author
|
|
42
|
+
|
|
43
|
+
- Recommend consistent onboarding path across README, examples, and preset docs.
|
|
44
|
+
- Reduce cognitive load without hiding composability power.
|
|
45
|
+
|
|
46
|
+
## Scope
|
|
47
|
+
|
|
48
|
+
### In scope
|
|
49
|
+
|
|
50
|
+
- Make preset-first onboarding explicit in first-run docs and interactive guidance where current product already supports it.
|
|
51
|
+
- Define jobs-to-be-done framing for preset entrypoints.
|
|
52
|
+
- Clarify customization path after selecting preset.
|
|
53
|
+
- Define fallback path for users whose need does not fit preset.
|
|
54
|
+
|
|
55
|
+
### Out of scope
|
|
56
|
+
|
|
57
|
+
- Creating brand-new preset execution engine.
|
|
58
|
+
- Removing direct overlay selection.
|
|
59
|
+
- Private/versioned preset catalogs.
|
|
60
|
+
- Guaranteeing every possible stack has preset coverage in this slice.
|
|
61
|
+
|
|
62
|
+
## Must Preserve
|
|
63
|
+
|
|
64
|
+
- Direct overlay-driven workflow remains supported.
|
|
65
|
+
- Presets remain optional shortcut, not mandatory abstraction.
|
|
66
|
+
- Users can still add/remove overlays after preset expansion when current product supports it.
|
|
67
|
+
|
|
68
|
+
## Proposed Behavior
|
|
69
|
+
|
|
70
|
+
### 1. Presets become recommended first-run path for common jobs
|
|
71
|
+
|
|
72
|
+
First-run surfaces SHOULD recommend presets first for users whose need matches common jobs:
|
|
73
|
+
|
|
74
|
+
- web API
|
|
75
|
+
- microservice
|
|
76
|
+
- documentation site
|
|
77
|
+
- full-stack application
|
|
78
|
+
- other currently supported preset scenarios documented by product
|
|
79
|
+
|
|
80
|
+
### 2. Manual overlay path remains visible as advanced/flexible path
|
|
81
|
+
|
|
82
|
+
Docs and interactive copy MUST make clear that users can:
|
|
83
|
+
|
|
84
|
+
- start from preset for speed
|
|
85
|
+
- or start from direct overlay selection for bespoke stacks
|
|
86
|
+
|
|
87
|
+
Neither path should imply other path is deprecated.
|
|
88
|
+
|
|
89
|
+
### 3. Preset flow explains customization handoff
|
|
90
|
+
|
|
91
|
+
When preset is recommended, docs and onboarding copy MUST also explain that user can customize after preset selection by:
|
|
92
|
+
|
|
93
|
+
- choosing preset options (`presetChoices`) where applicable
|
|
94
|
+
- adding overlays not included in preset
|
|
95
|
+
- removing non-required overlays when supported by current flow
|
|
96
|
+
|
|
97
|
+
### 4. Job-based docs/examples point to preset equivalents
|
|
98
|
+
|
|
99
|
+
Docs/examples for common stacks SHOULD show:
|
|
100
|
+
|
|
101
|
+
- preset-first path
|
|
102
|
+
- equivalent explicit overlay path when useful for transparency or automation
|
|
103
|
+
|
|
104
|
+
This keeps onboarding approachable without hiding resulting stack composition.
|
|
105
|
+
|
|
106
|
+
## UX Contract
|
|
107
|
+
|
|
108
|
+
### Entry decision
|
|
109
|
+
|
|
110
|
+
User should quickly answer: “Does one of these common outcomes match my project?”
|
|
111
|
+
|
|
112
|
+
If yes:
|
|
113
|
+
|
|
114
|
+
- choose preset path
|
|
115
|
+
|
|
116
|
+
If no:
|
|
117
|
+
|
|
118
|
+
- choose direct overlay path
|
|
119
|
+
|
|
120
|
+
### Copy contract
|
|
121
|
+
|
|
122
|
+
- Present presets as fastest way to get started.
|
|
123
|
+
- Present overlays as flexible composition layer.
|
|
124
|
+
- Avoid language implying presets are toy mode or overlays are only expert path.
|
|
125
|
+
- Use job-focused labels before implementation-focused labels when introducing preset choices.
|
|
126
|
+
|
|
127
|
+
### State/navigation contract
|
|
128
|
+
|
|
129
|
+
- First-run docs link from generic getting-started surfaces to preset guide.
|
|
130
|
+
- Preset guide links back to explicit overlay/config equivalents.
|
|
131
|
+
- Customization step appears after preset recommendation, not hidden in later deep docs.
|
|
132
|
+
|
|
133
|
+
## Acceptance Criteria
|
|
134
|
+
|
|
135
|
+
| # | Criterion |
|
|
136
|
+
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
137
|
+
| AC-1 | First-run documentation recommends presets as default starting path for common jobs-to-be-done while preserving direct overlay selection as supported alternative. |
|
|
138
|
+
| AC-2 | README and related getting-started surfaces point users to preset-oriented entry guidance when their use case matches a common preset. |
|
|
139
|
+
| AC-3 | `docs/presets.md` and linked onboarding surfaces explain how users customize after selecting a preset, including `presetChoices` and overlay-level additions/removals where supported. |
|
|
140
|
+
| AC-4 | At least core common scenarios documented by current product have job-oriented preset guidance and, where useful, equivalent explicit overlay/config examples for transparency. |
|
|
141
|
+
| AC-5 | Guidance clearly tells users what to do when no preset fits: use flat `overlays:` or direct interactive overlay selection. |
|
|
142
|
+
| AC-6 | This spec does not remove or hide advanced composability; it changes recommendation order and explanatory copy only. |
|
|
143
|
+
| AC-7 | If interactive questionnaire copy or menu ordering changes under this spec, tests or snapshots cover new recommendation wording/order. |
|
|
144
|
+
|
|
145
|
+
## ADR Impact
|
|
146
|
+
|
|
147
|
+
Aligned.
|
|
148
|
+
|
|
149
|
+
No new ADR required. Product behavior stays within current preset architecture.
|
|
150
|
+
|
|
151
|
+
## Assumptions
|
|
152
|
+
|
|
153
|
+
1. Existing preset catalog is sufficient for first ship of preset-led onboarding improvements.
|
|
154
|
+
2. Work may adjust docs and current questionnaire wording/order, but not preset expansion semantics.
|
|
155
|
+
|
|
156
|
+
## Routing Decision
|
|
157
|
+
|
|
158
|
+
**PM → Developer**
|
|
159
|
+
|
|
160
|
+
Reason: UX contract, scope, and preservation rules explicit. No further architecture discovery required.
|
package/docs/specs/README.md
CHANGED
|
@@ -1,32 +1,35 @@
|
|
|
1
1
|
# Specs Index
|
|
2
2
|
|
|
3
|
-
| Spec
|
|
4
|
-
|
|
|
5
|
-
| [001-verbose-plan-graph](001-verbose-plan-graph/spec.md)
|
|
6
|
-
| [002-superposition-config-file](002-superposition-config-file/spec.md)
|
|
7
|
-
| [003-mkdocs2-overlay](003-mkdocs2-overlay/spec.md)
|
|
8
|
-
| [004-doctor-fix](004-doctor-fix/spec.md)
|
|
9
|
-
| [005-cuda-overlay](005-cuda-overlay/spec.md)
|
|
10
|
-
| [006-rocm-overlay](006-rocm-overlay/spec.md)
|
|
11
|
-
| [007-target-aware-generation](007-target-aware-generation/spec.md)
|
|
12
|
-
| [008-project-file-canonical](008-project-file-canonical/spec.md)
|
|
13
|
-
| [009-project-env](009-project-env/spec.md)
|
|
14
|
-
| [010-compose-env-materialization](010-compose-env-materialization/spec.md)
|
|
15
|
-
| [011-overlay-parameters](011-overlay-parameters/spec.md)
|
|
16
|
-
| [012-ollama-cli-overlay](012-ollama-cli-overlay/spec.md)
|
|
17
|
-
| [013-doctor-dependency-check](013-doctor-dependency-check/spec.md)
|
|
18
|
-
| [014-doctor-compose-port-cross-validation](014-doctor-compose-port-cross-validation/spec.md)
|
|
19
|
-
| [015-doctor-env-example-drift](015-doctor-env-example-drift/spec.md)
|
|
20
|
-
| [016-doctor-reproducibility-check](016-doctor-reproducibility-check/spec.md)
|
|
21
|
-
| [017-doctor-dry-run](017-doctor-dry-run/spec.md)
|
|
22
|
-
| [018-init-project-file](018-init-project-file/spec.md)
|
|
23
|
-
| [019-project-mounts](019-project-mounts/spec.md)
|
|
24
|
-
| [020-superposition-yml-schema](020-superposition-yml-schema/spec.md)
|
|
25
|
-
| [021-deterministic-generated-readme](021-deterministic-generated-readme/spec.md)
|
|
26
|
-
| [022-local-superposition-config](022-local-superposition-config/spec.md)
|
|
27
|
-
| [023-pr-prerelease-gate](023-pr-prerelease-gate/spec.md)
|
|
28
|
-
| [024-project-ports](024-project-ports/spec.md)
|
|
29
|
-
| [025-variable-expansion-consolidation](025-variable-expansion-consolidation/spec.md)
|
|
30
|
-
| [026-adhoc-project-parameters](026-adhoc-project-parameters/spec.md)
|
|
31
|
-
| [027-devcontainer-gitignore-content](027-devcontainer-gitignore-content/spec.md)
|
|
32
|
-
| [028-publish-summaries-and-pr-comments](028-publish-summaries-and-pr-comments/spec.md)
|
|
3
|
+
| Spec | Title | Status | Taxonomy |
|
|
4
|
+
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------- | -------------------- |
|
|
5
|
+
| [001-verbose-plan-graph](001-verbose-plan-graph/spec.md) | Verbose Plan Graph | Final | CLI-UX |
|
|
6
|
+
| [002-superposition-config-file](002-superposition-config-file/spec.md) | Project Configuration File | Final | PROJECT |
|
|
7
|
+
| [003-mkdocs2-overlay](003-mkdocs2-overlay/spec.md) | MkDocs 2.x Overlay | Final | OVERLAY-NEW |
|
|
8
|
+
| [004-doctor-fix](004-doctor-fix/spec.md) | `doctor --fix` — Interactive Auto-Repair | Final | CLI-COMMAND |
|
|
9
|
+
| [005-cuda-overlay](005-cuda-overlay/spec.md) | CUDA (NVIDIA GPU) Overlay | Final | OVERLAY-NEW |
|
|
10
|
+
| [006-rocm-overlay](006-rocm-overlay/spec.md) | ROCm (AMD GPU) Overlay | Final | OVERLAY-NEW |
|
|
11
|
+
| [007-target-aware-generation](007-target-aware-generation/spec.md) | Target-Aware Generation | Final | CLI-FLAG |
|
|
12
|
+
| [008-project-file-canonical](008-project-file-canonical/spec.md) | Make superposition.yml Canonical Input | Approved | PROJECT |
|
|
13
|
+
| [009-project-env](009-project-env/spec.md) | Unified Project-Level Environment Variables | Approved | PROJECT |
|
|
14
|
+
| [010-compose-env-materialization](010-compose-env-materialization/spec.md) | Compose Env Materialization and Env Template Naming | Approved | COMPOSER-FEAT |
|
|
15
|
+
| [011-overlay-parameters](011-overlay-parameters/spec.md) | Overlay Parameters with Safe Substitution | Final | SCHEMA-FIELD |
|
|
16
|
+
| [012-ollama-cli-overlay](012-ollama-cli-overlay/spec.md) | Split Ollama Service and CLI Overlays | Final | OVERLAY-NEW |
|
|
17
|
+
| [013-doctor-dependency-check](013-doctor-dependency-check/spec.md) | Doctor Overlay Dependency Resolution Check | Approved | CLI-UX |
|
|
18
|
+
| [014-doctor-compose-port-cross-validation](014-doctor-compose-port-cross-validation/spec.md) | Doctor Compose / Port Cross-Validation | Approved | CLI-UX |
|
|
19
|
+
| [015-doctor-env-example-drift](015-doctor-env-example-drift/spec.md) | Doctor `.env.example` Drift Detection | Approved | CLI-UX |
|
|
20
|
+
| [016-doctor-reproducibility-check](016-doctor-reproducibility-check/spec.md) | Doctor Reproducibility Check | Approved | CLI-UX |
|
|
21
|
+
| [017-doctor-dry-run](017-doctor-dry-run/spec.md) | Doctor `--fix --dry-run` Flag | Approved | CLI-FLAG |
|
|
22
|
+
| [018-init-project-file](018-init-project-file/spec.md) | `init --project-file` | Final | PROJECT |
|
|
23
|
+
| [019-project-mounts](019-project-mounts/spec.md) | First-Class Mounts Support | Approved | PROJECT |
|
|
24
|
+
| [020-superposition-yml-schema](020-superposition-yml-schema/spec.md) | JSON Schema for `superposition.yml` | Approved | SCHEMA-FIELD |
|
|
25
|
+
| [021-deterministic-generated-readme](021-deterministic-generated-readme/spec.md) | Deterministic Generated README Header | Approved | CLI-UX |
|
|
26
|
+
| [022-local-superposition-config](022-local-superposition-config/spec.md) | Local Superposition Config | Final | PROJECT |
|
|
27
|
+
| [023-pr-prerelease-gate](023-pr-prerelease-gate/spec.md) | PR Prerelease Deployment Gate | Final | INFRA-BUILD |
|
|
28
|
+
| [024-project-ports](024-project-ports/spec.md) | Project-Level `ports` Field (plain/compose redesign) | Final | SCHEMA-FIELD |
|
|
29
|
+
| [025-variable-expansion-consolidation](025-variable-expansion-consolidation/spec.md) | Variable Expansion and Substitution Consolidation | Final | SCHEMA-FIELD, CLI-UX |
|
|
30
|
+
| [026-adhoc-project-parameters](026-adhoc-project-parameters/spec.md) | Ad-hoc Project Parameters | Final | SCHEMA-FIELD, CLI-UX |
|
|
31
|
+
| [027-devcontainer-gitignore-content](027-devcontainer-gitignore-content/spec.md) | devcontainerGitignore — Drop `!.gitignore` from Generated Content | Final | CLI-UX |
|
|
32
|
+
| [028-publish-summaries-and-pr-comments](028-publish-summaries-and-pr-comments/spec.md) | Publish Workflow Summaries and PR Comment Parity | Implemented | INFRA-BUILD |
|
|
33
|
+
| [029-versioned-private-catalogs](029-versioned-private-catalogs/spec.md) | Versioned Private Overlay and Preset Catalogs | Draft | PROJECT |
|
|
34
|
+
| [030-discovery-surface-and-docs-alignment](030-discovery-surface-and-docs-alignment/spec.md) | Discovery Surface and Canonical Docs Alignment | Draft | CLI-UX, DOCS-GUIDE |
|
|
35
|
+
| [031-preset-led-onboarding-for-common-jobs](031-preset-led-onboarding-for-common-jobs/spec.md) | Preset-Led Onboarding for Common Jobs-to-be-Done | Draft | CLI-UX, DOCS-GUIDE |
|
package/docs/specs/taxonomy.md
CHANGED
|
@@ -122,13 +122,15 @@ _No specs yet._
|
|
|
122
122
|
|
|
123
123
|
### CLI-UX
|
|
124
124
|
|
|
125
|
-
| Spec
|
|
126
|
-
|
|
|
127
|
-
| [001-verbose-plan-graph](001-verbose-plan-graph/spec.md)
|
|
128
|
-
| [013-doctor-dependency-check](013-doctor-dependency-check/spec.md)
|
|
129
|
-
| [014-doctor-compose-port-cross-validation](014-doctor-compose-port-cross-validation/spec.md)
|
|
130
|
-
| [015-doctor-env-example-drift](015-doctor-env-example-drift/spec.md)
|
|
131
|
-
| [016-doctor-reproducibility-check](016-doctor-reproducibility-check/spec.md)
|
|
125
|
+
| Spec | Title | Status |
|
|
126
|
+
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------ |
|
|
127
|
+
| [001-verbose-plan-graph](001-verbose-plan-graph/spec.md) | Verbose Plan Graph | Final |
|
|
128
|
+
| [013-doctor-dependency-check](013-doctor-dependency-check/spec.md) | Doctor Overlay Dependency Resolution Check | Draft |
|
|
129
|
+
| [014-doctor-compose-port-cross-validation](014-doctor-compose-port-cross-validation/spec.md) | Doctor Compose / Port Cross-Validation | Draft |
|
|
130
|
+
| [015-doctor-env-example-drift](015-doctor-env-example-drift/spec.md) | Doctor `.env.example` Drift Detection | Draft |
|
|
131
|
+
| [016-doctor-reproducibility-check](016-doctor-reproducibility-check/spec.md) | Doctor Reproducibility Check | Draft |
|
|
132
|
+
| [030-discovery-surface-and-docs-alignment](030-discovery-surface-and-docs-alignment/spec.md) | Discovery Surface and Canonical Docs Alignment | Draft |
|
|
133
|
+
| [031-preset-led-onboarding-for-common-jobs](031-preset-led-onboarding-for-common-jobs/spec.md) | Preset-Led Onboarding for Common Jobs-to-be-Done | Draft |
|
|
132
134
|
|
|
133
135
|
---
|
|
134
136
|
|
|
@@ -152,7 +154,10 @@ _No specs yet._
|
|
|
152
154
|
|
|
153
155
|
### DOCS-GUIDE
|
|
154
156
|
|
|
155
|
-
|
|
157
|
+
| Spec | Title | Status |
|
|
158
|
+
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------ |
|
|
159
|
+
| [030-discovery-surface-and-docs-alignment](030-discovery-surface-and-docs-alignment/spec.md) | Discovery Surface and Canonical Docs Alignment | Draft |
|
|
160
|
+
| [031-preset-led-onboarding-for-common-jobs](031-preset-led-onboarding-for-common-jobs/spec.md) | Preset-Led Onboarding for Common Jobs-to-be-Done | Draft |
|
|
156
161
|
|
|
157
162
|
### DOCS-API
|
|
158
163
|
|
|
@@ -180,11 +185,12 @@ _No specs yet._
|
|
|
180
185
|
|
|
181
186
|
## PROJECT — Project-level configuration
|
|
182
187
|
|
|
183
|
-
| Spec | Title
|
|
184
|
-
| ------------------------------------------------------------------------ |
|
|
185
|
-
| [002-superposition-config-file](002-superposition-config-file/spec.md) | Project Configuration File
|
|
186
|
-
| [008-project-file-canonical](008-project-file-canonical/spec.md) | Project File Canonical Form
|
|
187
|
-
| [009-project-env](009-project-env/spec.md) | Unified Project-Level Environment Variables
|
|
188
|
-
| [018-init-project-file](018-init-project-file/spec.md) | `init --project-file`
|
|
189
|
-
| [019-project-mounts](019-project-mounts/spec.md) | First-Class Mounts Support
|
|
190
|
-
| [022-local-superposition-config](022-local-superposition-config/spec.md) | Local Superposition Config
|
|
188
|
+
| Spec | Title | Status |
|
|
189
|
+
| ------------------------------------------------------------------------ | --------------------------------------------- | ----------- |
|
|
190
|
+
| [002-superposition-config-file](002-superposition-config-file/spec.md) | Project Configuration File | Final |
|
|
191
|
+
| [008-project-file-canonical](008-project-file-canonical/spec.md) | Project File Canonical Form | Approved |
|
|
192
|
+
| [009-project-env](009-project-env/spec.md) | Unified Project-Level Environment Variables | Approved |
|
|
193
|
+
| [018-init-project-file](018-init-project-file/spec.md) | `init --project-file` | Final |
|
|
194
|
+
| [019-project-mounts](019-project-mounts/spec.md) | First-Class Mounts Support | Approved |
|
|
195
|
+
| [022-local-superposition-config](022-local-superposition-config/spec.md) | Local Superposition Config | Implemented |
|
|
196
|
+
| [029-versioned-private-catalogs](029-versioned-private-catalogs/spec.md) | Versioned Private Overlay and Preset Catalogs | Draft |
|
|
@@ -31,6 +31,16 @@ else
|
|
|
31
31
|
exit 1
|
|
32
32
|
fi
|
|
33
33
|
|
|
34
|
+
# Normalize GitHub credential helper for container paths
|
|
35
|
+
# Example broken host value: !/home/linuxbrew/.linuxbrew/bin/gh auth git-credential
|
|
36
|
+
if git config --global --get-all credential.helper 2>/dev/null | grep -Fxq '!/home/linuxbrew/.linuxbrew/bin/gh auth git-credential'; then
|
|
37
|
+
git config --global --fixed-value --unset-all credential.helper '!/home/linuxbrew/.linuxbrew/bin/gh auth git-credential' || true
|
|
38
|
+
fi
|
|
39
|
+
if ! git config --global --get-all credential.helper 2>/dev/null | grep -Fxq '!gh auth git-credential'; then
|
|
40
|
+
git config --global --add credential.helper '!gh auth git-credential'
|
|
41
|
+
echo "✓ GitHub credential helper configured for container gh"
|
|
42
|
+
fi
|
|
43
|
+
|
|
34
44
|
# Set up SSH permissions if .ssh directory exists
|
|
35
45
|
if [ -d "$HOME/.ssh" ]; then
|
|
36
46
|
chmod 700 "$HOME/.ssh"
|
package/package.json
CHANGED