diff --git a/docs/topics/README.md b/docs/topics/README.md index 8c7c0c2c..db2cff79 100644 --- a/docs/topics/README.md +++ b/docs/topics/README.md @@ -10,15 +10,44 @@ short path to the authoritative surface. ## Topic Map -| Task | Start Here | Authority | -| ------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------ | -| Decide whether a change belongs in Wesley or an extension. | [Compiler Boundary](./compiler-boundary.md) | `docs/design/0014-domain-empty-core-boundary/` | -| Configure schema sets, changed-schema selection, or targets. | [Project Manifests](./project-manifests.md) | `docs/reference/project-manifest.md` | -| Author or review descriptor-only extension fixtures. | [Compiler Boundary](./compiler-boundary.md) | `docs/guides/module-authoring.md` | -| Choose local checks before a PR or release. | [Validation](./validation.md) | `cargo xtask preflight`, `docs/governance/RELEASE_POLICY.md` | -| Understand HOLMES CI and evidence artifacts. | [HOLMES CI](./holmes-ci.md) | `.github/workflows/wesley-holmes.yml`, `docs/architecture/` | -| Prepare or judge a release. | [Releases](./releases.md) | `docs/method/release-runbook.md`, `docs/governance/` | -| Triage issues into release lanes. | [Issue Triage](./contributing/triage.md) | GitHub Issues, Milestones, Projects, and labels | +### Compiler Use + +| Task | Start Here | Authority | +| ----------------------------------------- | ----------------------------------------------- | ------------------------------------------ | +| Run the current product command surface. | [Native CLI](./native-cli.md) | `docs/reference/cli.md` | +| Inspect GraphQL lowering, hashes, or IR. | [Schema And IR](./schema-ir.md) | `docs/reference/cli.md#schema` | +| Work with operations and directive args. | [Operations](./operations.md) | `docs/reference/cli.md#operation` | +| Use or classify GraphQL directives. | [Directives](./directives.md) | `docs/reference/directives.md` | +| Author or validate `weslaw/v1`. | [Weslaw](./weslaw.md) | `docs/design/0019-weslaw-semantic-law-ir/` | +| Emit Rust, TypeScript, or LE-binary code. | [Emitters](./emitters.md) | `docs/reference/cli.md#emit` | +| Understand generated files and caches. | [Artifacts And Cache](./artifacts-and-cache.md) | `docs/build-artifacts.md` | + +### Boundaries And Extension + +| Task | Start Here | Authority | +| ------------------------------------------------------------ | ------------------------------------------- | ---------------------------------------------- | +| Decide whether a change belongs in Wesley or an extension. | [Compiler Boundary](./compiler-boundary.md) | `docs/design/0014-domain-empty-core-boundary/` | +| Configure schema sets, changed-schema selection, or targets. | [Project Manifests](./project-manifests.md) | `docs/reference/project-manifest.md` | +| Author or review descriptor-only extension fixtures. | [Extension Modules](./extension-modules.md) | `docs/guides/module-authoring.md` | +| Handle old Node, host, or package references. | [Legacy Node Retirement](./legacy-node.md) | `docs/LEGACY_NODE_MIGRATION.md` | +| Check durable repo properties. | [Invariants](./invariants.md) | `docs/invariants/README.md` | + +### Assurance, CI, And Release + +| Task | Start Here | Authority | +| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | +| Choose local checks before a PR or release. | [Validation](./validation.md) | `cargo xtask preflight`, `docs/governance/RELEASE_POLICY.md` | +| Interpret GitHub Actions checks. | [CI Workflows](./ci-workflows.md) | `docs/ci.md`, `.github/workflows/` | +| Understand HOLMES CI and PR comments. | [HOLMES CI](./holmes-ci.md) | `.github/workflows/wesley-holmes.yml`, `docs/architecture/` | +| Work with assurance evidence and policies. | [Assurance Evidence](./assurance-evidence.md) | `docs/holmes-policy-spec.md` | +| Prepare or judge a release. | [Releases](./releases.md) | `docs/method/release-runbook.md`, `docs/governance/` | + +### Contributor Process + +| Task | Start Here | Authority | +| --------------------------------- | ----------------------------------------- | ----------------------------------------------- | +| Triage issues into release lanes. | [Issue Triage](./contributing/triage.md) | GitHub Issues, Milestones, Projects, and labels | +| Keep docs accurate and covered. | [Docs Maintenance](./docs-maintenance.md) | `docs/governance/DOCUMENTATION_STANDARD.md` | ## Coverage Rule @@ -27,6 +56,10 @@ either cover that workflow directly or link clearly to the current authoritative page. Topic pages may summarize, but they must not duplicate live roadmap state, issue counts, or release progress. +When a PR adds or materially changes a public capability, command family, +workflow, invariant, release procedure, or extension boundary, update this topic +map or state why the existing topic path already covers it. + The release gate for this directory is defined in [`docs/governance/RELEASE_POLICY.md`](../governance/RELEASE_POLICY.md) and the execution runbook in [`docs/method/release-runbook.md`](../method/release-runbook.md). diff --git a/docs/topics/artifacts-and-cache.md b/docs/topics/artifacts-and-cache.md new file mode 100644 index 00000000..c6840982 --- /dev/null +++ b/docs/topics/artifacts-and-cache.md @@ -0,0 +1,36 @@ +# Artifacts And Cache + + + +Use this topic when generated files, cache directories, evidence bundles, or +report artifacts appear in the checkout. + +Generated outputs are disposable unless a specific release or audit process +says otherwise. Source files, manifests, docs, tests, and checked-in fixtures +remain the durable repo truth. + +## Common Locations + +| Location | Meaning | +| --------------------------------- | --------------------------------------------------------------- | +| `.wesley-cache/` | Default generated evidence/cache location for Wesley workflows. | +| `out/` | Default output root for explicit native emit commands. | +| `test/fixtures/**/out/` | Fixture-generated artifacts. | +| `test/fixtures/**/.wesley-cache/` | Fixture-generated evidence bundles. | +| `coverage/` | Test coverage output. | +| `dist/` | Package build output where retained packages emit bundles. | +| `reports-by-schema/` | HOLMES workflow staging layout for schema-scoped reports. | + +## Rules Of Thumb + +- If a generated path is gitignored, assume it can be deleted and regenerated. +- Do not make generated files an authority over authored GraphQL. +- External targets own their own cache and output layouts. +- HOLMES report artifacts are evidence surfaces, not source inputs. + +## Related Authority + +- [Build Artifacts Reference](../build-artifacts.md) +- [Project Manifests](./project-manifests.md) +- [HOLMES CI](./holmes-ci.md) +- [Validation](./validation.md) diff --git a/docs/topics/assurance-evidence.md b/docs/topics/assurance-evidence.md new file mode 100644 index 00000000..6117569e --- /dev/null +++ b/docs/topics/assurance-evidence.md @@ -0,0 +1,43 @@ +# Assurance Evidence + + + +Use this topic when a change touches HOLMES, Watson, Moriarty, BLADE, policy +templates, evidence bundles, or report interpretation. + +Assurance tooling judges explicit evidence. It does not replace the compiler, +and it does not create product semantics for GraphQL. + +## Current Surfaces + +| Surface | Use For | +| ------------------------------------- | --------------------------------------------------------- | +| `packages/wesley-holmes/` | Retained JavaScript assurance reporting tools. | +| `crates/wesley-holmes/` | Rust foundation for assurance data models and validation. | +| `docs/holmes-policy/` | Policy documentation. | +| `docs/templates/holmes-policy/` | Policy templates for host contexts. | +| `docs/architecture/holmes-*` | Architecture and integration notes. | +| `.github/workflows/wesley-holmes.yml` | Pull request assurance workflow. | + +## Rules Of Thumb + +- Reports should expose unavailable or invalid evidence honestly. +- Missing artifacts should not be hidden behind a passing workflow. +- Policy and report quality are evidence questions, not compiler semantics. +- Domain-specific target facts should be produced by the owning target module. + +## Useful Checks + +```bash +node --test packages/wesley-holmes/test/pr-comment.test.mjs +BATS_LIB_PATH=test/vendor bats -t test/ci-workflows.bats +cargo test -p wesley-holmes +``` + +## Related Authority + +- [HOLMES CI](./holmes-ci.md) +- [HOLMES Architecture](../architecture/holmes-architecture.md) +- [HOLMES Integration](../architecture/holmes-integration.md) +- [HOLMES Policy Spec](../holmes-policy-spec.md) +- [Policy Templates](../templates/holmes-policy/README.md) diff --git a/docs/topics/ci-workflows.md b/docs/topics/ci-workflows.md new file mode 100644 index 00000000..51e771e2 --- /dev/null +++ b/docs/topics/ci-workflows.md @@ -0,0 +1,56 @@ +# CI Workflows + + + +Use this topic when choosing or interpreting GitHub Actions checks. + +CI protects the Rust product spine, repository hygiene, retained package +surfaces, and assurance evidence. It is not a substitute for reading the local +diff or running focused checks before a PR. + +## Check Families + +| Family | Protects | +| ---------------------------- | -------------------------------------------------- | +| Rust product preflight | Native compiler crates, CLI, tests, clippy. | +| Repository hygiene preflight | Docs links, truth manifest, policy hygiene. | +| Compatibility smoke | Workspace compatibility and Rust product smoke. | +| CodeQL / analysis | Static analysis for supported languages. | +| Dependency review | Dependency risk in PRs. | +| HOLMES workflow | Schema-selected assurance reports and PR comments. | + +## Local Mirrors + +Run the full product gate: + +```bash +cargo xtask preflight +``` + +Run docs-only checks: + +```bash +cargo xtask docs-check +git diff --check +``` + +Run workflow invariant tests: + +```bash +BATS_LIB_PATH=test/vendor bats -t test/ci-workflows.bats +``` + +## Rules Of Thumb + +- A skipped HOLMES matrix can be correct when no schema set is selected. +- Browser, Bun, and Deno host experiment workflows are retired from Wesley. +- Required checks should name the Rust product or repository hygiene surface + they protect. +- Do not widen workflow permissions or secret exposure casually. + +## Related Authority + +- [Continuous Integration](../ci.md) +- [HOLMES CI](./holmes-ci.md) +- [Validation](./validation.md) +- [Release Workflow](./releases.md) diff --git a/docs/topics/directives.md b/docs/topics/directives.md new file mode 100644 index 00000000..bcbd6800 --- /dev/null +++ b/docs/topics/directives.md @@ -0,0 +1,47 @@ +# Directives + + + +Use this topic when deciding which GraphQL directives are current Wesley +surface area. + +Directive support is not "everything ever mentioned in old docs." Current +support is what the Rust-native SDL path actually parses, validates, lowers, or +preserves for current command paths. + +## Current Compatibility Path + +Existing core directive names are compatibility structure, not domain ownership. +When current command paths parse names such as the list below, Wesley lowers or +preserves structural metadata and leaves target meaning to downstream modules. + +- `@wes_table` +- `@wes_pk` +- `@wes_fk` +- `@wes_unique` +- `@wes_index` +- `@wes_tenant` +- `@wes_default` +- `@wes_rls` + +Do not present these names as proof that Wesley owns database, tenant, policy, +runtime, or renderer semantics. For new generic Wesley examples, prefer +directive examples that demonstrate preservation or law metadata without +assigning target meaning. When documenting the existing current-path directives, +use canonical `@wes_*` names and point to the directive truth table. + +## Boundary Rules + +- Product directive families belong with their owning module or repo. +- TTD, Continuum, Echo, renderer, database, and runtime directives are not + generic Wesley surface unless the current directive reference says so. +- Registry presence alone does not prove end-to-end command support. +- Dead or historical directive examples should stay in archives or migration + context, not in current quick starts. + +## Related Authority + +- [Directive Truth Table](../reference/directives.md) +- [Schema And IR](./schema-ir.md) +- [Compiler Boundary](./compiler-boundary.md) +- [Extending Wesley](../guides/extending.md) diff --git a/docs/topics/docs-maintenance.md b/docs/topics/docs-maintenance.md new file mode 100644 index 00000000..9e1505d1 --- /dev/null +++ b/docs/topics/docs-maintenance.md @@ -0,0 +1,51 @@ +# Docs Maintenance + + + +Use this topic when editing documentation or deciding whether a new signpost +belongs in the repo. + +Docs are a product interface and an evidence ledger. They are not a live +backlog, status board, or progress counter. + +## Maintenance Rules + +- Give each page one primary job: tutorial, how-to, reference, explanation, + troubleshooting, contributor guide, or evidence. +- Keep live work state in GitHub Issues, Milestones, Projects, and labels. +- Update `docs/truth-manifest.json` when adding or changing public or + governance signposts that should be checked. +- Update `docs/topics/` when a release changes contributor or operator + workflows. +- Do not leave TODOs or hidden backlog state in prose. + +## Local Checks + +```bash +cargo xtask docs-check +git diff --check +pnpm exec prettier --check +``` + +For release prep, also audit `docs/topics/` for accuracy and coverage against +the actual release diff. + +## Topic Coverage Standard + +Every public capability should have an obvious path to: + +- orientation or explanation +- command, API, schema, or invariant reference +- at least one runnable or clearly illustrative example when useful +- troubleshooting or known failure behavior when relevant +- release or closeout evidence when recently shipped + +Topic pages may summarize and route. They should not duplicate full reference +pages or live roadmap state. + +## Related Authority + +- [Documentation Standard](../governance/DOCUMENTATION_STANDARD.md) +- [Topics Index](./README.md) +- [Releases](./releases.md) +- [Validation](./validation.md) diff --git a/docs/topics/emitters.md b/docs/topics/emitters.md new file mode 100644 index 00000000..61627cc7 --- /dev/null +++ b/docs/topics/emitters.md @@ -0,0 +1,59 @@ +# Emitters + + + +Use this topic when generating Rust, TypeScript, or LE-binary codec artifacts +from GraphQL SDL. + +Emitters consume Wesley compiler facts and write generic projection artifacts. +They must not smuggle database, renderer, runtime, or product semantics into +Wesley core. + +## Common Tasks + +Emit Rust declarations and operation bindings: + +```bash +cargo run --bin wesley -- emit rust \ + --schema schema.graphql \ + --out generated/models.rs \ + --metadata-out generated/models.metadata.json +``` + +Emit TypeScript declarations and operation bindings: + +```bash +cargo run --bin wesley -- emit typescript \ + --schema schema.graphql \ + --out generated/models.ts \ + --metadata-out generated/models.metadata.json +``` + +Emit LE-binary codecs: + +```bash +cargo run --bin wesley -- emit le-binary-rust \ + --schema schema.graphql \ + --out generated/codec.rs + +cargo run --bin wesley -- emit le-binary-typescript \ + --schema schema.graphql \ + --out generated/codec.ts +``` + +## Rules Of Thumb + +- Use Rust and TypeScript emitters for generic data models and operation + bindings. +- Use metadata sidecars when outputs need deterministic provenance. +- Put Zod, Postgres, Vue, Vite, renderer, or product artifacts in an external + target module. +- Emitter changes should use structured AST/printer code, not ad hoc semantic + string splicing. + +## Related Authority + +- [CLI Reference](../reference/cli.md#emit) +- [Extending Wesley](../guides/extending.md#emitter-extensions) +- [Build Artifacts](../build-artifacts.md) +- [Compiler Boundary](./compiler-boundary.md) diff --git a/docs/topics/extension-modules.md b/docs/topics/extension-modules.md new file mode 100644 index 00000000..00617864 --- /dev/null +++ b/docs/topics/extension-modules.md @@ -0,0 +1,46 @@ +# Extension Modules + + + +Use this topic when deciding how to extend Wesley without making core +domain-aware. + +Wesley provides generic compiler facts. Extension modules and sibling repos +assign those facts target-specific meaning. + +## Decision Table + +| Goal | Home | +| --------------------------------------- | ---------------------------------------- | +| New GraphQL lowering or generic IR fact | `crates/wesley-core` | +| New user-facing command over Rust facts | `crates/wesley-cli` | +| Generic Rust projection | `crates/wesley-emit-rust` | +| Generic TypeScript projection | `crates/wesley-emit-typescript` | +| Domain target behavior | External module, crate, package, or repo | +| Descriptor-only fixture coverage | `test/fixtures/extensions/` | +| Release or repository automation | `xtask` | + +## Descriptor Fixtures + +Descriptor-only fixtures are plain data examples for boundary tests. They may +describe capability metadata, but they must not execute code or make Wesley own +a domain. + +Use descriptor fixtures when Wesley needs hermetic coverage for extension shape +without shipping the extension itself. + +## Rules Of Thumb + +- Do not rebuild the retired dynamic JavaScript module loader in core. +- Do not add Postgres, Echo, Continuum, Geordi, Edict, renderer, or runtime + meaning to Wesley core. +- Use project manifest targets as metadata; target behavior lives elsewhere. +- Add an explicit Rust-native registry, WASM boundary, or external-process + protocol before executable target loading becomes a Wesley feature. + +## Related Authority + +- [Module Authoring Guide](../guides/module-authoring.md) +- [Extending Wesley](../guides/extending.md) +- [Project Manifests](./project-manifests.md) +- [Compiler Boundary](./compiler-boundary.md) diff --git a/docs/topics/invariants.md b/docs/topics/invariants.md new file mode 100644 index 00000000..0b3d15fc --- /dev/null +++ b/docs/topics/invariants.md @@ -0,0 +1,37 @@ +# Invariants + + + +Use this topic when a change might violate a stable Wesley property. + +Invariants are durable repo truths. They are not release goals, preferences, +or live planning state. + +## Current Invariant Families + +| Family | Protects | +| --------------------- | -------------------------------------------------------- | +| Schema source truth | Authored schema remains the source of truth. | +| Git boundary truth | Tests and tools do not mutate real git state carelessly. | +| Publication boundary | Release and publication claims are witnessed. | +| Evidence truth | Evidence claims stay scoped and inspectable. | +| Governance boundaries | Process state stays in the right surface. | +| Docs runtime honesty | Docs do not claim runtime behavior falsely. | + +The exact invariant list lives in [Invariants](../invariants/README.md). + +## Rules Of Thumb + +- Add a new invariant only when the property is stable and cross-cutting. +- Use tests, docs checks, release guards, or Bats guards to preserve invariants + where practical. +- Do not hide phase-specific contracts inside invariant prose. +- If a current doc contradicts an invariant, fix the doc or the implementation + before release. + +## Related Authority + +- [Invariants](../invariants/README.md) +- [Compiler Boundary](./compiler-boundary.md) +- [Docs Maintenance](./docs-maintenance.md) +- [Validation](./validation.md) diff --git a/docs/topics/legacy-node.md b/docs/topics/legacy-node.md new file mode 100644 index 00000000..93ea8ba1 --- /dev/null +++ b/docs/topics/legacy-node.md @@ -0,0 +1,44 @@ +# Legacy Node Retirement + + + +Use this topic when an old command, package, workflow, or doc still points at +Node-era Wesley. + +The historical Node CLI and host packages are retired as Wesley product +surfaces. JavaScript remains only for retained package tooling, assurance +tooling, docs tooling, and repository maintenance. + +## Replacement Rules + +| Old Surface | Current Direction | +| ----------------------------------- | ----------------------------------------- | +| `pnpm wesley` product CLI | Native `wesley` binary from `wesley-cli`. | +| Node compiler packages | Rust crates under `crates/`. | +| Browser/Bun/Deno host packages | Retired from generic Wesley. | +| Vue, Zod, product generators | External target modules when needed. | +| Certificate/runtime ledger commands | Assurance-owned package or future design. | + +## Common Rewrites + +| Legacy Call | Current Path | +| ---------------------------------------- | ----------------------------------------------------- | +| `pnpm wesley doctor` | `wesley doctor` | +| `pnpm wesley diff ` | `wesley schema diff --old --new ` | +| `pnpm wesley typescript --schema ` | `wesley emit typescript --schema --out ` | +| `pnpm wesley generate --schema ` | Native emitters or an external target module. | + +## Rules Of Thumb + +- If a doc presents Node as Wesley's product front door, it is stale by + default. +- Reintroduce retired host behavior only through a downstream owner or explicit + target protocol. +- Do not preserve Node shapes just because they existed historically. + +## Related Authority + +- [Legacy Node Migration](../LEGACY_NODE_MIGRATION.md) +- [ENTRYPOINTS](../ENTRYPOINTS.md) +- [Native CLI](./native-cli.md) +- [Compiler Boundary](./compiler-boundary.md) diff --git a/docs/topics/native-cli.md b/docs/topics/native-cli.md new file mode 100644 index 00000000..8d964971 --- /dev/null +++ b/docs/topics/native-cli.md @@ -0,0 +1,61 @@ +# Native CLI + + + +Use this topic when you need to run Wesley or decide which command surface is +current. + +Wesley's product front door is the Rust-native `wesley` binary. The historical +Node wrapper is retired. + +## Common Tasks + +Inspect the local checkout binary: + +```bash +cargo run --bin wesley -- --help +``` + +Run a narrow Rust-native health check: + +```bash +cargo run --bin wesley -- doctor --json +``` + +Install the published CLI package after a release: + +```bash +cargo install wesley-cli --version X.Y.Z +wesley --help +``` + +Use the installed binary in scripts only when the version is pinned by the +script or release environment. Use `cargo run --bin wesley -- ...` when +validating this checkout before a PR or release. + +## Current Command Families + +| Family | Use For | +| ----------- | -------------------------------------------------------------- | +| `schema` | Lowering, hashing, operation catalogs, and schema diffs. | +| `operation` | Resolving operation selections and directive arguments. | +| `law` | `weslaw/v1` lint, validation, diff, explain, rebind, coverage. | +| `emit` | Rust, TypeScript, and LE-binary codec projections. | +| `config` | Project manifest validation, inspection, and changed schemas. | +| `doctor` | Rust-native health checks for the compiler spine. | + +The command help text and [CLI Reference](../reference/cli.md) are the command +surface authority. + +## Retired Command Surface + +Do not add new docs that present `pnpm wesley` as the product entry point. +Retained JavaScript is for assurance tooling, docs tooling, package tests, and +workspace maintenance outside compiler authority. + +## Related Authority + +- [CLI Reference](../reference/cli.md) +- [ENTRYPOINTS](../ENTRYPOINTS.md) +- [Legacy Node Migration](../LEGACY_NODE_MIGRATION.md) +- [Validation](./validation.md) diff --git a/docs/topics/operations.md b/docs/topics/operations.md new file mode 100644 index 00000000..1147bc4a --- /dev/null +++ b/docs/topics/operations.md @@ -0,0 +1,51 @@ +# Operations + + + +Use this topic when you need operation catalogs, selected field paths, or +operation directive arguments. + +Operations are generic GraphQL compiler facts in Wesley. Downstream extensions +decide what an operation means for a runtime, database, scheduler, policy, or +product. + +## Common Tasks + +List root schema operations: + +```bash +cargo run --bin wesley -- schema operations --schema schema.graphql --json +``` + +Resolve operation selection paths: + +```bash +cargo run --bin wesley -- operation selections \ + --operation query.graphql \ + --schema schema.graphql \ + --json +``` + +Extract directive arguments from operations: + +```bash +cargo run --bin wesley -- operation directive-args \ + --operation query.graphql \ + --directive wes_footprint \ + --json +``` + +## Rules Of Thumb + +- Operation facts are structure, not admission policy. +- Response paths use GraphQL response names where aliases exist. +- Schema-coordinate selections require schema SDL. +- Unsupported runtime behavior belongs in an extension, not in operation + analysis. + +## Related Authority + +- [CLI Reference](../reference/cli.md#operation) +- [Compiler Boundary](./compiler-boundary.md) +- [Extending Wesley](../guides/extending.md) +- [Wesley Core Versus Toolchain](../architecture/wesley-core-vs-toolchain.md) diff --git a/docs/topics/schema-ir.md b/docs/topics/schema-ir.md new file mode 100644 index 00000000..5bf11e0a --- /dev/null +++ b/docs/topics/schema-ir.md @@ -0,0 +1,62 @@ +# Schema And IR + + + +Use this topic when you need to inspect how Wesley sees GraphQL SDL. + +Wesley extracts GraphQL structure, normalizes it, lowers it into deterministic +IR, and exposes generic compiler facts. It does not assign product, database, +runtime, or renderer meaning to those facts. + +## Common Tasks + +Print normalized SDL from this checkout: + +```bash +cargo run --bin wesley -- normalize-sdl --schema schema.graphql +``` + +Print the normalized SDL hash: + +```bash +cargo run --bin wesley -- normalize-sdl --schema schema.graphql --hash +``` + +Lower SDL into Wesley L1 IR JSON: + +```bash +cargo run --bin wesley -- schema lower --schema schema.graphql --json +``` + +Print the L1 registry hash: + +```bash +cargo run --bin wesley -- schema hash --schema schema.graphql +``` + +Compare two SDL states: + +```bash +cargo run --bin wesley -- schema diff \ + --old old.graphql \ + --new new.graphql \ + --format summary \ + --exit-code +``` + +## Rules Of Thumb + +- Start from authored `.graphql` files when changing compiler input. +- Use normalized SDL when you need the consolidated structure the Rust compiler + actually sees. +- Use L1 IR JSON when external tooling needs deterministic compiler facts. +- Use schema hashes as evidence bytes, not as domain meaning. +- If a consumer needs Postgres, Echo, Geordi, Edict, or product behavior, that + behavior belongs in the owning extension or sibling repo. + +## Related Authority + +- [CLI Reference](../reference/cli.md#schema) +- [Compiler Boundary](./compiler-boundary.md) +- [Directive Truth Table](../reference/directives.md) +- [Architecture](../ARCHITECTURE.md) diff --git a/docs/topics/weslaw.md b/docs/topics/weslaw.md new file mode 100644 index 00000000..b9b46806 --- /dev/null +++ b/docs/topics/weslaw.md @@ -0,0 +1,70 @@ +# Weslaw + + + +Use this topic when working with `weslaw/v1` authoring files or law-derived +compiler evidence. + +`weslaw` lets authors attach structured law metadata to GraphQL structure. +Wesley validates and reports that structure; downstream owners decide how those +laws are used in a domain. + +## Common Tasks + +Scaffold law from known SDL directives: + +```bash +cargo run --bin wesley -- init-law \ + --schema schema.graphql \ + --family example.family \ + --out example.weslaw.yaml +``` + +Lint law shape without binding it to a schema: + +```bash +cargo run --bin wesley -- law lint --law example.weslaw.yaml --json +``` + +Validate law against active SDL: + +```bash +cargo run --bin wesley -- law validate \ + --schema schema.graphql \ + --law example.weslaw.yaml \ + --json +``` + +Compare law states: + +```bash +cargo run --bin wesley -- law diff \ + --old old.weslaw.yaml \ + --new new.weslaw.yaml \ + --schema schema.graphql \ + --format summary +``` + +Report release coverage: + +```bash +cargo run --bin wesley -- law coverage \ + --schema schema.graphql \ + --law example.weslaw.yaml \ + --profile release \ + --json +``` + +## Rules Of Thumb + +- Draft suggestions are not active law. +- Binding law to SDL must use current schema hashes and resolvable subjects. +- Coverage profiles are evidence and release inputs, not product policy. +- Domain-specific enforcement belongs outside Wesley core. + +## Related Authority + +- [CLI Reference](../reference/cli.md#law) +- [Weslaw Semantic Law IR](../design/0019-weslaw-semantic-law-ir/weslaw-semantic-law-ir.md) +- [HOLMES CI](./holmes-ci.md) +- [Compiler Boundary](./compiler-boundary.md) diff --git a/docs/truth-manifest.json b/docs/truth-manifest.json index 4a08dd75..1a9b8b12 100644 --- a/docs/truth-manifest.json +++ b/docs/truth-manifest.json @@ -126,16 +126,76 @@ "status": "current", "owner": "@flyingrobots" }, + { + "path": "docs/topics/artifacts-and-cache.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/assurance-evidence.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/ci-workflows.md", + "status": "current", + "owner": "@flyingrobots" + }, { "path": "docs/topics/compiler-boundary.md", "status": "current", "owner": "@flyingrobots" }, + { + "path": "docs/topics/directives.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/docs-maintenance.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/emitters.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/extension-modules.md", + "status": "current", + "owner": "@flyingrobots" + }, { "path": "docs/topics/project-manifests.md", "status": "current", "owner": "@flyingrobots" }, + { + "path": "docs/topics/invariants.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/legacy-node.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/native-cli.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/operations.md", + "status": "current", + "owner": "@flyingrobots" + }, + { + "path": "docs/topics/schema-ir.md", + "status": "current", + "owner": "@flyingrobots" + }, { "path": "docs/topics/validation.md", "status": "current", @@ -151,6 +211,11 @@ "status": "current", "owner": "@flyingrobots" }, + { + "path": "docs/topics/weslaw.md", + "status": "current", + "owner": "@flyingrobots" + }, { "path": "docs/topics/contributing/triage.md", "status": "current", diff --git a/test/release-governance.bats b/test/release-governance.bats index 76ca9777..14d378ed 100644 --- a/test/release-governance.bats +++ b/test/release-governance.bats @@ -52,3 +52,16 @@ load 'bats-plugins/bats-assert/load' run grep -F "wesley emit le-binary-rust --schema --out " docs/ENTRYPOINTS.md assert_success } + +@test "topics index uses exact docs authority paths" { + run grep -nE '`docs/[^`]*\*[^`]*`' docs/topics/README.md + assert_failure +} + +@test "directives topic frames core directives as compatibility structure" { + run grep -F 'Use canonical `@wes_*` directive names for new generic Wesley examples.' docs/topics/directives.md + assert_failure + + run grep -F "Existing core directive names are compatibility structure, not domain ownership." docs/topics/directives.md + assert_success +}