docs: add canonical language spec, governance, and adoption guides

Author: DKFuH

CHANGELOG.md

@@ -9,7 +9,11 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 - Added `orgscript format <file> --check` for canonical formatting checks without rewriting files.
 - Added `npm run format:check:all` and integrated formatting checks into CI.
 - Added `orgscript check <file>` as the combined quality command for validation, linting, and formatting checks.
+- Added `orgscript check <file> --json` for machine-readable combined quality diagnostics.
+- Added `npm run check:all` and switched CI to the combined quality path.
 - Added `orgscript export mermaid <file>` for first-pass Mermaid exports of processes and stateflows.
+- Added a canonical master language spec and lightweight governance guidance.
+- Added an example catalog and an initial VS Code syntax-highlighting scaffold.
 
 ## [0.3.0] - 2026-03-29
 

README.md

@@ -119,18 +119,23 @@ See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/
 - [`docs/language-principles.md`](docs/language-principles.md)
 - [`docs/github-labels.md`](docs/github-labels.md)
 - [`docs/github-project-setup.md`](docs/github-project-setup.md)
+- [`docs/governance.md`](docs/governance.md)
 - [`docs/orgscript-for-humans.md`](docs/orgscript-for-humans.md)
 - [`docs/orgscript-for-ai.md`](docs/orgscript-for-ai.md)
 - [`docs/roadmaps/v0.4.0.md`](docs/roadmaps/v0.4.0.md)
 - [`docs/repository-structure.md`](docs/repository-structure.md)
 - [`docs/syntax.md`](docs/syntax.md)
 - [`docs/semantics.md`](docs/semantics.md)
+- [`examples/README.md`](examples/README.md)
 - [`spec/grammar.ebnf`](spec/grammar.ebnf)
+- [`spec/language-spec.md`](spec/language-spec.md)
 - [`spec/canonical-model.md`](spec/canonical-model.md)
+- [`spec/diagnostics.md`](spec/diagnostics.md)
 - [`examples/craft-business-lead-to-order.orgs`](examples/craft-business-lead-to-order.orgs)
 - [`examples/lead-qualification.orgs`](examples/lead-qualification.orgs)
 - [`examples/order-approval.orgs`](examples/order-approval.orgs)
 - [`examples/service-escalation.orgs`](examples/service-escalation.orgs)
+- [`editors/vscode/README.md`](editors/vscode/README.md)
 - [`packages/parser/README.md`](packages/parser/README.md)
 - [`packages/cli/README.md`](packages/cli/README.md)
 - [`packages/formatter/README.md`](packages/formatter/README.md)
@@ -146,11 +151,14 @@ See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/
 - Canonical format checks: `orgscript format <file> --check`
 - AST-backed linting: `orgscript lint <file>`
 - Combined quality checks: `orgscript check <file>`
+- Machine-readable combined checks: `orgscript check <file> --json`
 - Canonical JSON export: `orgscript export json <file>`
 - Mermaid export for `process` and `stateflow`: `orgscript export mermaid <file>`
-- Machine-readable diagnostics: `orgscript validate <file> --json`, `orgscript lint <file> --json`
+- Machine-readable diagnostics: `orgscript validate <file> --json`, `orgscript lint <file> --json`, `orgscript check <file> --json`
 - Golden snapshot tests for AST, canonical model, and formatter output
 - Stable lint severities: `error`, `warning`, `info`
+- Canonical master spec: [`spec/language-spec.md`](spec/language-spec.md)
+- Initial VS Code syntax-highlighting scaffold: [`editors/vscode`](editors/vscode)
 
 ## Quick start
 
@@ -159,6 +167,7 @@ npm install
 node ./bin/orgscript.js validate ./examples/craft-business-lead-to-order.orgs
 node ./bin/orgscript.js validate ./examples/craft-business-lead-to-order.orgs --json
 node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs
+node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs --json
 node ./bin/orgscript.js format ./examples/craft-business-lead-to-order.orgs
 node ./bin/orgscript.js format ./examples/craft-business-lead-to-order.orgs --check
 node ./bin/orgscript.js lint ./tests/lint/process-missing-trigger.orgs
@@ -173,19 +182,139 @@ Exit codes are CI-friendly:
 - `lint` returns `0` when findings contain only `warning` and `info`, and `1` when findings contain at least one `error`.
 - `check` returns `0` only when validation passes, lint has no `error`, and formatting is canonical. Warnings and info findings alone do not fail `check`.
 
