Public Meridian standard · current

Meridian pnpm Workspace Standard

This standard owns Meridian's repository-level pnpm-workspace.yaml policy.
It explains the intent behind workspace settings, the boundary between package
manager configuration and other repository files, and the evidence required
when a repository deviates from the baseline.

The canonical public reference for this standard is:

https://agents.meridianstack.dev/standards/pnpm-workspace

The current pnpm 12 reference documents pnpm-workspace.yaml as the home for
workspace and non-auth configuration, while .npmrc owns authentication and
registry settings. See pnpm Settings and the
pnpm workspace documentation.

File ownership

File	Owns	Does not own
`pnpm-workspace.yaml`	Workspace package globs, catalogues, pnpm resolution/build/supply-chain settings and deliberate exceptions.	Reusable credentials, provider access policy or package-local implementation.
Root `package.json`	Repository identity, `packageManager`, compatible engines, root scripts and root development dependencies.	pnpm settings that affect the workspace installation as a whole.
Package `package.json`	Package identity, scripts, runtime/build dependencies and package-local engine constraints.	Workspace-wide catalogues or repository-wide lifecycle policy.
`.npmrc`	Registry routing and authentication configuration.	General pnpm settings, secrets committed to source, or workspace package selection.
Provider configuration	Build/deploy commands, watch paths, provider bindings and hosted access intent.	pnpm workspace policy or package-manager credentials.

Provider-specific build and deployment additions belong in
[pnpm-hosted-builds.md](pnpm-hosted-builds.md), which links back here for the
general workspace rules instead of redefining them.

Canonical header and section order

When a repository publishes or consumes this standard, the top of its
pnpm-workspace.yaml should contain this exact reference comment before the
first setting:

# Public standard: https://agents.meridianstack.dev/standards/pnpm-workspace

Keep the file in this order unless a pnpm feature requires otherwise:

the public-standard reference and a short repository exception comment, if

one exists;

packages workspace globs and exclusions;
catalog and named catalogs;
resolution, catalogue and workspace behaviour;
build-script and dependency trust policy;
shell/script compatibility settings; and
versioning or other less-common settings.

The order is for reviewability, not pnpm semantics. Do not add settings merely
to mirror this list: an omitted default is preferable to cargo-culted YAML.

Meridian baseline

The baseline applies to a repository using pnpm 12.4 or a later approved pnpm
12 patch. The exact version remains owned by the root package.json
packageManager field and must be compatible with its engines.pnpm range.

The normal workspace policy is:

