OH MY PM v0.6.2

OH MY PM v0.6.2

Project Memory integrity: verification, gap closure, and a supported recovery
path.

One new command (omp memory repair). Everything else behaves exactly as it did
in v0.6.1: no changed flag, output schema, exit code, MCP tool, Project Brain
schema, or Project Memory store format, and no migration is required.

Why this release exists

The original v0.6.2 scope was written as if atomic writes, integrity metadata,
migrations, locking, path confinement, and privacy enforcement all needed
building. They did not — most of them shipped earlier and were genuinely
implemented, not stubbed. Building a second atomic-write layer beside a correct
one would have made the system worse.

So the release was re-scoped to verification and gap closure, and an audit was
performed first, before any implementation:
docs/releases/v0.6.2-integrity-audit.md. That
audit is the authority for what this release contains. It found five real gaps out
of eighteen scope items; the other thirteen were already correct, already proven,
or deliberately out of scope.

The audit's original matrix is preserved unedited, with the closure appended
separately. It records what was believed before the work — which is what makes
it an audit rather than a summary.

The five gaps, and what closed them

G1 — Fault injection could not reach inside the atomic write

writeFileAtomic was one opaque step, so four of the nine crash stages a release
must prove were untestable: before temp write, during temp write, after flush,
before parent sync.

The write was probably correct; nothing proved it. The ordering now lives in
atomic-write.ts, parameterized over its primitives. Production passes real Node
primitives and no hook; tests pass deterministic primitives and a hook that throws
at a named stage. Both run the same ordering logic, so a test cannot pass
against an imitation whose steps happen to differ from production.

Closing this also surfaced a real defect: a failure between temp creation and
rename leaked the temp file, because cleanup was scoped only to the rename step.

G2 — Post-crash recovery was untested, and one test misreported itself

The crash test constructed a fresh in-memory filesystem for its follow-up
commit — a pristine store with no lock file, no staging residue, no partial state
— while its comment claimed it proved the lock was released and a follow-up commit
worked. It proved neither.

This was the most misleading finding in the audit, because the test read as if
crash recovery were covered. The follow-up commit now runs against the same
damaged store, and asserts the lock is gone, the residue is detectable, and the
next commit succeeds.

That fix exposed a second real defect: a crash after the manifest rename left
staging residue that survived every subsequent identical commit, because the
idempotent early-return skipped cleanup entirely. inspect() reported
abandonedStaging forever.

G3 — Locking was never exercised across real processes

The stale-lock rule (age and dead owner) was correct and is unchanged. But a
single-writer lock's real contract is open(path, "wx") on a real filesystem
between real processes, and every existing test was in-process against an
in-memory port.

Now proven with real spawned subprocesses against the real Node adapter: two
processes cannot both write, a live slow writer is never evicted, a dead stale
owner is reclaimed, acquisition is bounded, and crash residue recovers.

G4 — Path confinement was lexical, and writes were less protected than reads

Containment never consulted the filesystem, so a symlink or junction inside the
data root pointing outside satisfied every check. Reads mitigated this by refusing
to follow a symlink at the leaf; the write path performed no such check.

physical-confinement.ts resolves the physical path before a write, walking the
target one segment at a time and re-checking containment after every step.
Resolving one hop at a time is load-bearing: realpath collapses an entire chain,
so a route that leaves the root and returns — <root>/hop -> <outside>/back -> <root>/real — resolves to a path inside the root and would be accepted, even
though the write physically travels through a directory the store does not govern.

G5 — Corruption could be detected but never isolated or repaired

Detection was strong and deliberately non-destructive. But a user with a corrupt
record had no supported path forward: no quarantine, no preview, no repair.

omp memory repair closes that. See below.

Added: omp memory repair

The invariant the whole design serves:

normal read detects and reports
repair preview scans and proposes
explicit --apply performs bounded mutation

omp memory repair            # scan and propose; changes no byte
omp memory repair --apply    # bounded recovery under the writer lock

Preview and apply are separate store calls, not one call with a flag, so the
read-only path physically cannot reach the writer.

Apply requires explicit intent, takes the same single-writer lock a capture takes,
re-scans under that lock, and refuses a plan whose store fingerprint moved —
before the first write, so a stale plan produces no partial mutation. The
fingerprint is content-derived, never a modification time: mtime granularity is
coarse and platform-dependent, can be moved backwards, and does not change at all
for a same-size in-place edit.

Quarantine is not repair

This distinction is the most important thing in the release. Quarantining a
corrupt record preserves its exact original bytes and makes the rest of the
store readable again. It does not recover that record's meaning. Every output
path reports isolated separately from reconstructed, and there is deliberately
no single "repaired" total — a user whose data is damaged is the last person who
should be told it came back.

The write ordering is the safety argument: read the exact bytes, persist the
payload, persist sanitized metadata, confirm the payload re-reads with a
matching digest, and only then remove the corrupt live path. No reachable
failure stage leaves the original gone with no readable copy.

What a repair may do, by authority

Class	Examples	Action
Authoritative	records, manifest	isolated into quarantine; never rewritten from a guess, never deleted
Derived	manifest inventory, chronology	rebuilt, but only from records that fully verify
Coordination	lock files	reclaimed only on age threshold and a dead owner
Residue	temp files, abandoned staging	removed only when this store's ownership is proven
Recovery evidence	quarantine	never live, never auto-pruned, never rebuilt

Derived state is rebuilt only from verified records. A rebuild that trusted
the existing inventory would re-reference records the same apply just isolated; one
that trusted whatever is on disk would launder corruption into apparently-valid
authoritative state.

An unsupported future store format is reported and never downgraded. A repair
never writes to your project's source files, makes no network request, and is
not exposed as an MCP tool.

Defects found and corrected during the work

Recorded because a release that only lists what it fixed in others is not honest
about itself.

• A path-spelling mismatch broke convergence. The missing_referenced_record
  finding emitted a shorter relative path than every other target, so the manifest
  rebuild's comparison never matched and an isolated record was never dropped from
  the inventory — the store did not heal. Fixed by making one function the single
  authority for that spelling, so the two cannot drift.
• A duplication guard was dead code. An "already isolated, skip" branch could
  never run, because isolating a record changes the fingerprint and the stale-plan
  guard always intercepts a retry first. Removed rather than left as an untestable
  guard.
• An intermittently-failing baseline. An unhandled-rejection race made the
  integrity suite fail 2 of 8 runs, and an unformatted file failed pnpm quality.
  Both were introduced by earlier commits in this same release.