+## JSON diagnostics
+
+OrgScript exposes stable JSON diagnostics for CI, editors, AI systems, and downstream tooling.
+
+`validate --json` on a canonical example:
+
+```json
+{
+  "command": "validate",
+  "file": "examples/craft-business-lead-to-order.orgs",
+  "ok": true,
+  "valid": true,
+  "summary": {
+    "topLevelBlocks": 4,
+    "statements": 47,
+    "diagnostics": 0,
+    "error": 0,
+    "warning": 0,
+    "info": 0
+  },
+  "diagnostics": []
+}
+```
+
+`lint --json` on a warning-only fixture:
+
+```json
+{
+  "command": "lint",
+  "file": "tests/lint/process-missing-trigger.orgs",
+  "ok": true,
+  "clean": true,
+  "summary": {
+    "diagnostics": 1,
+    "error": 0,
+    "warning": 1,
+    "info": 0
+  },
+  "diagnostics": [
+    {
+      "source": "lint",
+      "code": "process-missing-trigger",
+      "severity": "warning",
+      "line": 1,
+      "message": "Process `MissingTrigger` has no `when` trigger."
+    }
+  ]
+}
+```
+
+`check --json` on a clean file:
+
+```json
+{
+  "command": "check",
+  "file": "examples/craft-business-lead-to-order.orgs",
+  "ok": true,
+  "summary": {
+    "diagnostics": 0,
+    "error": 0,
+    "warning": 0,
+    "info": 0
+  },
+  "validate": {
+    "ok": true,
+    "valid": true,
+    "skipped": false,
+    "summary": {
+      "topLevelBlocks": 4,
+      "statements": 47,
+      "diagnostics": 0,
+      "error": 0,
+      "warning": 0,
+      "info": 0
+    },
+    "diagnostics": []
+  },
+  "lint": {
+    "ok": true,
+    "clean": true,
+    "skipped": false,
+    "summary": {
+      "diagnostics": 0,
+      "error": 0,
+      "warning": 0,
+      "info": 0
+    },
+    "diagnostics": []
+  },
+  "format": {
+    "ok": true,
+    "canonical": true,
+    "skipped": false,
+    "summary": {
+      "diagnostics": 0,
+      "error": 0,
+      "warning": 0,
+      "info": 0
+    },
+    "diagnostics": []
+  }
+}
+```
+
 ## Guides
 
 - Human authoring guide: [`docs/orgscript-for-humans.md`](docs/orgscript-for-humans.md)
 - AI interpretation guide: [`docs/orgscript-for-ai.md`](docs/orgscript-for-ai.md)
 - Diagnostics contract: [`spec/diagnostics.md`](spec/diagnostics.md)
+- Canonical language spec: [`spec/language-spec.md`](spec/language-spec.md)
+- Language governance: [`docs/governance.md`](docs/governance.md)
+- Example catalog: [`examples/README.md`](examples/README.md)
+- VS Code editor scaffold: [`editors/vscode/README.md`](editors/vscode/README.md)
+
+## Editor support
+
+OrgScript now ships with a first VS Code syntax-highlighting scaffold under [`editors/vscode`](editors/vscode).
+
+It currently covers:
+
+- `.orgs` file association
+- top-level blocks and core keywords
+- strings, numbers, and operators
+
+See [`editors/vscode/README.md`](editors/vscode/README.md) for local installation and usage notes.
 
 ## Near-term plan
 
-1. Show real JSON diagnostics examples in the README and diagnostics spec.
-2. Improve diagnostics consistency across CLI commands.
-3. Add `orgscript check --json` for machine-readable combined quality output.
-4. Add an initial VS Code syntax highlighting scaffold.
-5. Add a first editor integration path that contributors can install locally.
+1. Expand diagnostics examples and integration guidance around CI and editors.
+2. Improve diagnostics consistency further across human-readable CLI output.
+3. Grow the example catalog across `simple`, `realistic`, and `advanced` scenarios.
+4. Extend editor support beyond the initial VS Code syntax-highlighting scaffold.
+5. Add additional downstream exporters and documentation views.
 
 See [`docs/roadmaps/v0.4.0.md`](docs/roadmaps/v0.4.0.md) for the current milestone plan.
 
@@ -203,6 +332,7 @@ orgscript lint file.orgs --json
 orgscript export json file.orgs
 orgscript export mermaid file.orgs
 orgscript check file.orgs
+orgscript check file.orgs --json
 ```
 
 `orgscript check` runs `validate`, `lint`, and `format --check` in that order and fails on validation errors, lint errors, or formatting drift. Warnings and info findings alone do not fail the command.
@@ -216,6 +346,8 @@ See [`docs/cli-v0.1-plan.md`](docs/cli-v0.1-plan.md) for the implementation plan
 ```text
 npm test
 npm run export:mermaid
+npm run check
+npm run check:all
 npm run format:check:all
 npm run validate:all
 npm run lint:all

ROADMAP.md

@@ -41,6 +41,9 @@
 
 - Open the v0.4.0 developer-experience milestone
 - Prepare issue drafts for formatter checks, diagnostics docs, combined quality checks, diagnostics consistency, and editor support
+- Publish the canonical language spec and governance notes
+- Add the first editor integration scaffold for VS Code
+- Expand diagnostics guidance and example indexing for contributors
 
 ## Later
 

