OH MY PM v0.5.3

OH MY PM v0.5.3

Documentation and architecture truth release. It changes no product code and
adds no user-facing capability.

Documentation authority was real but implicit. Two arrays inside
tools/validate-doc-truth.mjs decided which documents were checked for
present-tense claims and which were exempt as point-in-time records. That worked,
but the classification was knowable only by reading validator source: nothing
could enumerate it, a newly added document silently defaulted to
unclassified-and-unchecked, and a document that had been replaced could still be
linked from an active index as though it were current guidance.

This release makes that classification explicit, machine-readable, exhaustive,
and enforced.

Everything you can observe as a user is unchanged from v0.5.2. No migration is
required.

Release lineage

Latest published stable, and immutable base	v0.5.2
v0.5.0	superseded, unpublished source candidate — there is no v0.5.0 tag or release
v0.5.3	prepared; not yet published

No existing release tag is moved, replaced, recreated, or deleted. Merging the
v0.5.3 pull request publishes nothing.

Problem statement

Before this release the repository could not answer, mechanically, the question
"is this document current truth?" Three specific failures followed from that:

1. Unclassified documents were unchecked. A document not listed in the
   validator's ACTIVE_DOCS array was exempt from every current-state guard, so
   it could claim a stale version, a wrong tool count, or an unimplemented
   capability indefinitely without failing the build.
2. Nothing verified the package map was complete. docs/architecture.md is
   the authoritative map of workspace packages, and it silently omitted a real
   one (@oh-my-pm/examples), so a reader would conclude that package was not
   part of the system.
3. Superseded documents could be linked as normative. Marking a document
   replaced only matters if current documents stop pointing at it.

Documentation truth model

docs/manifest.json is the authoritative classification contract. Every tracked
Markdown document that describes the product is listed exactly once, with four
fields:

Field	Meaning
status	active, historical, superseded, or release-record
authority	normative (citable as current truth) or informative
appliesTo	the version or release line the document speaks for; current for active
replacement	the path that supersedes it, or null

A fifth field, concern, names what a document is authoritative about. It is
what makes duplicate authority detectable: two active, normative documents
claiming the same concern give a reader two candidate truths and no rule for
choosing between them.