Corrected evidence incidents

Three, kept permanently visible in the audit closure, because the lesson is the
deliverable.

1. Invalid mutation evidence. A Vitest filter containing | was assumed to be
   a regex. Vitest treats it as a literal substring, so it matched zero files and
   exited 1. The nonzero exit was read as the mutation being caught; nothing had
   run.
2. Vacuous assertion. An assertion filtered on issue.severity, a property
   that does not exist on the type. The filter matched nothing, so it passed no
   matter how damaged the store was.
3. Near-miss during the closure. A test claiming to derive the memory
   subcommand count asserted a hardcoded 7. It now derives on both sides — and
   the first attempt to prove that fix by mutation silently failed to apply, which
   is incident 1 all over again. The harness now fails loudly when a mutation does
   not change the file.

The rule this enforces:

a failing command is not mutation evidence
unless the unmutated baseline passes,
the intended tests are discovered,
the mutation changes the intended behaviour,
and targeted assertions fail

A corollary learned here: a flaky baseline is as disqualifying as a failing
one. Evidence gathered against a baseline that fails a quarter of the time is
worthless.

All ten required G5 mutations are killed, each with a verified-green baseline
before and after and targeted named failures.

Performance evidence

Bounded structural baselines, not SLOs — the full performance architecture
remains v0.6.5.

Timing gates on shared CI are coin flips: they fail on a noisy neighbour and pass
on a genuine 10x regression ...

OH MY PM v0.6.1

OH MY PM v0.6.1

Application boundary completion.

An internal architecture release. Every command, flag, output format, exit code,
and MCP schema is unchanged — if you upgrade and change nothing, nothing behaves
differently. What changed is where the shared work lives.

Why this release exists

v0.5.4 introduced ApplicationResult<T>: a shared envelope describing where a
result came from, what diagnostics it carried, and when it was produced. It was
correct and complete, and nothing used it. Outside its own definition and test
it had two references, both re-exports.

At the same time packages.json declared:

The four SHARED project workflows (brief/risks/next/handoff) go through the
application boundary on both surfaces.

That was not true. The MCP server called the shared use case. The CLI called
only the shared document loader, then re-composed the Runtime, provider, and
Kernel itself. The two surfaces shared the first step of the pipeline and
duplicated the rest, arriving at the same answer by two different routes.

Two routes that must agree, with nothing enforcing agreement, is a drift waiting
to happen. This release closes it.

Changed

• The CLI now calls runLocalProjectWorkflow for brief, risks, next,
  and handoff — the same use case the MCP server calls. It composes no
  Runtime, provider, or Kernel for them.
• The shared workflows are describable as ApplicationResult<T>.
  runLocalProjectApplication and runGitHubProjectApplication wrap the
  existing use cases and return the envelope, with a schema version, a stable
  operation name, an injected-clock timestamp, a normalized source descriptor,
  and structured diagnostics.
• A minimal ExecutionContext carries the correlation id, the injected
  clock, and an optional cancellation signal.
• GitHub workflows accept cancellation. Checked at the last offline point
  and again after the request returns.
• tools/validate-application-boundary.mjs runs in pnpm validate and in
  CI, and fails if the boundary claim stops holding in either direction.
• One fixed-time constant. The CLI's LOCAL_FIXED_NOW is gone; both
  surfaces use the application's FIXED_LOCAL_INSTANT. They always held the
  same value for the same reason.

Unchanged

Everything a user or an MCP client can observe:

Surface	Guarantee
CLI commands & flags	identical
CLI JSON output	byte-identical
CLI Markdown output	byte-identical
CLI exit codes	identical
MCP tool names/order	identical
MCP schemas	identical
Provider diagnostics	identical
Project Memory	no format change, no migration
Command families	omp canonical, ohmypm compatibility, oh-my-pm deprecated

This is asserted, not asserted-to. tests/e2e/public-golden.test.ts replays a
29-entry recording captured from the v0.6.0 tree — stdout, stderr, exit codes,
and MCP payloads — and compares the actual bytes. It was captured before any
refactor began, so it describes v0.6.0 behaviour and cannot be adjusted after
the fact to match whatever the new code happens to produce.

What deliberately did not move

status, doctor, and plan stay outside the application boundary.

Each has exactly one presentation consumer. They appear only under cli/src/
and are absent from both MCP operation unions. Moving them would buy diagram
symmetry and no reuse, and would put a second surface's worth of contract on
commands nothing else calls. The CLI keeps a local Runtime for them, and that is
the asymmetry packages.json documents.

The validator enforces this in both directions: it fails if a shared workflow is
re-composed per surface, and if a CLI-only command is pushed through the
boundary.

Also deliberately unmoved:

• Provider diagnostic report shapes. ProviderStatusReport and
  ProviderDoctorReport stay as they are. Replacing them with the unified
  Diagnostic model would change MCP output, and compatibility outranks
  uniformity.
• Low-level helpers. A pure function still returns whatever it returns.
  Nothing is forced into the envelope to make a diagram tidy.
• The raw RuntimeResponse. It stays out of the envelope. It is
  runtime-shaped, and putting it in a result both surfaces serialize would make
  an internal type part of a public contract.

Cancellation scope

Only the GitHub workflows. They are the ones doing remote, potentially
long-running work.

Local workflows read a bounded set of configured Markdown documents. Adding
cancellation machinery to a fast, finite filesystem walk would be complexity
with no caller, so the local family takes no signal.

Two properties hold where it is implemented:

• A cancellation before the request means no transport is built and no token is
  read.
• A cancellation during the request is still a failure. The already-fetched
  payload is discarded rather than returned. Reporting data the caller asked us
  to stop fetching would make cancellation meaningless.

github_cancelled is a new public failure code in a new cancelled category:
retryable (nothing about the request was wrong), exit code 2 (not our defect and
not a bad request), and not an MCP protocol error (the caller asked for it).

Safety properties

Source descriptors and diagnostics carry no token, authorization header, raw
transport object, or resolved absolute path. A caller-supplied project root is
echoed back exactly as typed — a relative root stays relative, so an error
message never discloses where the repository actually lives.

The free-text GitHub search query is deliberately omitted from source metadata:
kind and limit already describe the search, and echoing caller text into a
descriptor both surfaces serialize would widen what a result can carry for no
identification benefit.

generatedAt comes only from the injected clock. Under a fixed clock a result
is byte-reproducible.

