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>

examples/opencontext/engineering-team/README.md

@@ -0,0 +1,20 @@
+# Engineering team
+
+Architecture knowledge, engineering policy, an incident runbook, and ADR-style
+decisions — including a superseded one.
+
+```bash
+opencontext validate --strict
+opencontext resolve --agent dev-agent --task "add a column to the accounts table" --explain
+opencontext history decisions.2026-08-01-postgres-ha
+opencontext graph --format dot > context.dot
+```
+
+The two decisions show supersession working: the February decision is retained
+with `authority: historical` and `superseded_by`, and the August one supersedes
+it. Default resolution returns only the current one; `--include-historical`
+returns both, which is how you reconstruct what the team believed in March.
+
+`oncall-agent` inherits everything `dev-agent` has and adds
+`deploy.production`. Inheritance unions scope and can only ever narrow the
+classification ceiling — it cannot widen access.

examples/opencontext/engineering-team/context/decisions/2026-02-01-postgres.md

@@ -0,0 +1,23 @@
+---
+id: decisions.2026-02-01-postgres
+type: decision
+layer: L5
+title: Use Postgres for Core
+authority: historical
+owner: cto
+status: superseded
+version: 1
+durability: permanent
+classification: internal
+canonical_source: true
+created: 2026-02-01T00:00:00Z
+updated: 2026-02-01T00:00:00Z
+decision: Core stores transactional data in a single Postgres instance.
+rationale:
+  - One writable store keeps the consistency story simple.
+superseded_by: decisions.2026-08-01-postgres-ha
+tags: [datastore]
+---
+
+Kept, not deleted. Reading why a decision was originally made is most of the
+value of having reversed it.

examples/opencontext/engineering-team/context/decisions/2026-08-01-postgres-ha.md

@@ -0,0 +1,34 @@
+---
+id: decisions.2026-08-01-postgres-ha
+type: decision
+layer: L5
+title: Move Core to replicated Postgres
+authority: approved
+owner: cto
+status: accepted
+version: 2
+durability: permanent
+classification: internal
+canonical_source: true
+created: 2026-08-01T00:00:00Z
+updated: 2026-08-01T00:00:00Z
+decision: Run Core on a primary with a synchronous replica and automated failover.
+rationale:
+  - A single instance made every maintenance window a customer-visible outage.
+  - Read traffic had outgrown one node.
+alternatives:
+  - option: Shard by tenant
+    rejected_because: Complexity we cannot staff, for a load we do not have yet.
+consequences:
+  - Writes get slower by the replication round trip. Accepted.
+approved_by:
+  - role: cto
+    at: 2026-08-01T00:00:00Z
+supersedes:
+  - decisions.2026-02-01-postgres
+references: [knowledge.architecture]
+tags: [datastore]
+---
+
+Supersedes the original single-instance decision. Both stay in the
+repository; only this one resolves by default.

examples/opencontext/engineering-team/context/glossary.md

@@ -0,0 +1,16 @@
+---
+id: glossary
+type: glossary
+layer: L1
+title: System terminology
+authority: canonical
+owner: cto
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+---
+
+- **Edge** — the request-routing tier. Stateless.
+- **Core** — the transactional service. Owns the database.
+- **Ledger** — append-only financial record. Never updated in place.

examples/opencontext/engineering-team/context/knowledge/architecture.md

@@ -0,0 +1,21 @@
+---
+id: knowledge.architecture
+type: knowledge
+layer: L2
+title: System architecture
+authority: canonical
+owner: platform
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [glossary]
+tags: [architecture]
+---
+
+Edge terminates TLS and routes to Core. Core owns the only writable
+database. Ledger is append-only and is never written synchronously from a
+request path.
+
+The rule that matters: **nothing except Core writes to the database.** An
+agent proposing a direct write from Edge is proposing an outage.

examples/opencontext/engineering-team/context/mission.md

@@ -0,0 +1,15 @@
+---
+id: mission
+type: mission
+layer: L0
+title: What platform engineering is for
+authority: canonical
+owner: cto
+durability: permanent
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+---
+
+Make the safe thing the easy thing, so product teams ship without needing to
+understand the whole system.

examples/opencontext/engineering-team/context/policies/change-management.md

@@ -0,0 +1,27 @@
+---
+id: policies.change-management
+type: policy
+layer: L3
+title: Change management
+authority: canonical
+owner: cto
+status: approved
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [knowledge.architecture]
+tags: [process]
+approval:
+  required: true
+  roles: [cto]
+  minimum: 1
+  approved_by:
+    - role: cto
+      at: 2026-08-01T00:00:00Z
+---
+
+Every production change needs a reviewed pull request and a rollback plan.
+
+Schema migrations are additive first: add the column, backfill, switch
+reads, then drop. Never drop and add in one release.

examples/opencontext/engineering-team/context/sops/incident.md

@@ -0,0 +1,20 @@
+---
+id: procedures.incident
+type: procedure
+layer: L4
+title: Incident response
+authority: approved
+owner: platform
+status: approved
+durability: operational
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [knowledge.architecture, policies.change-management]
+applies_to: [oncall]
+---
+
+1. Declare the incident before investigating. A silent incident is a longer one.
+2. Stabilise first, diagnose second. Roll back rather than roll forward.
+3. Record what you did as you do it — the timeline is the postmortem.
+4. Write the decision record before closing the incident.

examples/opencontext/engineering-team/opencontext.yaml

@@ -0,0 +1,49 @@
+# Architecture knowledge, engineering policy, runbooks, and ADR-style
+# decisions — including a superseded decision, so history is visible.
+opencontext: "1.0"
+id: platform
+name: Platform Engineering
+
+context:
+  mission: ./context/mission.md
+  glossary: ./context/glossary.md
+
+collections:
+  knowledge: ./context/knowledge/**
+  policies: ./context/policies/**
+  procedures: ./context/sops/**
+  decisions: ./context/decisions/**
+
+roles:
+  engineering:
+    include:
+      - mission
+      - glossary
+      - knowledge.*
+      - policies.*
+      - procedures.*
+      - decisions.*
+    permissions:
+      - repo.write
+      - deploy.staging
+  oncall:
+    inherits: [engineering]
+    include:
+      - procedures.incident
+    permissions:
+      - deploy.production
+
+agents:
+  dev-agent:
+    roles: [engineering]
+  oncall-agent:
+    roles: [oncall]
+
+freshness:
+  default_ttl: 365d
+
+provenance:
+  required: true
+
+health:
+  require_owner: true