Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .config/dotnet-tools.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"rollForward": true
},
"purview.build": {
"version": "0.7.1",
"version": "0.8.1",
"commands": [
"purview-build"
],
Expand Down
56 changes: 40 additions & 16 deletions .config/org-inventory.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"schemaVersion": 1,
"org": "purview-dev",
"branch": "main",
"fetchedAt": "2026-11-03T15:46:07Z",
"fetchedAt": "2026-11-07T08:43:42Z",
"repositories": [
{
"name": "architests",
Expand Down Expand Up @@ -73,12 +73,31 @@
"architecture diagrams from source"
]
},
{
"name": "astroc4",
"visibility": "public",
"archived": false,
"commitSha": "90398b736b4fee4751e7241689b94a5014ac9d8b",
"pushedAt": "2026-11-06T13:47:01Z",
"docsDir": "docs/wiki",
"docsPages": 2,
"skills": [
"purview-astroc4-grammar",
"purview-astroc4-plugin"
],
"agentGuidance": [
"AGENTS.md"
],
"concerns": [
"architecture diagrams in an Astro site"
]
},
{
"name": "build",
"visibility": "public",
"archived": false,
"commitSha": "d00b005dd565f59f5b8641b2b80377d4e6e52c32",
"pushedAt": "2026-11-02T23:03:07Z",
"commitSha": "ee3cfcac69ccf14624eb024dcc1684bb572ab631",
"pushedAt": "2026-11-04T19:39:01Z",
"docsDir": "docs/wiki",
"docsPages": 14,
"skills": [
Expand Down Expand Up @@ -129,8 +148,8 @@
"name": "containers",
"visibility": "public",
"archived": false,
"commitSha": "b94d92afd52af1d509bc481b20c83fb9bb57badd",
"pushedAt": "2026-11-02T23:27:39Z",
"commitSha": "a0fac5502d5d543c5a1f3bb99a441cc2093bf232",
"pushedAt": "2026-11-03T18:57:30Z",
"docsDir": "docs/wiki",
"docsPages": 19,
"skills": [
Expand All @@ -152,14 +171,15 @@
"name": "engineering-playbook",
"visibility": "public",
"archived": false,
"commitSha": "ccf5b3d14616c1cbc904167439635909ed21d14c",
"pushedAt": "2026-11-03T15:40:26Z",
"commitSha": "cbe10a734f4f4ef1e29ea5d2ba710d1ef10d2702",
"pushedAt": "2026-11-04T08:43:29Z",
"docsDir": "docs/wiki",
"docsPages": 19,
"docsPages": 5,
"skills": [
"purview-architecture",
"purview-architecture-testing",
"purview-engineering-principles",
"purview-org-harvest",
"purview-persistence",
"purview-telemetry",
"purview-testing-conventions"
Expand Down Expand Up @@ -213,11 +233,12 @@
"name": "pm-skills",
"visibility": "public",
"archived": false,
"commitSha": "8460e52f4a36fd6cb59e6169e047448082b7b6ad",
"pushedAt": "2026-11-01T23:28:22Z",
"commitSha": "c32db71ba89f66260d678e5f9f843f557459b7b4",
"pushedAt": "2026-11-04T18:06:35Z",
"docsDir": null,
"docsPages": 0,
"skills": [
"pm-board",
"pm-checkpoint",
"pm-discover",
"pm-help",
Expand All @@ -226,12 +247,15 @@
"pm-next",
"pm-park",
"pm-purview",
"pm-rejoin",
"pm-resume",
"pm-review",
"pm-roadmap",
"pm-setup",
"pm-shape",
"pm-status",
"pm-strategy"
"pm-strategy",
"pm-up-next"
],
"agentGuidance": [
"AGENTS.md",
Expand All @@ -245,8 +269,8 @@
"name": "purview-dev.github.io",
"visibility": "public",
"archived": false,
"commitSha": "46fdb0e7a3155059aba132221737c1f6868542a6",
"pushedAt": "2026-11-03T15:28:00Z",
"commitSha": "0d2d72d0d6e3b69b454710622bd8bbd1bb60f46c",
"pushedAt": "2026-11-06T14:01:41Z",
"docsDir": "docs",
"docsPages": 2,
"skills": [],
Expand Down Expand Up @@ -356,10 +380,10 @@
"name": "zodsharp",
"visibility": "public",
"archived": false,
"commitSha": "d0dbc74417d4445226a58ef96464d4d3519bd3c4",
"pushedAt": "2026-11-02T23:19:42Z",
"commitSha": "667add30a57a0d0a5c0cdaeab436f7fd6af34224",
"pushedAt": "2026-11-03T22:37:59Z",
"docsDir": "docs/wiki",
"docsPages": 35,
"docsPages": 5,
"skills": [
"purview-zodsharp-aspnetcore",
"purview-zodsharp-blazor",
Expand Down
18 changes: 11 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,7 @@ implementation whose only job is to prove the conventions compile, run, and fail

| Path | Purpose |
| -- | -- |
| `docs/wiki` | The playbook itself. `Home.md` is the hub and `_Sidebar.md` is the navigation. |
| `mkdocs.yml` | Wiki site configuration (`docs_dir: docs/wiki`) |
| `docs/wiki` | The playbook itself, as plain Markdown. `Home.md` is the hub and `_Sidebar.md` is the navigation. |
| `src/EngineeringPlaybook.slnx` | Canonical solution for restore, build, lint and test |
| `src/src/Domain` | The reference implementation's value objects and aggregate |
| `src/src/Application` | The port (`IConventionRepository`) and the service that owns the rules |
Expand Down Expand Up @@ -59,17 +58,17 @@ demonstrate it.
- **One page per concern**, in `docs/wiki/<Section>/<Page-Name>.md`. The section is the topic folder,
the file name is title case with hyphens between words, and the folder name is lower-case.
- **Four sections, in order:** the rule, why, how it is enforced, at your scale. A rule a build cannot check
is labelled a review obligation — never described as enforced. `Home.md` and `index.md` are navigation,
and `Engineering-Principles.md` is an index that links to the page stating each rule in full.
is labelled a review obligation — never described as enforced. `Home.md` is navigation rather than a
rule, and `Engineering-Principles.md` is an index that links to the page stating each rule in full.
- **A new page goes in `_Sidebar.md` and in the table in `Home.md`.** A page in neither does not exist.
- **Link to the authority rather than paraphrasing it.** The SDK's own wiki is authoritative on the SDK's
behaviour; a paraphrase here is a second source of truth that will drift.
- **Name the public repository a rule came from.** Every rule came from a real repository and a real failure.
- **No reference to a private repository or product, ever.** This playbook is public, and it is aggregated by
a public site. A rule that can only be justified by something private cannot be reviewed by the people it
is published to.
- **Fences always declare a language.** Mermaid is not enabled in `mkdocs.yml`, so raw Mermaid source goes in
a ` ```text ` block.
- **Fences always declare a language.** A wiki is plain Markdown and no diagram extension is configured, so
raw Mermaid source goes in a ` ```text ` block.

## Skills

Expand All @@ -84,13 +83,14 @@ build-time `.agents/` mirror outright. The skills CLI clones the git repository,

| Skill | Answers |
| -- | -- |
| `skills/purview-engineering-principles/` | the ten universal conventions, the conditional persistence rules, and whether a build or a reviewer enforces each |
| `skills/purview-engineering-principles/` | the eleven universal conventions, the conditional persistence rules, and whether a build or a reviewer enforces each |
| `skills/purview-architecture/` | how many projects, which layers, where validation lives |
| `skills/purview-architecture-testing/` | turning a boundary into a failing build |
| `skills/purview-testing-conventions/` | TUnit, AAA, `TestBuilder`, substitutes, tiers |
| `skills/purview-persistence/` | storage approach, EF Core integration, well-known identifiers, GUID key strategy |
| `skills/purview-telemetry/` | logging, tracing, metrics, and when a project is "too small" for them |
| `skills/purview-org-harvest/` | which repository owns which convention, and how it is read at `main` before anything is adopted |
| `skills/purview-component-compatibility/` | the lowest compatible dependency version for a published component, per target framework |

Every skill carries the `purview-` prefix: skills install into one flat directory per agent, shared with
every skill a developer has installed from anywhere, so an unprefixed name collides and the loser is
Expand Down Expand Up @@ -119,6 +119,10 @@ folder is installed with it. Name the other skill in prose instead.
- **Factories on `TestBuilder` are flat, not nested.** `CA1034` is an `error` in the SDK's style policy and
`PRSGD0008` rejects adding it to `NoWarn`.
- **A test class lives in the namespace of the class under test**, and is named `{Class}Tests`.
- **A dependency version is a lookup, not a claim.** An application takes the latest version its runtime
supports; a published component declares the **lowest** version that compiles and passes, per target
framework. Never write a release number into a page or a skill — use a registry badge. See
[Dependency Versions](docs/wiki/foundations/Dependency-Versions.md).
- **A family's package version is a property.** In `Directory.Packages.props`, a version shared by a family
of packages — `TUnit`/`TUnit.Core`/`TUnit.Mocks` here — is declared once in a labelled `PropertyGroup` and
referenced as `Version="$(TUnitVersion)"`, so a bump cannot be applied to half the family. A package with
Expand Down
6 changes: 3 additions & 3 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,18 @@

<!-- Version Definitions -->
<PropertyGroup Label=".NET Versions">
<MSExtensionVersion>10.10.0</MSExtensionVersion>
<MSExtensionVersion>10.11.0</MSExtensionVersion>
</PropertyGroup>
<PropertyGroup Label="Purview Versions">
<PurviewTelemetryVersion>5.1.0</PurviewTelemetryVersion>
<PurviewTelemetryVersion>5.2.0</PurviewTelemetryVersion>
<!--
The build-sdk's test-support packages ship together and track the SDK version pinned in
global.json, so they share one property: a bump cannot be applied to half the family.
-->
<PurviewBuildSdkTestingVersion>1.2.0</PurviewBuildSdkTestingVersion>
</PropertyGroup>
<PropertyGroup Label="Testing Versions">
<TUnitVersion>1.76.0</TUnitVersion>
<TUnitVersion>1.81.10</TUnitVersion>
</PropertyGroup>

<!-- Packages -->
Expand Down
3 changes: 1 addition & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,10 @@ coding agents are enabled to work in a codebase without hand-holding.

| Path | Purpose |
| -- | -- |
| `docs/wiki` | The playbook. Aggregated by the purview-dev website. |
| `docs/wiki` | The playbook, as plain Markdown. Aggregated by the purview-dev website. |
| `templates/` | Ready-to-copy starter files for a repository adopting the playbook. |
| `src/` | The reference implementation: a layered repository whose architecture rules are tests. |
| `samples/` | Runnable samples for conventions that `src/` cannot host; run with `just samples`. |
| `mkdocs.yml` | Wiki site configuration (`docs_dir: docs/wiki`). |
| `.config/purview-build.json` | Pipeline configuration for the shared Purview build workflow. |
| `Justfile` | Supported local workflow commands. |
| `package.json` | Authoritative version for the repository. |
Expand Down
7 changes: 4 additions & 3 deletions docs/wiki/Engineering-Principles.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Engineering Principles

These are the ten universal rules the Purview repositories are held to, plus the conditional persistence
These are the eleven universal rules the Purview repositories are held to, plus the conditional persistence
rules below them. This page is an index: each rule is stated once, in full, on the page named beside it.
That page carries the failure the rule prevents, the mechanism that makes it true, and what a smaller
repository does instead — so a rule is never written twice and the two copies cannot disagree. Where a
Expand All @@ -19,10 +19,11 @@ A rule that claims enforcement it does not have is worse than no rule, because p
| 4 | The build is the only authority | A convention a build can check is checked by the build; the rest is labelled a review obligation, never described as enforced. | [Documentation Convention](foundations/Documentation-Convention.md) |
| 5 | Warnings are not acceptable output | A clean build has no warnings: fix one, suppress it where it occurs with a justification, or turn the rule off deliberately. | [Testing and Test Data](testing/Testing-And-Test-Data.md) |
| 6 | Every claim about a consumer is proved by a consumer | A package that documents how it must be used ships something that builds that documented consumer and asserts the documented outcome. | [Contracts and Data Exchange](data/Contracts-And-Data-Exchange.md) |
| 7 | Documentation is a build artefact of the repository | The wiki lives in the repository it describes, and the repository owns its `mkdocs.yml`, navigation and `edit_uri`. | [Documentation Convention](foundations/Documentation-Convention.md) |
| 7 | Documentation is a build artefact of the repository | The wiki is plain Markdown in the repository it describes, with its navigation in `_Sidebar.md` and no site configuration beside it. | [Documentation Convention](foundations/Documentation-Convention.md) |
| 8 | Everything a test needs is built by one builder | Domain content in a test comes from `TestBuilder`; a test overrides only the value it is proving. | [Testing and Test Data](testing/Testing-And-Test-Data.md) |
| 9 | An agent is a reader with no memory | A repository states its purpose, layout and conventions in `AGENTS.md`; nothing important is discoverable only from the code. | [Agent Enablement](agents/Agent-Enablement.md) |
| 10 | A change is verified in proportion to its risk | Checks are tiered; a pull request runs the fast tier, and the slow tier is run deliberately. | [Verification Model](foundations/Verification-Model.md) |
| 11 | A version is a range, not a number | An application takes the latest compatible release; a published component declares the lowest compatible version per target framework, and a page shows a badge rather than a number. | [Dependency Versions](foundations/Dependency-Versions.md) |

### Conditional persistence rules

Expand All @@ -36,7 +37,7 @@ silent there. Each is stated in full on its own page.
| P2 | A GUID key strategy is chosen once per store | One provider-specific strategy, carried as context-options data and applied to every key by convention. | [GUID Key Strategy](data/Guid-Key-Strategy.md) |
| P3 | EF Core is the persistence boundary | `DbContext` used directly, value objects mapped once, design-time and runtime options in step, migrations applied deliberately. | [EF Core Integration](data/EF-Core-Integration.md) |

Enforcement is stated per rule on the linked page. Three of the ten are enforced by the build in a way
Enforcement is stated per rule on the linked page. Three of the eleven are enforced by the build in a way
worth knowing at a glance: identity (rule 2) by `PurviewProjectFileNameMismatch` and the SDK's
derivation, architecture (rule 3) by the architecture tests, and the verification tiers (rule 10) by the
pipeline's `TestFilter`. The rest are enforced partly by the build and partly by review, and each page
Expand Down
Loading
Loading