Verification

Check	Result
Unit tests	3027 passed / 196 files
Golden replay	31 passed, byte-identical
Boundary mutation tests	9 passed
Validators	10/10 OK
Build (incl. Rust/WASM)	pass
Lint / format / rustfmt / clippy	pass

The boundary validator reported five failures — naming exactly the CLI
duplication — before the convergence commit, and passes after it. The nine
mutation tests damage a sandboxed copy of the repository in each way the
validator claims to detect and assert it fails for the right reason, so the
check is load-bearing rather than decorative.

Not in this release

• No Project Memory format change, migration, or data movement.
• No Dashboard, and no Dashboard groundwork.
• No cloud sync, telemetry, accounts, or remote storage.
• No new command, flag, or MCP tool.
• No dependency upgrade taken as part of the release.

Next

v0.6.2 hardens Project Memory and local governed data: atomic writes, integrity
metadata, a schema migration framework, cross-process locking, path confinement,
and corruption detection with preview-first repair.

OH MY PM v0.6.0

OH MY PM v0.6.0

Canonical omp command migration and public surface stabilization.

omp is now the canonical command. This is a command namespace migration — not a
product rename, and not a data migration. If you do nothing, everything you
already have keeps working.

Changed

• omp, omp-mcp, and omp-install are canonical. They are the commands
  shown in help output, examples, and all active documentation.
• ohmypm, ohmypm-mcp, and ohmypm-install are now supported compatibility
  aliases. They were canonical in v0.5. They are not deprecated: demoting a
  name that was canonical one minor version ago would retroactively withdraw a
  promise. Each emits one notice on stderr.
• oh-my-pm, oh-my-pm-mcp, and oh-my-pm-install remain deprecated
  aliases. Each emits one deprecation notice on stderr.
• Generated MCP client configuration invokes omp-mcp. The server key is
  unchanged (see below), so regenerating does not create a duplicate entry.
• An install now writes twelve shims — six commands, each with a POSIX and a
  Windows .cmd launcher. The release bundle ships nine executables.
• command-surface.json moves to schema version 2, adding a machine-checked
  product identity block and the two distinct alias classes.

Alias behavior, for both classes:

• stdout is byte-identical to the canonical command's, so a piped --json
  invocation stays parseable.
• The notice goes to stderr only, exactly once per invocation.
• Exit codes are identical.
• The MCP stdio stream is never touched: the notice is written before the
  transport connects, so it cannot desynchronize JSON-RPC.

No removal is scheduled for either alias family.

Unchanged

