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

FileOwnsDoes not own
pnpm-workspace.yamlWorkspace package globs, catalogues, pnpm resolution/build/supply-chain settings and deliberate exceptions.Reusable credentials, provider access policy or package-local implementation.
Root package.jsonRepository identity, packageManager, compatible engines, root scripts and root development dependencies.pnpm settings that affect the workspace installation as a whole.
Package package.jsonPackage identity, scripts, runtime/build dependencies and package-local engine constraints.Workspace-wide catalogues or repository-wide lifecycle policy.
.npmrcRegistry routing and authentication configuration.General pnpm settings, secrets committed to source, or workspace package selection.
Provider configurationBuild/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:

  1. the public-standard reference and a short repository exception comment, if
  2. one exists;

  3. packages workspace globs and exclusions;
  4. catalog and named catalogs;
  5. resolution, catalogue and workspace behaviour;
  6. build-script and dependency trust policy;
  7. shell/script compatibility settings; and
  8. 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.

Catalogue taxonomy

Catalogues coordinate dependency versions, not dependency roles. The
owning package manifest already distinguishes dependencies,
devDependencies, peerDependencies and optionalDependencies; repeating
those roles as catalogue names creates a second classification that pnpm does
not interpret semantically.

Use the default catalog for the ordinary coordinated dependency line:

catalog:
  react: 19.2.7
  typescript: 6.0.3
  vitest: 4.1.10

A package keeps its role locally while consuming the same version authority:

{
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vitest": "catalog:"
  }
}

Named catalogs are reserved for deliberate alternate compatibility,
toolchain or version lanes such as typescript7, react18 or a bounded
application compatibility set. Names such as dev, prod, development,
production, runtime or test must not be used merely to mirror the
manifest section that consumes the dependency.

A named lane should be self-explanatory. When it represents a deliberate hold,
compatibility divergence or temporary split, document the applicable deviation
class, evidence and retirement/review condition under the exception model below.

A repository with one package or no useful coordinated version set does not
need to invent a catalogue for conformity. Catalogue policy applies when the
repository actually uses catalogues.

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 its engines.pnpm range must admit the governed
pnpm 12 line without crossing into pnpm 13.

A representative multi-package workspace is:

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

catalog:
  # Ordinary coordinated dependency versions live here.

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

update:
  githubActions: true

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

minimumReleaseAge: 1440
minimumReleaseAgeStrict: true
minimumReleaseAgeIgnoreMissingTime: false
minimumReleaseAgeExclude:
  - '@meridian-stack/*'

trustPolicy: no-downgrade
trustPolicyIgnoreAfter: 10080
trustLockfile: false