docs/cli-v0.1-plan.md

@@ -19,6 +19,7 @@ Implemented:
 - `validate --json`
 - `lint --json`
 - `check`
+- `check --json`
 
 Planned next:
 
@@ -105,6 +106,8 @@ Output:
 - compact pass/fail summary for each stage
 - clear indication of which stage failed
 - stable text output suitable for CI logs
+- optional machine-readable diagnostics via `--json`
+- easy composition into repo-level wrappers such as `npm run check:all`
 
 Exit behavior:
 
@@ -159,7 +162,7 @@ TypeScript is the fastest start:
 ## Success criteria for v0.1
 
 - One can run `orgscript validate` on example files.
-- One can run `orgscript validate --json` and `orgscript lint --json` for downstream tooling.
+- One can run `orgscript validate --json`, `orgscript lint --json`, and `orgscript check --json` for downstream tooling.
 - One can run `orgscript format` on example files without changing canonical files.
 - One can run `orgscript format --check` in CI or pre-commit workflows.
 - One can run `orgscript check` to combine validation, linting, and format checks.

docs/governance.md

@@ -0,0 +1,38 @@
+# OrgScript Governance
+
+This note defines how the language evolves without losing its canonical shape.
+
+## Principles
+
+- Protect the small core.
+- Prefer explicit semantics over convenience features.
+- Preserve backward compatibility where possible.
+- Treat keyword meaning as stable once documented.
+- Keep the language readable for humans and deterministic for machines.
+
+## Change policy
+
+- Any change to keywords, grammar, canonical modeling, or diagnostics is a spec change.
+- New features should start as a documented proposal before implementation.
+- Experimental ideas should stay out of the canonical spec until they are stable enough to support long-term tooling.
+- If a change can be expressed with existing language forms, prefer that over adding a new construct.
+
+## Core vs tooling vs exporters
+
+- Core language changes affect keywords, grammar, semantics, formatting rules, or the canonical model.
+- Tooling changes affect CLI behavior, diagnostics presentation, editor support, and developer workflow.
+- Exporter changes affect derived outputs such as JSON, Mermaid, Markdown summaries, or HTML documentation.
+- Prefer exporter or tooling extensions over core-language growth when the same user need can be met without changing OrgScript syntax.
+
+## Review expectations
+
+- Check alignment with `spec/language-spec.md`.
+- Check alignment with the manifesto and language principles.
+- Check parser and formatter impact before approving syntax changes.
+- Check canonical model and diagnostic impact before approving semantic changes.
+
+## Versioning guidance
+
+- Make breaking changes only with an explicit version plan.
+- Keep release notes aligned with the canonical spec.
+- When a feature is promoted from draft to canonical, update the spec first and then the supporting docs.

docs/repository-structure.md

@@ -14,6 +14,7 @@ spec/
 
 ```text
 docs/
+  governance.md
   cli-v0.1-plan.md
   language-principles.md
   manifesto.md
@@ -22,11 +23,20 @@ docs/
   syntax.md
 
 examples/
+  README.md
   craft-business-lead-to-order.orgs
   lead-qualification.orgs
   order-approval.orgs
   service-escalation.orgs
 
+editors/
+  vscode/
+    README.md
+    language-configuration.json
+    package.json
+    syntaxes/
+      orgscript.tmLanguage.json
+
 scripts/
   validate-all.js
 
@@ -51,13 +61,16 @@ packages/
 
 spec/
   canonical-model.md
+  diagnostics.md
   grammar.ebnf
+  language-spec.md
 ```
 
 ## Structure principles
 
 - `docs/` explains purpose, language behavior, governance, and roadmap
 - `examples/` demonstrates realistic domain use cases
+- `editors/` contains language-support scaffolds and editor integrations
 - `spec/` holds normative language definitions
 - `src/` contains the current reference implementation
 - `packages/` contains implementation units

docs/roadmaps/v0.4.0.md

@@ -13,6 +13,15 @@ Make OrgScript easier to use in daily development, CI, and editor workflows with
 - editor support foundation
 - stable quality workflows for contributors
 
+## Delivered so far
+
+- `format --check`
+- `check`
+- `check --json`
+- JSON diagnostics examples in the README and diagnostics spec
+- canonical language spec and governance notes
+- initial VS Code syntax-highlighting scaffold
+
 ## Non-goals
 
 - new language keywords
@@ -48,7 +57,7 @@ Make OrgScript easier to use in daily development, CI, and editor workflows with
 ## Success criteria
 
 - CI can verify canonical formatting without rewriting files.
-- README shows real JSON examples for `validate --json` and `lint --json`.
+- README shows real JSON examples for `validate --json`, `lint --json`, and `check --json`.
 - Contributors have one clear quality command for routine checks.
 - CLI output feels predictable in both text and JSON modes.
 - `.orgs` files are easier to read in a mainstream editor.