Test fixtures under examples/fixtures/**, issue templates, and the PR template
are explicitly excluded — they are input data and scaffolding, not documentation
about the product.

tools/docs-manifest.mjs is the single loader over the contract, so
validate-doc-truth and docs-inventory agree by construction rather than by
restating the same lists.

Architecture corrections

Two active-documentation claims were factually wrong and are corrected:

• README.md described the repository as "the new v2 line." It is not. The
  repository ships a v0.x line — v0.1.0 through v0.5.2 — and there is no
  v2.x target. The rebuild that produced this architecture is history, not a
  pending migration. The section now states the real release line and links
  version.json and the roadmap.
• docs/architecture.md omitted @oh-my-pm/examples. It is now documented
  with its real role: a development-only composition harness that wires the real
  packages together so each documented composition is exercised by a test. It is
  the one workspace package outside the release dependency surface — the bundler
  deploys none of its code, though its fixtures/markdown-project/ tree is
  copied in as the sample project the installed qualification analyzes.

Both corrections were found by the new guards, not by inspection.

Validator improvements

pnpm validate:docs derives its active and historical sets from the manifest
instead of restating them, and gains four guards:

Guard	Fails when
Nonexistent package	an active document names an @oh-my-pm/* package that is not a workspace package
Incomplete package map	docs/architecture.md omits a real workspace package
Superseded document linked	an active, normative document Markdown-links a document classified superseded
Duplicate authority	two active, normative documents declare the same concern

Plus full classification coverage: every tracked Markdown document must be
classified or explicitly excluded, so a new document cannot default to unchecked.

Both package expectations derive from pnpm-workspace.yaml, so adding or
removing a package moves them automatically and neither can go stale.

The manifest itself is structurally validated: unknown status/authority
values, a superseded entry without a replacement, a replacement that does
not resolve, a classified file that no longer exists, a path classified twice,
and an active entry that declares a replacement are all defects.

Documentation inventory tooling

pnpm docs:inventory          # human-readable report
pnpm docs:inventory --json   # machine-readable
pnpm docs:inventory:check    # exit non-zero on any defect (wired into pnpm validate)

It reports active normative, active informative, historical, superseded, release
records, broken replacements, classified-but-missing files, and unclassified
documents. Deterministic (entries sorted, so output is stable and diffable),
offline, and read-only.

Historical preservation policy

Historical claims that were true at publication time are not rewritten to
satisfy present-tense validators. The correct fix for a stale-looking historical
statement is classification, not editing.

CHANGELOG.md is the concrete case. Its v0.2.0 entry states that "the four
shims remain validated byte-for-byte," which was accurate before v0.5 introduced
the canonical ohmypm family and made the installed count eight. Classifying the
changelog as a release-record rather than an active document is what keeps that
entry intact; treating it as active would have made the shim-count guard demand
its rewrite, destroying exactly the release evidence it exists to preserve.

No file under docs/releases/**, docs/v0.3/**, docs/v0.4/**, or
docs/architecture/** is modified by this release.

User-visible behavior statement

None. No command, flag, output format, exit code, MCP tool, MCP schema, tool
order, annotation, Project Brain schema, Project Memory store format, or
installed layout changes. The twelve read-only MCP tools, zero write tools, seven
memory subcommands, Project Brain schema 1, and store format 2 are all
unchanged.

Migration statement

No migration. Installing v0.5.3 over v0.5.2 requires no action, and a v0.5.2
Project Memory store is read and written identically.

Compatibility statement

• Canonical commands ohmypm, ohmypm-mcp, ohmypm-install — unchanged.
• Deprecated aliases oh-my-pm, oh-my-pm-mcp, oh-my-pm-install — retained,
  still warn on stderr only, no removal scheduled.
• MCP tool inventory and order — unchanged.
• Generated TypeScript and Rust contracts — unchanged.
• Release archive names, bundle profile, and installed layout — unchanged.

Validation evidence

pnpm build                          OK
pnpm quality                        OK (lint, format, rustfmt, clippy)
pnpm test                           OK (unit, release, rust)
pnpm validate                       OK (public, structure, boundaries, contracts,
                                        version, commands, references, docs,
                                        docs inventory)
pnpm mcp:smoke                      OK
pnpm release:preview -- --apply     OK
pnpm release:check                  OK
pnpm release:archives:preview       OK
pnpm release:archives:check         OK
pnpm release:archives:repro         OK
pnpm release:install:check          OK

The seventeen mutation tests in tools/docs-manifest.test.mjs each introduce one
contradiction into a disposable git fixture and assert the validator rejects it
with that guard's specific message, then assert the unmutated fixture passes. A
guard never observed failing is not evidence that it matches anything.

Known limitations

• concern is declared, not inferred. Duplicate authority is detected only
  when two documents claim the same concern string; two documents that overlap
  in substance while declaring different concerns are not detected. Naming the
  concern is a maintainer judgement.
• The superseded-link guard covers Markdown inline links only. A bare path in
  prose is intentionally not treated as a live link, so a document that mentions
  a superseded path without linking it is not flagged.
• The package-map guard checks presence, not accuracy. It proves every real
  package is named in docs/architecture.md; it does not verify the prose about
  each package is correct.
• The provider contract enum remains wider than the supported set.
  PROVIDER_ID_VALUES lists seven providers while only local and github are
  registered and allowed. This is the intentional forward-looking superset
  recorded as F-DUP-2 in the v0.2 stabilization audit, gated by the runtime
  allow-list. It is documentation-visible only in a historical document and is
  not changed here.

What remains for v0.5.4

v0.5.3 establishes documentation truth. v0.5.4 addresses repository and contract
consistency:

• an authoritative package catalog with role, ownership, and dependency rules per
  workspace;
• a verified, cycle-free package dependency model;
• a shared ApplicationResult<T> envelope at the application boundary;
• normalized source descriptors and provenance contracts;
• a unified Diagnostic model and a repository-wide error taxonomy, consolidating
  today's per-use-case structures in application/src/errors.ts and
  application/src/provider-diagnostics.ts;
• CLI exit-code and MCP error mapping made explicit and tested;
• semantic parity tests proving CLI and MCP consume the same application result.

Neither release implements the omp command migration, a Dashboard, new
providers, cloud sync, telemetry, accounts, GitHub mutation, or an HTTP MCP
transport.