Meridian retains apps/*/* as an explicit workspace-structure exception: the
repository structure contract requires second-level app roots, and the pattern
preserves membership for current and future app categories. Category patterns
such as apps/websites/* and apps/workers/* are omitted because they are
subsumed by this pattern. Current discovered application roots match the broad
pattern without selecting unrelated managed package roots.

The important rules are:

Some security-safe pnpm defaults are intentionally not cargo-culted into every
workspace. strictDepBuilds and blockExoticSubdeps currently default to
true; do not explicitly weaken either without a documented exception.
Likewise autoInstallPeers, strictPeerDependencies, recursiveInstall,
engineStrict, hoisting and linker settings are repository-specific unless a
separate standard adopts them.

Do not adopt a setting merely because a newer pnpm exposes it. For example,
autoDedupe arrived after the currently governed pnpm 12.4 baseline; it should
be evaluated only when the fleet deliberately advances to a supporting version.

The baseline records policy intent. It does not require every repository to
copy an irrelevant setting, create a catalogue it does not need, or introduce a
multi-project orchestrator into a genuinely single-project repository.

A retained legacy pnpm workspace uses the setting names supported by that
governed line rather than pretending newer spellings exist. For example, an
evidence-backed pnpm 11.21 compatibility workspace retains
cleanupUnusedCatalogs and enableGlobalVirtualStore; it migrates to
catalogPrune and virtualStoreType only when the documented pnpm 12 exit
condition is satisfied. The compatibility metadata and bounded engine range are
what make that legacy lane deliberate rather than silent drift.

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:

ClassRequired rationaleRequired evidenceExit-condition semantics
permanentWhy 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.
compatibilityWhich 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.
temporaryWhy 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.

Dependency-verification exception

verifyDepsBeforeRun: error is the ordinary baseline because pnpm otherwise
defaults to automatically installing when node_modules is stale. Repository
commands should fail with an actionable dependency error rather than mutating
the install as a side effect of running a script.

A custom authenticated hosted-build bootstrap is the main reviewed exception.
It may need verifyDepsBeforeRun: false so a dependency-free root bootstrap can
obtain bounded package authentication and perform the frozen deployable-scoped
install before pnpm attempts any verification. Record that departure beside the
setting as a permanent or compatibility deviation with the rationale/evidence
required below. The hosted-build standard owns the additional provider switch
and credential boundary.

Interactive warn, prompt or implicit install modes are not the
organisation baseline. If a repository genuinely needs one, treat it as a
documented deviation rather than another default.

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:

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.

IDSeverityCheck
PNPM-WORKSPACE-001failRoot packageManager and engines.pnpm identify the approved bounded pnpm 12 line.
PNPM-WORKSPACE-002failWorkspace, resolution and lifecycle settings are in pnpm-workspace.yaml; registry/auth settings remain in .npmrc.
PNPM-WORKSPACE-003reviewGlobal virtual-store policy is explicit, or the project-local exception carries compatibility evidence and an exit condition.
PNPM-WORKSPACE-004failBuild scripts use explicit allowBuilds approvals without removed legacy lists or blanket allow-all.
PNPM-WORKSPACE-005reviewRelease-age and trust policy match the supply-chain baseline or a narrow documented exception.
PNPM-WORKSPACE-006failDeliberate deviations identify permanent, compatibility or temporary class plus the required rationale/evidence/exit semantics.
PNPM-WORKSPACE-007failCatalogue mode/pruning and named-catalogue taxonomy match the standard; dependency-role buckets such as dev / prod are rejected.
PNPM-WORKSPACE-008failThe governed pnpm line uses canonical setting names rather than deprecated compatibility spellings.
PNPM-WORKSPACE-009failDependency verification uses error normally, or another mode carries a supported documented exception.

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 was established by ISSUE #1775 and clarified for the organisation-wide rollout by ISSUE #2357.

Standards authority and sources

The machine-readable policy is published at
/standards/pnpm-workspace.policy.json.
Its sourceRevision is generated from the same source revision as
/standards/index.json.
Consumers should resolve the pnpm-workspace entry in that index, fetch its
authorityUrl, and require matching sourceRevision values. The sidecar is
the versioned machine authority; this document remains the explanatory source.

The selected pnpm settings and their current spellings are checked against the
pnpm 12.x workspace settings reference, including
dependency resolution and supply-chain settings,
virtual-store settings,
build settings, and
catalogue and shell settings. The
installation reference identifies pnpm 12 as
the current release line. Meridian's 12.4 requirement is the fleet's
governed patch pin, not a claim that 12.4 is the latest pnpm release.

Nx and provider boundary

Nx is the steady-state generic project and task graph for applicable
multi-project repositories. Use affected selection as the fast validation
lane, then run the repository's full required acceptance. Cache deterministic
build, typecheck, test and quality tasks when their inputs and outputs are
complete. Never treat a cache hit as success authority for deploy, publish,
migration or live-provider mutation. Turbo files are migration evidence only:
reproduce required dependencies, inputs and outputs in Nx, validate parity,
then remove Turbo in the same bounded migration. Providers invoke stable
repository-owned root commands; Meridian remains authoritative for deployable
closure, provider configuration and watch paths.

Download raw Markdown · Standards index