@dxos/deus 0.0.0-stage → 0.0.0
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/LICENSE +105 -0
- package/README.md +24 -2
- package/bin/deus.ts +42 -0
- package/dist/lib/chunk-blocks.mjs +151 -0
- package/dist/lib/chunk-blocks.mjs.map +1 -0
- package/dist/lib/chunk-check.mjs +452 -0
- package/dist/lib/chunk-check.mjs.map +1 -0
- package/dist/lib/chunk-completion.mjs +112 -0
- package/dist/lib/chunk-completion.mjs.map +1 -0
- package/dist/lib/chunk-extension.mjs +396 -0
- package/dist/lib/chunk-extension.mjs.map +1 -0
- package/dist/lib/chunk-parse.mjs +21 -0
- package/dist/lib/chunk-parse.mjs.map +1 -0
- package/dist/lib/cli.mjs +946 -0
- package/dist/lib/cli.mjs.map +1 -0
- package/dist/lib/extension.mjs +4 -0
- package/dist/lib/index.mjs +6 -0
- package/dist/lib/parse.mjs +4 -0
- package/dist/lib/review.mjs +260 -0
- package/dist/lib/review.mjs.map +1 -0
- package/dist/lib/spec-index.mjs +28 -0
- package/dist/lib/spec-index.mjs.map +1 -0
- package/dist/types/bin/deus.d.ts +3 -0
- package/dist/types/bin/deus.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/changelog.d.ts +25 -0
- package/dist/types/src/cli/changelog.d.ts.map +1 -0
- package/dist/types/src/cli/cli.test.d.ts +2 -0
- package/dist/types/src/cli/cli.test.d.ts.map +1 -0
- package/dist/types/src/cli/errors.d.ts +183 -0
- package/dist/types/src/cli/errors.d.ts.map +1 -0
- package/dist/types/src/cli/features.d.ts +58 -0
- package/dist/types/src/cli/features.d.ts.map +1 -0
- package/dist/types/src/cli/git.d.ts +8 -0
- package/dist/types/src/cli/git.d.ts.map +1 -0
- package/dist/types/src/cli/index.d.ts +12 -0
- package/dist/types/src/cli/index.d.ts.map +1 -0
- package/dist/types/src/cli/lint.d.ts +17 -0
- package/dist/types/src/cli/lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa-lint.d.ts +40 -0
- package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa.d.ts +86 -0
- package/dist/types/src/cli/qa.d.ts.map +1 -0
- package/dist/types/src/cli/review.d.ts +38 -0
- package/dist/types/src/cli/review.d.ts.map +1 -0
- package/dist/types/src/cli/spec-index.d.ts +17 -0
- package/dist/types/src/cli/spec-index.d.ts.map +1 -0
- package/dist/types/src/extension/blocks.d.ts +65 -0
- package/dist/types/src/extension/blocks.d.ts.map +1 -0
- package/dist/types/src/extension/check.d.ts +99 -0
- package/dist/types/src/extension/check.d.ts.map +1 -0
- package/dist/types/src/extension/check.test.d.ts +2 -0
- package/dist/types/src/extension/check.test.d.ts.map +1 -0
- package/dist/types/src/extension/code.d.ts +7 -0
- package/dist/types/src/extension/code.d.ts.map +1 -0
- package/dist/types/src/extension/complete.d.ts +6 -0
- package/dist/types/src/extension/complete.d.ts.map +1 -0
- package/dist/types/src/extension/completion.d.ts +10 -0
- package/dist/types/src/extension/completion.d.ts.map +1 -0
- package/dist/types/src/extension/constants.d.ts +6 -0
- package/dist/types/src/extension/constants.d.ts.map +1 -0
- package/dist/types/src/extension/fences.d.ts +10 -0
- package/dist/types/src/extension/fences.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.d.ts +3 -0
- package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
- package/dist/types/src/extension/index.d.ts +8 -0
- package/dist/types/src/extension/index.d.ts.map +1 -0
- package/dist/types/src/extension/language.d.ts +20 -0
- package/dist/types/src/extension/language.d.ts.map +1 -0
- package/dist/types/src/extension/lint.d.ts +8 -0
- package/dist/types/src/extension/lint.d.ts.map +1 -0
- package/dist/types/src/extension/parse.d.ts +6 -0
- package/dist/types/src/extension/parse.d.ts.map +1 -0
- package/dist/types/src/extension/parser.test.d.ts +2 -0
- package/dist/types/src/extension/parser.test.d.ts.map +1 -0
- package/dist/types/src/extension/refs.d.ts +32 -0
- package/dist/types/src/extension/refs.d.ts.map +1 -0
- package/dist/types/src/extension/refs.test.d.ts +2 -0
- package/dist/types/src/extension/refs.test.d.ts.map +1 -0
- package/dist/types/src/extension/syntax.d.ts +12 -0
- package/dist/types/src/extension/syntax.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/review/fields.d.ts +9 -0
- package/dist/types/src/review/fields.d.ts.map +1 -0
- package/dist/types/src/review/index.d.ts +5 -0
- package/dist/types/src/review/index.d.ts.map +1 -0
- package/dist/types/src/review/review.d.ts +70 -0
- package/dist/types/src/review/review.d.ts.map +1 -0
- package/dist/types/src/review/review.test.d.ts +2 -0
- package/dist/types/src/review/review.test.d.ts.map +1 -0
- package/dist/types/src/review/source-key.d.ts +35 -0
- package/dist/types/src/review/source-key.d.ts.map +1 -0
- package/dist/types/src/review/symbol.d.ts +17 -0
- package/dist/types/src/review/symbol.d.ts.map +1 -0
- package/dist/types/src/review/symbol.test.d.ts +2 -0
- package/dist/types/src/review/symbol.test.d.ts.map +1 -0
- package/dist/types/src/spec-index/index.d.ts +3 -0
- package/dist/types/src/spec-index/index.d.ts.map +1 -0
- package/dist/types/src/spec-index/parse.d.ts +11 -0
- package/dist/types/src/spec-index/parse.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.d.ts +21 -0
- package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/docs/DESIGN.md +561 -0
- package/docs/IDIOMS.md +265 -0
- package/lang/PLUGIN-.template.mdl +115 -0
- package/lang/app.mdl +200 -0
- package/lang/changelog.mdl +184 -0
- package/lang/core.mdl +203 -0
- package/lang/examples/chess-1.mdl +149 -0
- package/lang/examples/chess-2.mdl +203 -0
- package/lang/examples/chess-3.mdl +231 -0
- package/lang/features.mdl +92 -0
- package/lang/plugin.mdl +59 -0
- package/lang/qa.mdl +383 -0
- package/lang/review.mdl +103 -0
- package/lang/sql.mdl +72 -0
- package/package.json +74 -3
- package/src/cli/__fixtures__/bad-decision.mdl +13 -0
- package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
- package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
- package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
- package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
- package/src/cli/__fixtures__/features/TASKS.md +5 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
- package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
- package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
- package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
- package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
- package/src/cli/changelog.ts +122 -0
- package/src/cli/cli.test.ts +359 -0
- package/src/cli/errors.ts +23 -0
- package/src/cli/features.ts +320 -0
- package/src/cli/git.ts +35 -0
- package/src/cli/index.ts +27 -0
- package/src/cli/lint.ts +75 -0
- package/src/cli/qa-lint.ts +206 -0
- package/src/cli/qa.ts +300 -0
- package/src/cli/review.ts +359 -0
- package/src/cli/spec-index.ts +54 -0
- package/src/extension/blocks.ts +169 -0
- package/src/extension/check.test.ts +629 -0
- package/src/extension/check.ts +552 -0
- package/src/extension/code.ts +99 -0
- package/src/extension/complete.ts +34 -0
- package/src/extension/completion.ts +64 -0
- package/src/extension/constants.ts +28 -0
- package/src/extension/fences.ts +270 -0
- package/src/extension/gen/mdl.terms.ts +16 -0
- package/src/extension/gen/mdl.ts +16 -0
- package/src/extension/index.ts +25 -0
- package/src/extension/language.ts +33 -0
- package/src/extension/lint.ts +19 -0
- package/src/extension/mdl.grammar +60 -0
- package/src/extension/parse.ts +31 -0
- package/src/extension/parser.test.ts +248 -0
- package/src/extension/refs.test.ts +95 -0
- package/src/extension/refs.ts +94 -0
- package/src/extension/syntax.ts +25 -0
- package/src/index.ts +6 -0
- package/src/review/fields.ts +31 -0
- package/src/review/index.ts +8 -0
- package/src/review/review.test.ts +111 -0
- package/src/review/review.ts +184 -0
- package/src/review/source-key.ts +63 -0
- package/src/review/symbol.test.ts +47 -0
- package/src/review/symbol.ts +96 -0
- package/src/spec-index/index.ts +6 -0
- package/src/spec-index/parse.ts +22 -0
- package/src/spec-index/spec-index.test.ts +56 -0
- package/src/spec-index/spec-index.ts +49 -0
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.spec.changelog
|
|
3
|
+
name: DSL.Changelog
|
|
4
|
+
version: 1.0
|
|
5
|
+
extends:
|
|
6
|
+
- org.dxos.spec.core
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
The changelog dialect. Adds a `## Changelog` section to a spec: an append-only log of every
|
|
10
|
+
decision that changed it, each one attributed to the person or the agent that made it. The body of
|
|
11
|
+
a spec says what is true now; the changelog says who decided it, when, and why.
|
|
12
|
+
|
|
13
|
+
A spec is written by people and agents together. Typically the person gives coarse direction and
|
|
14
|
+
the agent fills in the gaps. The two carry different authority, so the log keeps their knowledge
|
|
15
|
+
in separate entries: every entry names exactly one decider, typed as `user:` or `agent:`, and
|
|
16
|
+
"which parts of this spec did a person choose?" is a filter, not an archaeology project.
|
|
17
|
+
|
|
18
|
+
## Extensions
|
|
19
|
+
|
|
20
|
+
| Term | URI |
|
|
21
|
+
| ---------- | ---------------------------- |
|
|
22
|
+
| `decision` | `org.dxos.mdl.decision@1.0` |
|
|
23
|
+
| `question` | `org.dxos.mdl.question@1.0` |
|
|
24
|
+
|
|
25
|
+
## Actors
|
|
26
|
+
|
|
27
|
+
Every actor reference carries one of two prefixes. The prefix is the point of the dialect: the
|
|
28
|
+
linter rejects a `by:` without one.
|
|
29
|
+
|
|
30
|
+
| Form | Who | Example |
|
|
31
|
+
| ----------------- | ----------------------------------------------------- | ----------------------------- |
|
|
32
|
+
| `user:<handle>` | A person, by GitHub username or email. | `user:alice`, `user:a@b.org` |
|
|
33
|
+
| `agent:<name>` | An agent, by harness or product name — never a model. | `agent:claude-code` |
|
|
34
|
+
|
|
35
|
+
Name an agent by what ran it (`agent:claude-code`, `agent:composer-assistant`), not by the model
|
|
36
|
+
that served it: models change mid-session and the name must stay stable across the log.
|
|
37
|
+
|
|
38
|
+
## Rules
|
|
39
|
+
|
|
40
|
+
1. **Every change to a spec adds a decision.** A change to anything outside `## Changelog` comes
|
|
41
|
+
with at least one new entry in the same change. The check
|
|
42
|
+
`pnpm deus changelog check` enforces this in CI. Trivial edits are exempt:
|
|
43
|
+
whitespace, and fixes of at most 3 words by 1–2 letters each, excluding words with digits and
|
|
44
|
+
normative words. A bulk mechanical edit, or a change with no spec decision behind it (rule 9),
|
|
45
|
+
may be waived with a `Spec-Changelog-Skip: <reason>` commit trailer.
|
|
46
|
+
2. **One decider per entry.** An entry is `by:` exactly one `user:` or `agent:`. Knowledge from
|
|
47
|
+
two sources is two entries, even when they land in the same edit.
|
|
48
|
+
3. **A person's input is recorded faithfully, first.** When a person gives direction, the first
|
|
49
|
+
entry is `by: user:<them>` and restates what they said in spec terms. The recording agent may
|
|
50
|
+
resolve references ("it", "the canvas" → `Scene`), include the context needed to read the entry
|
|
51
|
+
on its own, and fix wording. It must not add or remove information: no requirement, rationale or
|
|
52
|
+
assumption the person did not give, and nothing they said left out. Prompts are messy, so the
|
|
53
|
+
entry is a clean statement of their intent, not a transcript. The decider is who chose, not who
|
|
54
|
+
typed: an agent writes this entry, the person made it.
|
|
55
|
+
4. **What the agent adds is a separate entry.** Gaps the agent filled — shapes, names, edge cases,
|
|
56
|
+
a reading of an ambiguous instruction — go in later `by: agent:<name>` entries, one per
|
|
57
|
+
independent choice, referring to the entry they build on (`Fills in [D-1]`).
|
|
58
|
+
5. **An agent entry names its principal.** `for:` is the person whose instruction the agent was
|
|
59
|
+
acting under. It is required on `agent:` entries and forbidden on `user:` entries.
|
|
60
|
+
6. **Approval is a decision.** A person who reviews and accepts agent entries makes a new
|
|
61
|
+
`user:` entry saying so ("Approve [D-2] and [D-3]."). Nothing in the approved entry changes.
|
|
62
|
+
7. **Append-only.** Never edit or delete an entry. To reverse or refine one, append a new entry
|
|
63
|
+
with `supersedes: D-n`. The superseded entry stays — it is the trace.
|
|
64
|
+
8. **Identifiers are monotonic, newest last.** `D-1`, `D-2`, … in the order appended. Never reuse
|
|
65
|
+
or renumber.
|
|
66
|
+
9. **Only spec decisions.** An entry records a choice about the specified system: its behavior,
|
|
67
|
+
requirements, structure, interfaces, data, tests, or the reason for one of those. How the authors
|
|
68
|
+
worked is not a decision: which tool or skill they used, how the spec is shared or reviewed, which
|
|
69
|
+
PR a change goes in, that the document exists, has diagrams, or was reorganized. When a person's
|
|
70
|
+
instruction is only about process, follow it and record nothing. A spec change with no decision
|
|
71
|
+
behind it carries the `Spec-Changelog-Skip` trailer instead. `.agents/skills/mdl/scripts/check-decisions.ts` checks
|
|
72
|
+
new entries with TypeSafe System One.
|
|
73
|
+
10. **An open question is a `question`, and its answer is a decision.** A choice the spec needs but
|
|
74
|
+
nobody has made yet goes in `## Changelog` as `question Q-n`, attributed like a decision. It is
|
|
75
|
+
answered by appending a `decision` whose `answers:` names it; the decider is whoever answered.
|
|
76
|
+
The question itself is never edited, so "answered" is derived, not stored. Only the first
|
|
77
|
+
decision that answers a question counts; to change the answer, supersede that decision.
|
|
78
|
+
Question ids are `Q-1`, `Q-2`, … in the order asked, a sequence of their own.
|
|
79
|
+
|
|
80
|
+
## Definitions
|
|
81
|
+
|
|
82
|
+
```mdl
|
|
83
|
+
ext decision
|
|
84
|
+
uri: org.dxos.mdl.decision@1.0
|
|
85
|
+
desc: |
|
|
86
|
+
One decision about the spec, attributed to exactly one actor. The inline prose is the decision
|
|
87
|
+
itself, stated as what is now true ("Bounds are derived, never stored."), not as the edit
|
|
88
|
+
that was made.
|
|
89
|
+
fields:
|
|
90
|
+
date: Date # YYYY-MM-DD, the day the decision was made
|
|
91
|
+
by: ActorRef # user:<handle> | agent:<name> — the decider
|
|
92
|
+
for?: UserRef # agent entries only: the person the agent acted for
|
|
93
|
+
affects?: RefList # block ids the decision constrains, e.g. [Scene, F-2.1]
|
|
94
|
+
supersedes?: Identifier # an earlier decision this one replaces
|
|
95
|
+
why?: Prose # the reason; on a user entry, only a reason the person gave
|
|
96
|
+
rejected?: ProseList # alternatives considered and why they lost
|
|
97
|
+
source?: URI # PR, review comment, issue, or session where it was made
|
|
98
|
+
answers?: Identifier # a question this decision answers, e.g. Q-1
|
|
99
|
+
inline-prose: true
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```mdl
|
|
103
|
+
ext question
|
|
104
|
+
uri: org.dxos.mdl.question@1.0
|
|
105
|
+
desc: |
|
|
106
|
+
A choice the spec needs that nobody has made yet, attributed to the actor that asked it. The
|
|
107
|
+
inline prose is the question. It is answered by a later `decision` whose `answers:` names it.
|
|
108
|
+
fields:
|
|
109
|
+
date: Date # YYYY-MM-DD, the day it was asked
|
|
110
|
+
by: ActorRef # user:<handle> | agent:<name> — who asked
|
|
111
|
+
for?: UserRef # agent questions only: the person the agent acted for
|
|
112
|
+
affects?: RefList # block ids the answer will constrain
|
|
113
|
+
context?: Prose # why it is asked, and what depends on the answer
|
|
114
|
+
options?: ProseList # suggested answers, each `<title>: <description>`
|
|
115
|
+
source?: URI # PR, review comment, issue, or session where it was asked
|
|
116
|
+
inline-prose: true
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Example
|
|
120
|
+
|
|
121
|
+
A person asks for a feature in one line; the agent records it, then fills it in; the person
|
|
122
|
+
approves part of it and overrides the rest.
|
|
123
|
+
|
|
124
|
+
```mdl
|
|
125
|
+
decision D-1: The `Scene` canvas grows to fit its content when a node moves past its edge.
|
|
126
|
+
date: 2026-10-02
|
|
127
|
+
by: user:alice
|
|
128
|
+
affects: [Scene]
|
|
129
|
+
source: https://github.com/dxos/dxos/pull/<n>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
```mdl
|
|
133
|
+
decision D-2: Bounds are derived from content, never stored. Fills in [D-1].
|
|
134
|
+
date: 2026-10-02
|
|
135
|
+
by: agent:claude-code
|
|
136
|
+
for: user:alice
|
|
137
|
+
affects: [Scene]
|
|
138
|
+
why: Stored bounds drift from the content whenever a node moves outside an edit path.
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
```mdl
|
|
142
|
+
decision D-3: Bounds grow to the major grid. Fills in [D-1].
|
|
143
|
+
date: 2026-10-02
|
|
144
|
+
by: agent:claude-code
|
|
145
|
+
for: user:alice
|
|
146
|
+
affects: [Scene, F-2.1]
|
|
147
|
+
why: Growing to the minor grid re-lays the canvas on every drag step.
|
|
148
|
+
rejected:
|
|
149
|
+
- Fixed padding: clips large nodes at the edge.
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
```mdl
|
|
153
|
+
decision D-4: Approve [D-2].
|
|
154
|
+
date: 2026-10-05
|
|
155
|
+
by: user:alice
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
```mdl
|
|
159
|
+
decision D-5: Bounds grow to the minor grid while dragging and snap to the major grid on drop, because growing to the major grid feels laggy.
|
|
160
|
+
date: 2026-10-05
|
|
161
|
+
by: user:alice
|
|
162
|
+
supersedes: D-3
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The agent meets a choice it should not make alone, and asks; the person's answer is a decision.
|
|
166
|
+
|
|
167
|
+
```mdl
|
|
168
|
+
question Q-1: Does the canvas shrink when nodes are removed?
|
|
169
|
+
date: 2026-10-06
|
|
170
|
+
by: agent:claude-code
|
|
171
|
+
for: user:alice
|
|
172
|
+
affects: [Scene]
|
|
173
|
+
context: [D-1] grows the bounds; nothing says whether they ever shrink.
|
|
174
|
+
options:
|
|
175
|
+
- Never: bounds only grow, so the view never jumps under the reader.
|
|
176
|
+
- On drop: bounds fit the content again after each edit.
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
```mdl
|
|
180
|
+
decision D-6: Never.
|
|
181
|
+
date: 2026-10-07
|
|
182
|
+
by: user:alice
|
|
183
|
+
answers: Q-1
|
|
184
|
+
```
|
package/lang/core.mdl
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.spec.core
|
|
3
|
+
name: DSL.Core
|
|
4
|
+
version: 1.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
The minimal base language. Defines document format and the `ext` primitive only.
|
|
8
|
+
All domain constructs — type, op, feat, scenario, test, ui, db, service, etc. — are extensions.
|
|
9
|
+
|
|
10
|
+
## Document Format
|
|
11
|
+
|
|
12
|
+
A `.mdl` file has three parts:
|
|
13
|
+
|
|
14
|
+
1. **Frontmatter** — YAML block delimited by `---`. Contains document metadata.
|
|
15
|
+
2. **Body** — Standard Markdown prose, headings, and lists.
|
|
16
|
+
3. **Blocks** — Typed fenced sections carrying structured declarations.
|
|
17
|
+
|
|
18
|
+
### Frontmatter
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
id: URI # globally unique document identifier
|
|
22
|
+
name: Identifier # human-readable name
|
|
23
|
+
version: SemVer # document version
|
|
24
|
+
extends?: URI[] # specs this document extends (transitive)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Blocks
|
|
28
|
+
|
|
29
|
+
All blocks use the `mdl` fence. The first line of the body declares the block
|
|
30
|
+
type, optional identifier, and optional title:
|
|
31
|
+
|
|
32
|
+
````
|
|
33
|
+
```mdl
|
|
34
|
+
<type> [<id>][: <title>]
|
|
35
|
+
key: value
|
|
36
|
+
key?: TypeExpr
|
|
37
|
+
key: a | b | c
|
|
38
|
+
```
|
|
39
|
+
````
|
|
40
|
+
|
|
41
|
+
- `<type>` must be declared in the Extensions section of this document or an ancestor.
|
|
42
|
+
- `<id>` is an optional locally-scoped identifier (e.g. `F-1.1`, `Board`).
|
|
43
|
+
- `<title>` is optional human-readable prose after the colon.
|
|
44
|
+
- Block identifiers must be unique within the document.
|
|
45
|
+
|
|
46
|
+
### Block Body Syntax
|
|
47
|
+
|
|
48
|
+
Within a block, the body is a sequence of key-value pairs:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
key: value # scalar
|
|
52
|
+
key: a | b | c # union list (literals)
|
|
53
|
+
key?: TypeExpr # optional field declaration
|
|
54
|
+
key: # multi-line value
|
|
55
|
+
- item one
|
|
56
|
+
- item two
|
|
57
|
+
# comment
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
When an extension declares `inline-prose: true`, prose may appear between
|
|
61
|
+
the header line and the first key-value pair:
|
|
62
|
+
|
|
63
|
+
````
|
|
64
|
+
```mdl
|
|
65
|
+
feat F-1: Start Game
|
|
66
|
+
A new Board is created with pieces in starting positions. ← inline prose
|
|
67
|
+
req F-1.1: White moves first.
|
|
68
|
+
```
|
|
69
|
+
````
|
|
70
|
+
|
|
71
|
+
### Cross-References
|
|
72
|
+
|
|
73
|
+
Any declared block identifier may be referenced elsewhere in the document as `[<id>]`.
|
|
74
|
+
The linter verifies that all references resolve to a declared block.
|
|
75
|
+
|
|
76
|
+
### External References
|
|
77
|
+
|
|
78
|
+
A spec names a block of another spec as `<spec id>#<item>`, where the item is a block id or `req` id
|
|
79
|
+
(`com.acme.canvas#F-3.1`), and declares that spec under `## Dependencies` (below). A
|
|
80
|
+
block may name code, or anything else outside the specs, by **source key**:
|
|
81
|
+
`github:<owner>/<repo>/<path>[#<fragment>]`, with the path relative to the repository root.
|
|
82
|
+
|
|
83
|
+
| Key names | Example | Fragment |
|
|
84
|
+
| ------------------- | -------------------------------------------------------------- | ------------------- |
|
|
85
|
+
| A code symbol | `github:dxos/dxos/packages/sdk/types/src/types/Spec.ts#make` | Symbol (`A.b` ok) |
|
|
86
|
+
| A whole file | `github:dxos/dxos/packages/apps/composer-app/vite.config.ts` | none |
|
|
87
|
+
|
|
88
|
+
A spec does not name the code that implements it: those links are annotations kept outside the
|
|
89
|
+
spec (a review's `evidence:`, see `review.mdl`), and the spec viewer renders them as decorations
|
|
90
|
+
beside the items they annotate. Tools resolve keys against a local checkout of the repository. A
|
|
91
|
+
key is a location, not a version: it names whatever the checkout holds.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Extensions Section
|
|
96
|
+
|
|
97
|
+
Every document that uses non-core block types MUST declare them:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
## Extensions
|
|
101
|
+
|
|
102
|
+
| Term | URI |
|
|
103
|
+
|----------|----------------------------|
|
|
104
|
+
| `type` | dxos.spec/ext/type@1.0 |
|
|
105
|
+
| `feat` | dxos.spec/ext/feat@1.0 |
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
An extension definition is either:
|
|
109
|
+
- **External** — resolved by URI (registry lookup, future tooling).
|
|
110
|
+
- **Inline** — defined in the document's Appendix using `ext` blocks.
|
|
111
|
+
|
|
112
|
+
A document may use both: external URIs for standard extensions,
|
|
113
|
+
inline `ext` blocks for custom or experimental ones.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Dependencies Section
|
|
118
|
+
|
|
119
|
+
A spec lists the other specs it builds on under `## Dependencies`, after the opening prose and
|
|
120
|
+
before `## Extensions`, one `uses` block per spec. A Composer plugin's runtime dependencies are the
|
|
121
|
+
exception: they go in its `plugin` block's `dependsOn` (plugin dialect) and are never repeated under
|
|
122
|
+
`uses`. The identifier is the depended-on spec's `id`;
|
|
123
|
+
the inline prose is required and says what this spec takes from it.
|
|
124
|
+
|
|
125
|
+
```mdl
|
|
126
|
+
ext uses
|
|
127
|
+
uri: dxos.spec.core/uses
|
|
128
|
+
desc: Declares that this spec builds on another spec, identified by its frontmatter id.
|
|
129
|
+
inline-prose: true
|
|
130
|
+
fields:
|
|
131
|
+
id: URI # the depended-on spec's id (the block identifier)
|
|
132
|
+
syntax: |
|
|
133
|
+
uses org.dxos.ui.react-ui-canvas: The engine whose types and operations this canvas models.
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
A reference into another spec is `<spec id>#<item>`, where the item is any block id or `req` id.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## The `ext` Primitive
|
|
141
|
+
|
|
142
|
+
`ext` is the only block type the core language natively provides.
|
|
143
|
+
It is self-describing — defined here using itself:
|
|
144
|
+
|
|
145
|
+
```mdl
|
|
146
|
+
ext ext
|
|
147
|
+
uri: dxos.spec.core/ext
|
|
148
|
+
desc: Declares a new block type or extends an existing one.
|
|
149
|
+
fields:
|
|
150
|
+
uri: URI # canonical identifier for this extension (required)
|
|
151
|
+
desc: Prose # human description (required)
|
|
152
|
+
extends?: ExtRef # parent extension — inherits all parent fields
|
|
153
|
+
fields?: FieldMap # fields valid on instances of this block type
|
|
154
|
+
adds-fields?: FieldMap # additional fields merged into parent (use with extends)
|
|
155
|
+
nesting?: self | none # whether instances may contain same-type blocks
|
|
156
|
+
inline-prose?: Boolean # first non-key line treated as prose value
|
|
157
|
+
syntax?: CodeBlock # reference syntax (non-normative)
|
|
158
|
+
example?: CodeBlock # usage example (non-normative)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Primitive Types
|
|
164
|
+
|
|
165
|
+
The following types are available in `ext` field declarations.
|
|
166
|
+
They are the vocabulary of the meta-language.
|
|
167
|
+
|
|
168
|
+
| Type | Description |
|
|
169
|
+
|--------------|--------------------------------------------------------------|
|
|
170
|
+
| `Prose` | Free-form text, single or multi-line |
|
|
171
|
+
| `Identifier` | Alphanumeric name, hyphens allowed — e.g. `Board`, `F-1` |
|
|
172
|
+
| `URI` | Dot-path or URL identifier — e.g. `dxos.spec/ext/type@1.0` |
|
|
173
|
+
| `SemVer` | Semantic version string — e.g. `1.0.0` |
|
|
174
|
+
| `Boolean` | `true` or `false` |
|
|
175
|
+
| `TypeExpr` | Type reference or inline type — e.g. `Color`, `Piece?` |
|
|
176
|
+
| `FieldMap` | Named fields: `name[?]: TypeExpr # comment` |
|
|
177
|
+
| `UnionList` | Pipe-separated literals: `a \| b \| c` |
|
|
178
|
+
| `ProseList` | Bulleted list of prose items |
|
|
179
|
+
| `CodeBlock` | Literal indented or fenced text |
|
|
180
|
+
| `ExtRef` | Reference to a declared extension name |
|
|
181
|
+
| `TagList` | Space or comma-separated tag identifiers |
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Resolution Rules
|
|
186
|
+
|
|
187
|
+
1. When a block type appears in a document body, the linter looks it up
|
|
188
|
+
in the nearest enclosing Extensions table (this document or any ancestor).
|
|
189
|
+
2. If the URI resolves to an inline `ext` block in an Appendix, that definition is used.
|
|
190
|
+
3. If the URI is external, the linter fetches the definition from a registry.
|
|
191
|
+
4. An unresolvable block type is a lint error.
|
|
192
|
+
5. Field names not declared in the `ext` definition are lint warnings.
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Non-Goals
|
|
197
|
+
|
|
198
|
+
The core language deliberately omits:
|
|
199
|
+
|
|
200
|
+
- Execution semantics — `.mdl` is a specification, not a program.
|
|
201
|
+
- Type checking — field values are not verified against TypeExpr at the core level.
|
|
202
|
+
- Ordering constraints — sections may appear in any order.
|
|
203
|
+
- Verification — requirements are semi-formal; the language is not a proof system.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: org.dxos.plugin.chess
|
|
3
|
+
name: ChessPlugin
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
A two-player chess game plugin for `DXOS` Composer.
|
|
8
|
+
|
|
9
|
+
## Extensions
|
|
10
|
+
|
|
11
|
+
The following extension dialects are used in this document.
|
|
12
|
+
Each extension is defined in the Appendix or resolved via its URI.
|
|
13
|
+
|
|
14
|
+
| Term | URI |
|
|
15
|
+
|--------|-----------------------------|
|
|
16
|
+
| `type` | `org.dxos.mdl.type@1.0` |
|
|
17
|
+
| `feat` | `org.dxos.mdl.feat@1.0` |
|
|
18
|
+
| `scenario` | `org.dxos.mdl.scenario@1.0` |
|
|
19
|
+
|
|
20
|
+
## Types
|
|
21
|
+
|
|
22
|
+
```mdl
|
|
23
|
+
type Color
|
|
24
|
+
literals: white | black
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```mdl
|
|
28
|
+
type PieceKind
|
|
29
|
+
literals: pawn | rook | knight | bishop | queen | king
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```mdl
|
|
33
|
+
type Piece
|
|
34
|
+
fields:
|
|
35
|
+
kind: PieceKind
|
|
36
|
+
color: Color
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```mdl
|
|
40
|
+
type Square
|
|
41
|
+
fields:
|
|
42
|
+
file: a | b | c | d | e | f | g | h
|
|
43
|
+
rank: 1..8
|
|
44
|
+
piece?: Piece
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```mdl
|
|
48
|
+
type Move
|
|
49
|
+
fields:
|
|
50
|
+
from: Square
|
|
51
|
+
to: Square
|
|
52
|
+
promotion?: PieceKind # only valid for pawn reaching back rank
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
```mdl
|
|
56
|
+
type Board
|
|
57
|
+
fields:
|
|
58
|
+
squares: Square[8][8]
|
|
59
|
+
turn: Color
|
|
60
|
+
status: playing | check | checkmate | stalemate
|
|
61
|
+
moves: Move[] # full move history
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Features
|
|
65
|
+
|
|
66
|
+
```mdl
|
|
67
|
+
feat F-1: Start Game
|
|
68
|
+
|
|
69
|
+
req F-1.1: New Board created with pieces in standard starting positions.
|
|
70
|
+
req F-1.2: White moves first.
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```mdl
|
|
74
|
+
feat F-2: Make Move
|
|
75
|
+
|
|
76
|
+
req F-2.1:
|
|
77
|
+
when: player submits a Move on their turn
|
|
78
|
+
then: Move validated against chess rules
|
|
79
|
+
errors: [InvalidMove, WrongTurn, GameOver]
|
|
80
|
+
|
|
81
|
+
req F-2.2:
|
|
82
|
+
when: Move is valid
|
|
83
|
+
then: Board updated; turn advances to opponent
|
|
84
|
+
|
|
85
|
+
req F-2.3:
|
|
86
|
+
when: resulting position leaves opponent's king in check
|
|
87
|
+
then: Board.status set to check
|
|
88
|
+
|
|
89
|
+
req F-2.4:
|
|
90
|
+
when: no legal moves remain for the side to move
|
|
91
|
+
then: Board.status set to checkmate (if in check) or stalemate
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Acceptance
|
|
95
|
+
|
|
96
|
+
```mdl
|
|
97
|
+
scenario T-1: New game starting position
|
|
98
|
+
given: a new game is started
|
|
99
|
+
then:
|
|
100
|
+
- Board.turn === white
|
|
101
|
+
- Board.status === playing
|
|
102
|
+
- each player has 16 pieces in standard positions
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
```mdl
|
|
106
|
+
scenario T-2: Illegal move rejected
|
|
107
|
+
given: it is white's turn
|
|
108
|
+
when: white attempts to move a black piece
|
|
109
|
+
then: WrongTurn error; Board unchanged
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Appendix: Extension Definitions
|
|
115
|
+
|
|
116
|
+
Extension block types used in this document are defined below using
|
|
117
|
+
the core `ext` primitive — the only construct the base language provides.
|
|
118
|
+
|
|
119
|
+
```mdl
|
|
120
|
+
ext type
|
|
121
|
+
uri: org.dxos.mdl.type@1.0
|
|
122
|
+
desc: A named data structure with typed fields and optional literals.
|
|
123
|
+
fields:
|
|
124
|
+
desc?: Prose
|
|
125
|
+
fields?: FieldMap # name[?]: TypeExpr (# inline comment)
|
|
126
|
+
literals?: UnionList # a | b | c
|
|
127
|
+
extends?: TypeRef[]
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
```mdl
|
|
131
|
+
ext feat
|
|
132
|
+
uri: org.dxos.mdl.feat@1.0
|
|
133
|
+
desc: A named feature grouping one or more requirements.
|
|
134
|
+
fields:
|
|
135
|
+
desc?: Prose
|
|
136
|
+
req: RequirementList
|
|
137
|
+
nesting: self # feat blocks may contain feat blocks
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
```mdl
|
|
141
|
+
ext scenario
|
|
142
|
+
uri: org.dxos.mdl.scenario@1.0
|
|
143
|
+
desc: An acceptance scenario expressed as given / when / then steps.
|
|
144
|
+
fields:
|
|
145
|
+
given?: Step | Step[]
|
|
146
|
+
when?: Step | Step[]
|
|
147
|
+
then: Step | Step[]
|
|
148
|
+
tags?: TagList
|
|
149
|
+
```
|