Add the LogicSRC OpenContext specification (#132)

* Add the LogicSRC OpenContext specification

OpenContext is an open specification for durable, portable, permissioned,
provenance-aware context shared between humans and AI agents. It defines how
organizational knowledge is described, authorized, versioned, resolved,
audited, and handed between replaceable workers without losing institutional
state.

Follows the OpenPRD/OpenOntology pattern already in the repo: self-contained
JSON Schemas in @logicsrc/schemas, a reference implementation package, CLI
subcommands, docs, examples, and an OpenPRD record.

Schemas (8, all self-contained so a third party can fetch one file and
validate against it with no further resolution):
  manifest, object, bundle, role, provenance, decision, diagnostic,
  audit-event — registered in @logicsrc/validators and schemas:validate.

Reference implementation (@logicsrc/opencontext):
  loader with upward manifest discovery, the full resolution pipeline,
  authority/supersession, permissions, redaction, lifecycle, provenance,
  deterministic digests, doctor, search, graph, history/diff, guarded writes,
  audit events, and file/http/git/sqlite adapters.

CLI: all 15 specified commands, as a standalone `opencontext` binary and as
`logicsrc context`, sharing one implementation so the two cannot drift.

Design decisions worth noting:

- Supersession is declared, never inferred from version numbers. Inferring it
  would hide the governance failure it represents and make
  multiple-active-versions and duplicate-canonical impossible to detect.

- The bundle digest identifies the resolved context, not the moment it was
  computed, so generated_at/bundle_id/digest/as_of are excluded while objects,
  lifecycle states, exclusions and warnings are covered. That is what lets a
  decision record cite exactly the context that produced it.

- A role's own max_classification beats an inherited one, so a ceiling on a
  shared base role cannot silently cap a role deliberately granted more;
  requesting several roles at once still takes the lowest, so combining roles
  never escalates.

- Scope wildcards match whole dotted segments only. A trailing .* covers a
  subtree; an interior * matches exactly one segment. Substring matching here
  would be an access-control bug.

- --include narrows an existing scope and is applied after it, never merged
  into it, so a request can never widen what a role holds.

Verified: 226 tests across core primitives, permissions/redaction, the
resolution pipeline, security, the published conformance fixtures (13 valid,
35 invalid, 8 resolution scenarios), project behaviour, and the five shipped
examples — which are held to --strict and a 100% health score. Benchmarks meet
every published budget (resolve 1,000 objects in ~33ms against a 2s target).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Point install docs at @logicsrc/opencontext; record the npm name collision

The unscoped `opencontext` name is already published on npm by an unrelated
third party (federicodeponte/opencontext, 2.0.0), so `npx opencontext` would
install a stranger's package. Docs now use `npx @logicsrc/opencontext`; the bin
stays named `opencontext` so the command reads as the PRD specifies once
installed.

Recorded in PRD 0003 as a blocker to resolve before any publication, along with
the fact that no @logicsrc spec package has ever been published, so there is no
existing release path to slot into.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Advance the logicsrc-mcp next-PRD-id assertion to 0004

standards.test.ts asserts prd_next_id against the live prd/ directory, so
adding PRD 0003 makes the next free id 0004. The test's own comment
anticipates this: "advances with every PRD added".

Caught by CI, not locally — the earlier verification ran per-package tests for
the packages this branch touches, and logicsrc-mcp is coupled to the PRD
directory without importing from it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/opencontext/manifest.md

@@ -0,0 +1,282 @@
+# Manifest reference
+
+`opencontext.yaml` is the control plane. It declares what context exists, where it is loaded from, who may read it, how authority is ranked, how freshness is judged, and what is audited.
+
+It is not the database. It points at systems that remain the sources of truth.
+
+Schema: `https://logicsrc.com/schemas/opencontext/manifest.schema.json`
+
+Discovery searches upward from the working directory, the way git finds `.git`, so commands work from anywhere inside a project. `opencontext.json` and `opencontext.yml` are also accepted.
+
+## Minimal
+
+```yaml
+opencontext: "1.0"
+id: example
+```
+
+`opencontext` and `id` are the only required fields.
+
+## Identity
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `opencontext` | string | Spec version, e.g. `"1.0"`. A major version the runtime does not support is refused, never partially parsed. |
+| `id` | slug | Namespace. Object ids are unique within it. |
+| `name` | string | Human-readable organization or project name. |
+| `description` | string | One paragraph on what this repository covers. |
+
+## `context` — single documents
+
+Each key becomes a resolvable object id; each value is a path or URI.
+
+```yaml
+context:
+  mission: ./context/mission.md
+  glossary: ./context/glossary.md
+  handbook: https://intranet.example.com/handbook.md
+```
+
+A document may declare its own `id` in front matter, which wins over the key.
+
+## `collections` — globs
+
+The key namespaces the ids of everything the collection loads, so `./context/policies/refunds.md` under `policies` resolves as `policies.refunds`.
+
+```yaml
+collections:
+  policies: ./context/policies/**
+  procedures:
+    source: ./context/sops/**
+    type: procedure
+    layer: L4
+    owner: support
+    ttl: 180d
+```
+
+A bare string is the glob. The object form adds defaults applied to members that omit them.
+
+**Glob syntax.** `**` crosses directories; `*` and `?` never do. Files are picked up only with a context extension (`.md`, `.markdown`, `.yaml`, `.yml`, `.json`) unless the pattern names one explicitly. `node_modules`, `.git`, `dist`, `build`, and dot-directories are skipped.
+
+**Derived ids.** A member that declares no `id` gets one derived from its path relative to the collection base: `support/refund.md` in `policies` becomes `policies.support.refund`. `index.md` and `readme.md` resolve to the directory itself.
+
+> A document that declares an id outside its collection's namespace keeps that id. `policies` loading a file that declares `id: pricing.enterprise` produces `pricing.enterprise`, which `policies.*` will not match. Declare ids that match the collection, or rely on derivation.
+
+## `roles` — scopes
+
+```yaml
+roles:
+  everyone:
+    include: [mission, glossary]
+
+  support:
+    description: Front-line customer support.
+    inherits: [everyone]
+    include:
+      - policies.*
+      - customers.*
+    exclude:
+      - policies.internal.*
+      - customers.*.churn-risk
+    permissions: [customer.read, ticket.write]
+    max_classification: internal
+    redact:
+      - path: ssn
+        mode: remove
+        reason: PII
+```
+
+See [permissions and scopes](./permissions.md) for the full model. In short: scope is opt-in, deny always overrides allow, and inheritance can only narrow.
+
+## `agents` — consumers
+
+```yaml
+agents:
+  support-agent:
+    roles: [support]
+  dev-agent:
+    roles: [engineering]
+    description: Ships product code.
+```
+
+An agent holds no rights of its own beyond the roles listed. A role named here that the manifest does not define is a validation error — a typo silently denying access is exactly the failure this catches.
+
+## `authority`
+
+```yaml
+authority:
+  precedence:
+    - canonical
+    - approved
+    - reference
+    - observed
+    - inferred
+    - historical
+  tie_breakers: [version, updated, confidence, id]
+```
+
+`precedence` may be reordered but must remain a permutation of all six levels. Omitting one would leave objects at that level unrankable; adding one would let a repository define something that outranks canonical.
+
+`tie_breakers` apply when authority does not settle it. `id` is always appended so ordering is total and resolution deterministic.
+
+## `freshness`
+
+```yaml
+freshness:
+  default_ttl: 30d
+  stale_is_error: false
+  exclude_expired: true
+```
+
+Durations use fixed unit lengths — `y` = 365d, `w` = 7d, `d` = 24h — so "stale after 30d" means the same number of milliseconds in every timezone. Calendar-aware arithmetic would make resolution non-deterministic.
+
+Stale context still resolves and is reported. `stale_is_error` makes `--strict` fail on it.
+
+## `provenance`
+
+```yaml
+provenance:
+  required: true
+  digest: sha256
+  require_digest: false
+```
+
+When `required`, every resolved object must declare a source or `canonical_source: true`. The check runs against what the *author* wrote, not against the `file://` source the loader attaches — otherwise it would always pass.
+
+## `audit`
+
+```yaml
+audit:
+  context_reads: true
+  context_writes: true
+  decisions: true
+  conflicts: false
+  sink: file://./context/.audit/events.ndjson
+```
+
+The specification defines the event shape and leaves storage open. The reference implementation writes `file://` sinks; anything else is returned for the caller to ship.
+
+## `redact` — repository-wide
+
+```yaml
+redact:
+  - path: payment.card
+    mode: mask
+    replacement: "[REDACTED]"
+    reason: PAN is never needed to answer a question about an account
+```
+
+Applied above every role, including roles that could otherwise read the field. Stating it once here beats repeating it per role.
+
+## `review`
+
+```yaml
+review:
+  interval: 180d
+  required_approvers: 2
+  next_review: 2027-02-09
+```
+
+Default cadence for objects that declare none. Overdue reviews are reported by `doctor`.
+
+## `adapters`
+
+```yaml
+adapters:
+  https:
+    enabled: true
+    trust: untrusted
+    timeout_ms: 5000
+  http:
+    allow_insecure: false
+  git:
+    repos:
+      github.com/acme/context: ../acme-context
+```
+
+Configuration per URI scheme. A configured `trust` is a deliberate operator statement and overrides the adapter's own assertion — but only here, never by the content itself. See [adapters](./adapters.md).
+
+## `defaults`
+
+```yaml
+defaults:
+  classification: internal
+  trust: trusted
+  owner: platform
+  ttl: 365d
+```
+
+Applied to objects that omit a field. Defaults describe house style; they never launder authority. An object with no declared authority is `reference` — useful but not binding — because defaulting unlabelled context to `canonical` would let an unreviewed note outrank a reviewed policy simply by existing.
+
+## `health`
+
+```yaml
+health:
+  minimum_score: 90
+  fail_on: error
+  require_owner: true
+  weights:
+    stale: 0.2
+```
+
+Configures `doctor`. See [lifecycle](./lifecycle.md#health-score) for the formula.
+
+## `related`
+
+```yaml
+related:
+  prd: ./openprd.yaml
+  topology: ./opentopology.yaml
+  ontology: ./openontology.yaml
+```
+
+Optional links to sibling LogicSRC specifications. OpenContext is independently usable without them.
+
+## `extensions`
+
+```yaml
+extensions:
+  com.acme.region:
+    primary: eu-west-1
+```
+
+Keys must be reverse-DNS namespaced so independent tools never collide. Unknown extensions are preserved and do not invalidate the document unless `--strict` requires known ones.
+
+## Full example
+
+```yaml
+opencontext: "1.0"
+id: acme
+name: ACME Corporation
+
+context:
+  mission: ./context/mission.md
+  organization: ./context/organization.md
+  glossary: ./context/glossary.md
+
+collections:
+  products: ./context/products/**
+  policies: ./context/policies/**
+  procedures: ./context/sops/**
+  decisions: ./context/decisions/**
+
+roles:
+  support:
+    include: [mission, products.*, policies.support.*, procedures.support.*]
+    exclude: [finance.payroll.*, legal.privileged.*]
+    permissions: [customer.read, ticket.read, ticket.write]
+
+authority:
+  precedence: [canonical, approved, reference, observed, inferred, historical]
+
+freshness:
+  default_ttl: 30d
+
+provenance:
+  required: true
+
+audit:
+  context_reads: true
+  context_writes: true
+  decisions: true
+```