Identity	Value
Product name	OH MY PM
Package scope	@oh-my-pm/*
Environment prefix	OH_MY_PM_*
Project data directory	.oh-my-pm/
User data directory	~/.oh-my-pm/
Install layout	lib/oh-my-pm/versions/<version>/
Release archives	oh-my-pm-v0.6.0.{tar.gz,zip}
MCP server key	oh-my-pm

Also unchanged:

• Project Memory — schema 1, store format 2. No data migration.
• MCP — the same twelve read-only tools, in the same order, with the same
  schemas and annotations. stdio transport only, zero write tools.
• CLI — every command, JSON output schema, Markdown report structure, and
  exit code.
• Provider behavior and the read-only policy: no project file is ever
  modified, no project context is uploaded, no telemetry is emitted.
• No Dashboard, no HTTP server, no registry publication.

Upgrading

Nothing is required. To adopt the canonical names:

# before
ohmypm brief ./project --json

# after — identical output
omp brief ./project --json

Optionally regenerate your MCP client configuration with omp mcp-config. An
existing configuration naming ohmypm-mcp or oh-my-pm-mcp keeps working.

See the v0.6 migration guide for full before/after examples.

Verification

This release was built and qualified by the manually dispatched
Release v0.6 Stable workflow, which:

• refuses any version other than 0.6.0 and any confirmation other than
  RELEASE v0.6.0;
• verifies the immutable v0.5.4 base lineage
  (288337a9514150b7a5973d9d9410f7186567520f) before building;
• builds a deterministic, reproducible omp-cli-namespace bundle and verifies
  its declared command surface, MCP tool inventory, and product identity;
• qualifies the installed artifact on Ubuntu, macOS, and Windows;
• exercises all three command families for stdout parity, stderr-only notices,
  exactly-one-warning behavior, and MCP protocol cleanliness;
• publishes only after approval of the protected github-release environment.

Known limitations

Unchanged from v0.5 and still future work:

• ApplicationResult<T> is not yet adopted by every workflow return type.
• Provider diagnostics keep their own report shape.
• Advanced side-effect analysis is not implemented.
• No Dashboard.

Requirements

Node.js 20+. No other runtime dependency; a source checkout is not required
after installation.

OH MY PM v0.5.4

OH MY PM v0.5.4

Contract and repository consistency release. It adds shared contracts at the
application boundary and makes the package dependency model explicit and
mechanically enforced.

No public behaviour changes.

Release lineage

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

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

What the audit found first

This release began with an audit of the actual tree, and the result changed its
shape. Several problems the plan anticipated did not exist:

Property	Audit result
Production dependency cycles	None. The graph was already acyclic.
Cross-package deep src/ imports	None anywhere in the workspace.
@oh-my-pm/contracts purity	Already declared zero workspace dependencies.
CLI exit-code consistency	Already consistent with the documented policy in cli/src/help.ts.
CLI/MCP shared use cases	Already shared for the four project workflows and the GitHub workflows.

So this release repairs none of those. It is important to state that plainly:
the guards below make existing correct structure permanent, they do not fix
violations. Where something genuinely did not exist, it is listed as newly
implemented.

Newly implemented

The authoritative package catalog

packages.json gives every one of the thirteen workspace packages exactly one
role plus an explicit contract: allowed dependencies, forbidden inversions,
responsibilities and non-responsibilities, public entry points, permitted process
side effects, data ownership, release-bundle status, compatibility surface, and
test ownership.

The layer order is derived from the real graph rather than an imported
convention:

contract < capability < composition < orchestration < application < presentation < packaging < development

A package may depend on its own layer or any layer to its left, never to its
right. The names describe this codebase: providers owns both the network
boundary and the ProviderRegistry abstraction that planner is written against,
so a generic domain/infrastructure split does not fit — ranking by actual longest
dependency path does.

Catalog-driven boundary validation

pnpm validate:packages derives every check from the catalog, so a package added
later inherits them instead of needing hand-written pairwise rules:

• no production dependency cycle (dev-only edges are correctly not treated as
  cycles);
• dependencies point down the layer order and stay inside the declared allowance;
• no package reaches inside another's src/, dist/, or test/;
• no package imports a workspace package it does not declare;
• no package below presentation writes to stdout/stderr or calls
  process.exit;
• declared exports match the catalog's entry points;
• the catalog's inBundle claims match the real release dependency closure;
• every package has a README.

This extends rather than duplicates tools/validate-boundaries.mjs, which
keeps its specific high-value pairwise rules and its release/workflow policy.

The shared application result contract

interface ApplicationResult<TData> {
  schemaVersion: string;
  operation: string;
  generatedAt: string;
  source: SourceDescriptor;
  data: TData;
  diagnostics: Diagnostic[];
  provenance: ProvenanceRecord[];
}

ApplicationResult<T> is additive. ProjectWorkflowResult and
GitHubWorkflowResult keep their exact shapes and public behaviour; the envelope
gives them a shared identity so a consumer can ask "where did this come from?"
without knowing which use case it called. Nothing is forced into it.

Serialization is deterministic: applicationResultToJson emits canonical key
order and sorts selection and details keys, so byte-identical inputs give
byte-identical output however the object was assembled. generatedAt comes from
the caller's injected clock, keeping results reproducible.

Normalized source descriptors

A closed set of eight source kinds — local project, four GitHub shapes, GitHub
search, Project Memory snapshot, Project Timeline — each carrying identity and
bounded selection metadata only. Never a token, an authorization header, a raw
transport object, a resolved absolute path, or document content.
assertSafeSourceDescriptor is the single shared enforcement.

On paths specifically: a failure message echoes the root the caller supplied,
verbatim. If a caller passes an absolute path, an absolute path comes back — that
is their own string, not a disclosure. The guarantee is that nothing resolves
the root before reporting it.

Provenance contracts

ProvenanceRecord is optional by design — attaching it to every trivial field
would bloat simple outputs. It supports the source, a repository-relative document
path, a line or range, a GitHub item number, a snapshot id, the deriving rule, and
a truncated flag so a bounded read is not mistaken for a complete one.

Unified diagnostics and a repository-wide error taxonomy

One Diagnostic shape with a stable machine-readable code, a three-level
severity, optional remediation and retryability, an optional narrower source, and
JSON-safe details only — never a cause chain or a stack trace.

Eleven error categories, each with a complete behavioural contract: retryability,
CLI exit code, severity, and whether MCP marks the result an error.

Every existing public failure code is classified; none is renamed or removed.
Those code strings appear in CLI JSON and MCP results, so they are public. Two
tests keep the table honest in both directions: every declared code must be
classified, and every classified code must still be declared.

CLI exit-code and MCP error mappings

The exit-code policy is the one already documented in cli/src/help.ts and
already implemented — 0 success, 1 runtime execution failed, 2 invalid
invocation or a controlled precondition failure. This release makes it explicit
and testable; it changes no exit code.

MCP preserves the machine-readable code and sanitized message, and keeps an
expected validation failure a structured result rather than an unstructured
crash, so an agent can read the code and correct its own call.

Direct CLI/MCP semantic parity assertions

tests/e2e/semantic-parity.test.ts compares the two surfaces against each
other. The pre-existing extraction-parity.test.ts runs each surface against
its own expected shape and re-runs it for determinism — both files could pass
while CLI and MCP quietly diverged, because nothing compared one to the other.

Covered: the four shared local project workflows, the four shared GitHub
workflows, the document set behind both surfaces, failure-code agreement,
exit-code agreement with the taxonomy, sanitized-message agreement, and the
absence of any token or authorization header in either surface's output.

Consolidation, and its deliberate limit

application/src/errors.ts and application/src/provider-diagnostics.ts were the
migration inputs. The outcome differs between them, for a reason worth recording:

• errors.ts keeps its two sanitization helpers (sanitizedErrorCode,
  looksLikeAbsolutePath). They are used, correct, and orthogonal to the
  taxonomy.
• provider-diagnostics.ts keeps its report types unchanged, and gains an
  adapter instead. buildProviderStatusReport(...) is returned directly as
  the result of the provider_status and github_provider_diagnostics MCP tools
  and printed by the CLI under --json, so its schemaVersion: 1 and its
  ok | info | warning | fail vocabulary are a client-facing contract.
  Rewriting those types onto Diagnostic would change an MCP tool's output
  schema, which this release must not do.

application/src/diagnostics-adapter.ts projects those reports into the unified
model for consumers that want one vocabulary. The report types are documented in
docs/v0.5/contracts.md as deliberately retained public
shapes, not leftovers.

The intentional CLI asymmetry, documented not "fixed"

@oh-my-pm/cli declares runtime, providers, skills, and kernel while
@oh-my-pm/mcp-server reaches the shared project workflows through
@oh-my-pm/application. This is intentional.

cli/src/local-process.ts composes a local Runtime for status, doctor, and
plan: runtime-identity and free-form planning commands that the application
boundary does not expose and that no second surface consumes. The four shared
project workflows and the GitHub workflows go through the application boundary on
both surfaces.

Extending the boundary to absorb those three commands purely for symmetry was
considered and rejected: it would restructure three packages to tidy a diagram
without a second consumer to justify it. If a future surface ever needs runtime
identity, that is the point at which the boundary should grow — driven by a real
consumer. The asymmetry is recorded in packages.json and
docs/v0.5/contracts.md.

Separately, @oh-my-pm/project-memory is a production dependency of the CLI
so it ships in the bundle, while being reached only through a lazy dynamic import.
cli/test/memory-boundary.test.ts enforces both halves. It is not an unused
dependency, and it was not "cleaned up".

Compatibility policy

[`do...

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...

OH MY PM v0.5.2

OH MY PM v0.5.2

Maintenance release. It fixes one internal architecture problem and adds no
user-facing capability.

The GitHub-backed project workflow was duplicated across presentation adapters.
@oh-my-pm/application already owned a shared GitHub use case, but the MCP
server reimplemented the same pipeline, and the CLI assembled its own Runtime
rather than consuming the shared one.

Everything you can observe is unchanged from v0.5.1. No migration is
required.

Release lineage

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

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

What changed

One shared GitHub application use case

CLI and MCP are now genuinely presentation adapters over the same GitHub
workflow, matching the boundary v0.5.1 established for local Markdown workflows.

CLI GitHub adapter ──┐
                     ├──> @oh-my-pm/application GitHub use case
MCP GitHub adapter ──┘         │
                               ├──> injected provider configuration
                               ├──> lazy transport creation
                               ├──> injected clock
                               └──> Runtime / Kernel / Providers / Skills

@oh-my-pm/application owns workflow sequencing, effective provider settings,
repository validation, source selection, limit resolution, fail-closed ordering,
Runtime composition, request construction, execution, and output extraction.
@oh-my-pm/application/node owns the provider-config file load, the optional
token environment read, platform/cwd resolution, real transport construction,
and real clock access.

The adapters keep only what is theirs. The CLI owns its grammar, its
config-path allowance, output-mode selection, terminal formatting, stream
routing, and exit codes. The MCP server owns tool registration, input schemas,
annotations, agent-safe restrictions, strict source projection, structured
content, and protocol stdout safety.

Neither adapter composes a Kernel, Runtime, provider registry, skill registry,
or Node transport any more.

Fail-closed ordering is now enforced by construction

The shared dependency contract became lazy. Provider configuration resolves
first, then the effective repository, then the source selection — and only then
may a transport be created or a clock read.

The previous contract took an eagerly-resolved token, so composing the
dependencies read the environment before any validation ran. The token read now
happens inside the transport factory closure, which the use case invokes only
after every controlled input has validated. An injected transport skips it
entirely, so offline test suites never touch the environment.

A misconfigured call therefore reads no token, opens no transport, and reads no
clock. New tests count those dependency invocations directly.

Caller identity is injected, not assumed

The shared use case hardcoded caller: "mcp". It was only reachable from MCP, so
nothing had broken yet — but routing the CLI through it would have silently
mislabelled every CLI request identity and payload source. caller is now a
required injected value, and both surfaces are covered by tests.

Request identities are unchanged: cli-github-{brief,risks,next,handoff} and
mcp-github-{brief,risks,next,handoff}.

One canonical MCP version

The MCP GitHub runner declared MCP_GITHUB_RUNTIME_VERSION = "0.3.0" against a
0.5.1 source. Consolidating onto a single canonical constant surfaced a second
stale "0.3.0" in the provider diagnostics runner, and two further duplicated
literals in the server and project tool runner.

All four now derive from OH_MY_PM_MCP_VERSION in mcp-server/src/version.ts,
leaving exactly one place for a release bump to touch. These values only ever
fed the outbound user agent and the server handshake, so no observable output
changed.

Boundary guards

New validators keep the duplication from returning: neither GitHub adapter may
name the Kernel/Runtime/provider/skill/transport constructors or resolve
settings and selection itself, both must call the shared use case, the core use
case may not construct a Node transport or read process/clock/filesystem state
or hardcode a caller, and the MCP package may declare only one version literal.

The CLI purity test also got stricter: local-process.ts no longer reads the
environment or builds a transport, so its GitHub boundary exemption is gone and
both CLI GitHub files are held to the strictest rules.

Deterministic release-test execution

CI qualification was intermittently failing on unchanged source, in a different
suite each run. Every Vitest file ran with default file parallelism, so the
release, archive, and installation suites could each build a bundle at the same
time. Because that builder runs pnpm deploy and reads the shared workspace
build output while computing the bundle's internal SHA256SUMS, concurrent
suites could leave a bundle whose manifest no longer matched its own contents —
surfacing as source:sha256sums_checksum_mismatch.

v0.5.2 splits the test topology into a parallel unit project and a serialized
release project, so the release/archive/install suites never run concurrently
with one another or over the same build output. Pure tests keep full
parallelism. A regression guard fails when a new shared-resource suite is not
classified.

Archive utility probing was also wrong in two ways: any spawnSync failure was
reported as a missing prerequisite, so a transient error on a loaded machine
looked like an absent tool, and a utility that ran but exited non-zero counted
as available. Probes now classify as available, genuinely missing (ENOENT), or
probe-failed, with a bounded retry for transient errors only and a distinct
release_archive_prerequisite_probe_failed:<utility> reason. Genuinely missing
tools keep their existing reason.

Release fixture setup hooks now report the command, status, signal, spawn error
code, and bounded output instead of only an exit status.

This is test and CI infrastructure only. No product behavior, release artifact
format, or checksum algorithm changed.

Compatibility

This release is behavior-preserving. Verified by pre/post byte-parity fixtures
across 39 CLI cases and 25 MCP cases, plus a full protocol-surface capture over
real stdio JSON-RPC.

• no new command, no removed command
• no CLI syntax change
• no intentional JSON output change except version-bearing fields
• no MCP tool change, schema change, annotation change, or tool-order change
• no Project Brain schema change (schema 1)
• no Project Memory format change (store format 2)
• no data migration
• no Dashboard
• no npm publication
• no GitHub mutation capability — the provider stays GET-only against a fixed
  origin
• no HTTP MCP transport — stdio only

The twelve read-only MCP tools, zero write tools, eight installed shims, seven
memory subcommands, and the ohmypm-cli-namespace bundle profile are all
unchanged.

Verification

pnpm install --frozen-lockfile
pnpm build:contracts
pnpm build:kernel
pnpm build
pnpm test
pnpm validate
pnpm mcp:smoke
cargo test --workspace
cargo clippy --workspace --all-targets

Publication

v0.5.2 is prepared but unpublished. See
publishing-v0.5.2.md for the gated procedure.

OH MY PM v0.5.1

OH MY PM v0.5.1

Maintenance release. It fixes two internal problems and adds no user-facing
capability.

1. Active documentation no longer matched the shipped product.
2. Shared application logic lived inside the CLI package, so the MCP server had
   to depend on the CLI to reuse it.

Everything you can observe is unchanged from v0.5.0. No migration is
required.

Release lineage

There is no v0.5.0 tag and no v0.5.0 GitHub release. The v0.5.0 work
merged to main as a source candidate and was never published.

Latest published stable, and immutable base	v0.4.0
v0.5.0	superseded, unpublished source candidate
v0.5.1	prepared; would be the first published stable of the v0.5 line

No existing release tag is moved, replaced, recreated, or deleted, and no
v0.5.0 tag is invented. Merging the v0.5.1 pull request publishes nothing.

What changed

Active documentation corrected to match the actual system

The repository shipped five release lines while parts of its documentation
stayed frozen at v0.2 and v0.3. The corrections are not cosmetic — several
claims inverted reality:

Document	Was	Now
project-memory/README.md	"Nothing invokes it yet"	lists the seven CLI subcommands and two MCP tools that invoke it
runtime/src/index.ts	"no CLI or MCP surface invokes the Project Brain Runtime"	describes the surfaces that do
installer/README.md	"does not write files ... will be added in a later phase"	documents the shipped transactional prefix install
docs/architecture.md	the initial scaffold and a "planned" architecture	the implemented system, all layers, and the enforced boundaries
README.md	the 0.3.1 source line, ten MCP tools, "early-stage"	the current source line, twelve tools, the shipped capability table
mcp-server/README.md	eleven tools, project_timeline absent	all twelve in registration order, zero write tools
cli/README.md	six memory subcommands, ten MCP tools	seven subcommands, twelve tools
docs/getting-started.md	v0.2.0 as latest stable, four shims, eleven tools	v0.4.0, eight shims, twelve tools
docs/roadmap.md	v0.4.0 "prepared but not published", v0.4 active	v0.4.0 published, v0.5.1 active, explicit states
docs/security-model.md	project data in .oh-my-pm/ inside the project	the application-data boundary the code enforces

Historical documents were deliberately left alone. docs/releases/**,
docs/v0.3/**, docs/v0.4/**, the v0.2 stabilization audit, and superseded
CHANGELOG entries are point-in-time records; their old versions and tool counts
were true when written and remain historically accurate.

A new validator, pnpm validate:docs, keeps them honest. It derives every
expectation from a canonical source — version.json, command-surface.json,
the MCP tool registration sites, and the memory subcommand allowlist — so it
introduces no second source of truth.

Shared application boundary

New private workspace package @oh-my-pm/application. CLI and MCP are now
presentation adapters over the same typed use cases.

CLI ───────────┐
MCP ───────────┼──> Application ──> Runtime / Providers / Project Memory
Future UI ─────┘                    └──> Planner / Skills / Kernel

The Future UI line is architectural context only. This release includes no
Dashboard.

The modules were moved, not copied, so no orchestration is duplicated. The MCP
server's dependency on @oh-my-pm/cli is removed from its manifest and from
every import.

See the application boundary and
the v0.5.1 scope.

What did not change

Surface	v0.5.1
Canonical commands	ohmypm, ohmypm-mcp, ohmypm-install
Compatibility aliases	oh-my-pm, oh-my-pm-mcp, oh-my-pm-install — no removal scheduled
CLI commands, grammar, options, defaults	unchanged
CLI exit codes and stdout/stderr separation	unchanged
CLI JSON and Markdown output	unchanged
MCP tools	twelve read-only, zero write, exact same registration order
MCP schemas, annotations, error codes	unchanged
MCP transport	stdio only
Memory subcommands	seven
Project Brain schema	1
Project Memory store format	2
Storage paths and record formats	unchanged
Release line / bundle profile	v0.5 / ohmypm-cli-namespace
Node.js runtime	20+
npm publication	none; packages remain private

• No new user-facing feature.
• No new command.
• No new MCP tool.
• No schema or store-format change.
• No migration is required.
• No Dashboard is included.
• No release is published by merging the pull request.

Upgrading

Nothing to do. An existing installation, an existing MCP client configuration,
and an existing Project Brain store all keep working unchanged. deprecatedSince
remains 0.5.0 — the aliases were deprecated then, and that fact is unchanged.

Verification

Public compatibility was verified against a pre-refactor build:

• CLI stdout, stderr, and exit codes byte-identical across seventeen
  representative invocations, including error paths. The only difference is the
  version and kernelVersion fields, which report 0.5.1.
• The MCP tool list, registration order, input and output schemas, and
  annotations compared byte-for-byte against a captured v0.5.0 server response:
  identical.
• Both compatibility aliases still warn on stderr only, never on stdout.

New enforcement:

• pnpm validate:docs — documentation truth
• pnpm validate:boundaries — the application boundary, with guards verified by
  injecting each violation
• mcp-server/test/application-boundary.test.ts — the twelve-tool contract and
  the absent CLI dependency

Related issues

Closes #23, #24, #25, #26, #27.

OH MY PM v0.4.0

OH MY PM v0.4.0

Stable release opening the v0.4 line. It adds one main capability —
Project Timeline — and changes nothing else.

Project Timeline answers "what changed in this project, and when?" from local
committed memory alone: a bounded, deterministic history derived from
already-captured Project Brain snapshots, in authoritative capture order,
filterable and paginated. It is read-only end to end.

The single main capability: Project Timeline

The v0.3 Project Brain could already compare the two most recent captures
(memory changes / project_changes). It could not answer the same question
across the whole recorded history. v0.4 closes exactly that gap.

A timeline is derived, never stored. Each query reads the store's
authoritative capture chronology, compares adjacent committed snapshots through
the existing deterministic change engine, and projects the results into bounded,
sanitized events. There is no timeline file, no timeline record type, and no
timeline store.

memory timeline — added

oh-my-pm memory timeline
  --project-id <id>       required
  --data-dir <path>       optional
  --limit <1-100>         optional, default 20
  --before-sequence <n>   optional
  --category <value>      optional
  --kind <value>          optional
  --json | --markdown     optional (brief is the default)
  --help | -h

• Exits 0 on success and 2 on any usage error, matching every other command.
• Writes to stdout only on success; failures write to stderr only.
• Ends with exactly one newline and is byte-identical across repeated runs.
• Needs no project root and reads no project config or project document — the
  project is identified by --project-id alone.
• Has no --apply: there is nothing to apply.
• Markdown output groups events by capture under fixed headings and invents no
  summary; every line restates recorded fields.

project_timeline — added

One new read-only stdio MCP tool, appended after the existing eleven.

• Input: projectId (required), limit, beforeSequence, category, kind.
• Output: schemaVersion, projectId, eventCount, hasMore,
  nextBeforeSequence, chronology, events.
• Declares readOnlyHint: true and destructiveHint: false.
• Loads the memory dependency lazily on its own path only, exactly as
  project_changes does.

Event model

Each event carries exactly these fields and nothing else:

eventId, snapshotId, captureSequence, eventSequence, capturedAt,
category, kind, subjectId, title?, status?, severity?, dueDate?,
evidenceCount.

Evidence is reported as a count, never an id. category and kind reuse the
existing ChangeSet taxonomy exactly — the twelve change categories and the six
item kinds. No second taxonomy was introduced.

Ordering, filtering and pagination

• Events order by captureSequence, then eventSequence. The authoritative
  capture chronology is the only ordering source: never a lexical snapshot-id
  order, and never a timestamp comparison while a capture sequence exists.
  capturedAt is presentation data, not a sort key.
• category and kind filter independently and combine as a conjunction, and
  are applied before the limit, so a page is never short because filtered-out
  events consumed its budget.
• Pagination is by capture boundary, so a page never splits a capture.
  hasMore and nextBeforeSequence are stable and truthful: paging with the
  returned cursor yields the next page with no duplicate and no skip.
• The same store and the same inputs produce byte-identical output.

Surface counts

Memory subcommands:      7
MCP tools:               12
MCP write tools:         0
MCP transport:           stdio only
Project Brain schema:    1
Store format:            2
Store migration:         not required
Installed runtime:       Node.js 20+
Packages:                private
Registry publication:    none

The six existing memory subcommands (capture, changes, status, history,
export, delete) and the eleven existing MCP tools keep their exact names,
options, output shapes, registration order and exit codes. timeline is the
seventh subcommand and project_timeline the twelfth tool, both appended last.

Not changed

• No schema change. Project Brain schema stays 1.
• No store-format change. Project Memory store format stays 2.
• No migration. A Project Brain store created by the public v0.3.1 build is
  read directly with no migration and no repair. This is qualified explicitly: a
  v0.3.1-shaped store serves every read surface, including the new timeline, with
  no manifest migration entry, no backup, no migrationRequired status, and
  byte-identical store bytes after every read.
• No write path. No project file is written. No application-state write, lock,
  staging directory, or backup is created by any timeline read, and no
  application-data directory is created on a read.
• No timeline persistence. A timeline is recomputed per query.
• No automatic capture. Capture stays explicit and user-invoked; there is no
  watcher, scheduler, or background process.
• No network. The timeline surface performs no request and reads no token.
• No new provider, alias, or profile. The timeline never reaches a provider.
• No registry publication. All workspace packages remain private.
• No telemetry, dashboard, or web UI.

Safety and privacy

• Project files are never modified. Byte-for-byte immutability of the analyzed
  project is asserted by test.
• No project content is uploaded.
• The privacy allowlist is enforced at three independent layers: the pure
  derivation constructs events from allow-listed fields only; the MCP projection
  re-validates against a strict schema and rejects rather than partially emits;
  and the serialized output passes a forbidden-marker scan. Absolute paths,
  oversize values, and planted secret sentinels are omitted from optional display
  fields.
• Raw evidence, evidence ids, unrestricted previous/current values, file paths,
  application-data paths, provider results, environment values, credentials, lock
  details, integrity internals, and stack traces never appear in output.

Failure behavior

Timeline reads fail closed. There is no partial timeline.

Condition	Behavior
malformed query	controlled validation failure (exit 2)
unknown project	valid empty result (exit 0)
zero or one snapshot	valid empty result (exit 0)
missing or corrupt snapshot	fail closed, no partial output
corrupt manifest	fail closed
integrity mismatch	fail closed
store with no authoritative chronology	fail closed, never migrate
unsupported store format	fail closed, never migrate
store format 1	fail closed; explicit CLI migration remains the only path
concurrent capture during a read	committed-manifest semantics only

Validation

• Kernel: 34 native tests over the deterministic derivation, plus a committed
  golden fixture asserted from both the native Rust and the WASM binding
  paths, so a cross-language divergence fails a test.
• Contracts: 12 tests over the three new bounded contracts.
• Runtime: 28 tests proving read-only behavior, chronology authority, and
  fail-closed corruption handling.
• CLI: 73 tests including a real-child-process end-to-end journey over a real
  store.
• MCP: 94 tests over the projector, the runner against the real adapter, and
  server registration and projection.
• Installed qualification: 428/428 checks from each of the .tar.gz and
  .zip archives on Ubuntu, macOS and Windows — including the new
  timeline-cli, timeline-mcp and v0.3.1-compatibility sections.
• Deterministic archives, archive reproducibility, checksums, one top-level
  archive directory, source-checkout independence, and prefix relocation.

Assets

oh-my-pm-v0.4.0.tar.gz
oh-my-pm-v0.4.0.zip
oh-my-pm-v0.4.0-SHA256SUMS.txt

Verify the checksums before installing:

shasum -a 256 -c oh-my-pm-v0.4.0-SHA256SUMS.txt

Compatibility

• v0.3.1 remains published and immutable; it is not modified, moved, or
  recreated by this release, and neither are v0.1.0, v0.2.0-rc.1, v0.2.0,
  v0.3.0-rc.1, or v0.3.0.
• Existing v0.3.1 installations upgrade in place with no store change.
• The same profile-aware installer and verifier still resolve the historical
  v0.2 (ten-tool) and v0.3 (eleven-tool) surfaces, so an upgrade from any earlier
  line is served by one installer.

OH MY PM v0.3.1

OH MY PM v0.3.1

Stable patch release for the v0.3 line. It adds two CLI usability improvements
and changes nothing else. There is no schema, store-format, or MCP capability
change, and no behavior change to any existing command.

This release fixes:

• Issue #2 — the CLI had no conventional --help output.
• Issue #3 — installed users had to configure MCP integration by hand.

Included

• Conventional CLI help — oh-my-pm --help and oh-my-pm -h print bounded,
  deterministic help to stdout and exit 0. Help lists the real current commands
  and namespaces, short usage examples, the output modes, and the controlled
  exit-code meanings. Namespace and command help is available in the same form,
  including oh-my-pm memory --help and oh-my-pm providers --help.
• Installed MCP client configuration — oh-my-pm mcp-config prints a generic
  stdio MCP client configuration for the installed MCP server. It supports
  --json (default), --markdown, --name <name>, and --help / -h.

Help behavior

• Exits 0, writes to stdout only, writes nothing to stderr.
• Ends with exactly one newline and is byte-identical across repeated runs.
• Performs no network access, creates no file or application-data directory, and
  reads no token.
• Unknown commands and options keep their existing nonzero usage exit code.

mcp-config behavior

• Resolves the installed sibling oh-my-pm-mcp executable from the actual
  installed location, so installed users never pass --prefix.
• Emits an absolute command path with args: [].
• Works on POSIX and Windows, including the Windows .cmd shim.
• Follows a relocated install prefix instead of embedding an install-time path.
• Writes no MCP client file and no project file, and performs no network access.
• Contains no token, credential, environment value, project root, provider
  response, or hidden state.
• Uses controlled exit 2 for an invalid argument or a missing installed
  executable, and produces newline-terminated deterministic output.
• Markdown output describes exactly the eleven read-only tools, including
  project_changes.

Not changed

• No schema change. Project Brain schema stays 1.
• No store-format change. Project Memory store format stays 2.
• No MCP capability change. Exactly eleven read-only MCP tools in the same
  fixed registration order; zero write tools; stdio only; the protocol, tool
  order, tool count, and capabilities are untouched.
• No memory surface change. Exactly the six memory subcommands.
• No change to existing command semantics or output.
• No new provider, alias, profile, or telemetry.
• No registry publication. All workspace packages remain private.

Safety

• Project files are never modified.
• Memory writes only through explicit CLI --apply.
• The MCP server performs no Project Brain writes.
• No telemetry, no context upload, no network in the memory or help paths.
• Tokens are environment-only — never persisted, printed, or stored. Neither
  help nor mcp-config reads or prints a token.

Compatibility

• Node.js 20+ (the installed runtime baseline; unchanged).
• Windows, macOS, and Linux.
• Project Brain schema 1.
• Project Memory store format 2.
• Fully compatible with a v0.3.0 installation: no migration is required.

Lineage

This patch builds on the immutable stable v0.3.0 release (tag target
0d6f9b1c66ac01835e5f7bf2c8512b5beea50014), which remains immutable and
unchanged. The immutable v0.1.0, v0.2.0-rc.1, v0.2.0, and v0.3.0-rc.1
releases are likewise unchanged.

MCP surface

Eleven read-only MCP tools over stdio, in exact registration order — identical to
v0.3.0:

project_brief
project_risks
project_next
project_handoff
github_project_brief
github_project_risks
github_project_next
github_project_handoff
provider_status
github_provider_diagnostics
project_changes

Assets

oh-my-pm-v0.3.1.tar.gz
oh-my-pm-v0.3.1.zip
oh-my-pm-v0.3.1-SHA256SUMS.txt

Both archives carry the same self-contained "project-brain" profile bundle
(eleven MCP tools, the bundled @oh-my-pm/project-memory package, the six memory
subcommands, Project Brain schema 1, store format 2). They are byte-reproducible
and have equivalent logical inventories.

Getting started

See getting-started-installed.md for
download, checksum verification, preview-first installation, capture, status,
history, changes, export, delete, MCP client configuration, and the explicit
v1 → v2 migration command.

OH MY PM v0.3.0

OH MY PM v0.3.0

Stable Project Brain foundation for the v0.3 line. This stable release is the
validated promotion of the v0.3.0-rc.1 prerelease — no product behavior changed
between the validated candidate and this stable release; only the version string
moved from 0.3.0-rc.1 to 0.3.0 (plus CI-only artifact-action maintenance and
documentation).

Included

• Local Markdown Project Brain capture — derive project state from the
  configured Markdown documents, fully offline.
• Minimized evidence — each observation persists a content fingerprint and
  allow-listed provenance only; never raw document bodies.
• Deterministic snapshots and changes — equal inputs and injected clock
  produce equal snapshot state fingerprints and equal change sets.
• Capture-order history — memory history presents snapshots in real
  capture order (store format 2), newest capture first.
• Preview-first memory CLI — capture, changes, status, history,
  export, delete. Mutating commands default to a zero-write preview and apply
  only with --apply.
• Export and delete — copy committed memory to an explicit destination, and
  remove a project's memory with explicit confirmation.
• Explicit store migration — the store-format 1 → 2 migration runs only on
  memory capture --apply --migrate-store, retains a backup, and never runs from
  a read.
• Read-only project_changes MCP tool — a bounded, sanitized projection of
  already-captured memory over stdio.
• Cross-platform installed qualification — the installed artifact is
  qualified on Windows, macOS, and Linux (Node.js 20+).

Safety

• Project files are never modified.
• Memory writes only through explicit CLI --apply. Previews and read
  commands write nothing and create no application-data directory.
• The MCP server performs no Project Brain writes. project_changes is
  read-only; there are zero Project Brain write tools.
• No telemetry, no context upload, no network in the memory path.
• No cloud or database requirement. Memory lives in the local
  platform-standard application-data directory.
• No raw body persistence by default.
• Tokens are environment-only — never persisted, printed, or stored.
• No registry publication. All workspace packages remain private.

Not included

• GitHub memory capture (the memory CLI captures local Markdown only).
• Restore / import / prune / repair.
• Automatic migration (migration is explicit and preview-first only).
• HTTP / SSE / WebSocket MCP (stdio only).
• MCP write tools (zero Project Brain write tools).
• A dashboard or UI.
• Cloud sync.
• Registry packages.

Compatibility

• Node.js 20+ (the product runtime baseline; unchanged by the CI move to
  Node 24 for GitHub Actions JavaScript actions).
• Windows, macOS, and Linux.
• Project Brain schema 1.
• Project Memory store format 2.
• Explicit v1 → v2 migration via memory capture --apply --migrate-store.

Promotion lineage

This stable release was promoted from the validated prerelease v0.3.0-rc.1
(tag target 1db4057b7dfb31cae7f0d6db593928ee1287ef85) after the recorded
post-publication validation
(v0.3.0-rc.1-post-publication-validation.md)
returned GO FOR v0.3.0 STABLE PREPARATION. The immutable v0.1.0,
v0.2.0-rc.1, v0.2.0, and v0.3.0-rc.1 releases are unchanged.

MCP surface

Eleven read-only MCP tools over stdio, in exact registration order:

project_brief
project_risks
project_next
project_handoff
github_project_brief
github_project_risks
github_project_next
github_project_handoff
provider_status
github_provider_diagnostics
project_changes

project_changes is the single Project Brain read tool. The historical v0.2.0
artifact remains a ten-tool surface and is unchanged.

Assets

oh-my-pm-v0.3.0.tar.gz
oh-my-pm-v0.3.0.zip
oh-my-pm-v0.3.0-SHA256SUMS.txt

Both archives carry the same self-contained "project-brain" profile bundle
(eleven MCP tools, the bundled @oh-my-pm/project-memory package, the six memory
subcommands, Project Brain schema 1, store format 2). They are byte-reproducible
and have equivalent logical inventories.

Getting started

See getting-started-installed.md for
download, checksum verification, preview-first installation, capture, status,
history, changes, export, delete, MCP client configuration, and the explicit
v1 → v2 migration command.