packages:
  - apps/*
  - packages/*
  - tools/*

catalogMode: prefer
catalogPrune: true
virtualStoreType: global
verifyDepsBeforeRun: false
shellEmulator: true

allowBuilds:
  # Only reviewed packages that need lifecycle/build scripts appear here.
  # The repository's actual allowlist is authoritative.

minimumReleaseAge: 1440
minimumReleaseAgeStrict: true

The important rules are:

workspace globs include only real package roots and intentionally documented

fixture roots; exclusions must explain why a matching directory is not a
workspace package;

catalogMode: prefer and catalogPrune: true keep compatible third-party

versions convergent without forcing incompatible packages into one range;

virtualStoreType: global is the current canonical spelling of

enableGlobalVirtualStore: true on pnpm 11.23 and later. It improves warm
multi-project installs, while pnpm automatically disables it in CI;

verifyDepsBeforeRun: false is appropriate when a repository-owned bootstrap

deliberately controls frozen dependency preparation before a root script;

shellEmulator: true is for simple portable package-script syntax only. It

does not turn package.json into a general shell-program container;

allowBuilds is an explicit package map. Do not use the removed legacy

build-script lists or dangerouslyAllowAllBuilds as a convenience;

keep pnpm's one-day minimumReleaseAge supply-chain delay unless there is a

reviewed reason to change it. Narrow first-party exclusions are preferable
to a global opt-out; and

the committed lockfile remains authoritative. Hosted installs use frozen

dependency preparation and must not silently resolve a new graph.

The baseline records policy intent. It does not require every repository to
copy every setting when pnpm's default already supplies the same behaviour.

Global virtual store compatibility exception

The global virtual store is the normal policy, not a universal mandate. A
repository may use the project-local virtual store when an OpenNext/Next build
or another tool follows pnpm's private project-local layout.

Meridian has concrete evidence for this exception: Site Intel PR #174
recorded a Windows OpenNext build failure with the global virtual store, and
Meridian issue #1304
tracks the resolver fix that allows the compatibility bridge to be removed.

The current Meridian source therefore makes the exception explicit:

# Class: compatibility. OpenNext/Next Windows builds still require the
# project-local virtual tree until deployment resolution closes ISSUE #1304.
# Evidence: Site Intel PR #174. Exit condition: released resolver plus a
# Windows proving build that passes with the global virtual store.
virtualStoreType: project

Do not turn this exception into a new default for unrelated repositories. Once
the deployment resolver and proving build satisfy the exit condition, remove
the exception and return to virtualStoreType: global.

Deviation classes

Every intentional deviation from the baseline uses one of these classes in a
nearby comment or repository-owned exception record:

Class	Required rationale	Required evidence	Exit-condition semantics
`permanent`	Why the baseline is not suitable for this repository or package family.	A stable design decision, supported tool contract or repeatable measurement.	State `none` only when the deviation is part of the intended long-term design; otherwise define the condition that retires it.
`compatibility`	Which upstream/tool/runtime incompatibility requires the deviation.	Reproduction, upstream issue/PR, and a proving test or build.	Name the upstream fix/release and the proving check required before removal.
`temporary`	Why the repository needs a short-lived departure now.	Current failure or rollout evidence and an owning GitHub Issue/PR.	Set an owner and review date or a concrete migration condition; temporary exceptions must not become invisible defaults.

An exception comment should identify the class, rationale, evidence and exit
condition without restating the literal YAML value. Ordinary current catalogue
or dependency versions need no prose. A deliberate hold, compatibility pin or
non-standard divergence does require that short rationale and its removal or
review condition.

Hosted-build boundary

When a provider build needs a repository-controlled install/authentication
boundary, the hosted-build standard may require verifyDepsBeforeRun: false
and a provider-level dependency-install switch. That is a hosted execution
decision, not a reason to duplicate the full pnpm baseline here or to put
credentials in workspace YAML.

The hosted standard owns the following additions:

root build/deploy command roles and built-artifact reuse;
provider dependency-install switches and bounded package authentication;
deployable closure and watch-path evidence;
provider preview/non-production state; and
separation of repository validation from live provider acceptance.

See [pnpm-hosted-builds.md](pnpm-hosted-builds.md) for those rules.

Audit contract

Workspace audits should report these stable rule identifiers. fail means the
repository is outside the standard; review means an explicit exception may
be valid but must carry the evidence and exit-condition metadata defined above.

ID	Severity	Check
`PNPM-WORKSPACE-001`	fail	Root `packageManager` and `engines.pnpm` identify an approved compatible pnpm 12 line.
`PNPM-WORKSPACE-002`	fail	Workspace, resolution and lifecycle settings are in `pnpm-workspace.yaml`; registry/auth settings remain in `.npmrc`.
`PNPM-WORKSPACE-003`	review	Global virtual-store policy is explicit, or the project-local exception carries compatibility evidence and an exit condition.
`PNPM-WORKSPACE-004`	fail	Build scripts use explicit `allowBuilds` approvals without removed legacy lists or blanket allow-all.
`PNPM-WORKSPACE-005`	review	Release-age and trust policy do not weaken pnpm's supply-chain baseline without a narrow, documented reason.
`PNPM-WORKSPACE-006`	fail	Deliberate deviations identify `permanent`, `compatibility` or `temporary` class plus rationale, evidence and exit-condition semantics.

Validation

Review a change to pnpm-workspace.yaml against this standard and the current
pnpm 12 documentation. Verify the examples against the repository's current
package manager version and one representative workspace install/build path.
For a compatibility exception, run the named proving check before removing or
changing the exception. Do not claim that a hosted build or provider state is
validated from a local pnpm command alone.

This standard is the implementation record for ISSUE #1775.

Download raw Markdown · Standards index