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/multi-agent-company/README.md

@@ -0,0 +1,50 @@
+# Multi-agent company
+
+One shared context repository. Five agents. Five different bundles.
+
+```bash
+opencontext validate --strict
+opencontext doctor
+
+for agent in sales-agent support-agent dev-agent finance-agent ops-agent; do
+  echo "== $agent"
+  opencontext resolve --agent "$agent" --explain
+done
+```
+
+## What each agent gets
+
+| Agent | Sees | Never sees |
+| --- | --- | --- |
+| `sales-agent` | products, customers, pricing, quoting SOP | churn risk, payroll, architecture |
+| `support-agent` | products, customers, refunds, refund SOP | pricing, payroll, architecture |
+| `dev-agent` | architecture, change management, decisions | customers, pricing, payroll |
+| `finance-agent` | every policy including payroll, customers | architecture, runbooks, card numbers |
+| `ops-agent` | procedures, runbooks, change management | customers, pricing, payroll |
+
+## Three mechanisms doing the work
+
+**Scope.** Each role includes only what it needs. `sales` additionally excludes
+`customers.*.churn-risk`, so an inferred model score cannot leak into a customer
+conversation even though `customers.*` matches it.
+
+**Classification.** `policies.payroll` is `confidential`. Only `finance`
+declares `max_classification: confidential`; every other role falls back to
+`internal` and is refused. A role's own declaration wins over the one it
+inherits, so a ceiling on a shared base role cannot silently cap a role that was
+deliberately granted more — while requesting several roles at once still takes
+the lowest of them, so combining roles never escalates.
+
+**Redaction.** The manifest redacts `payment.card` repository-wide, so no role —
+including `finance` — ever receives a card number, even from a record it is
+fully entitled to read.
+
+**Object permissions.** `policies.payroll` also carries
+`permissions.read: [finance]`, so it is refused even to a role whose include
+pattern matches it. Deny overrides allow, at every level.
+
+## The point
+
+Replace `support-agent` with a different model tomorrow. Run the same command.
+The bundle is identical, and its digest proves it. The agent was replaceable;
+the context was not.

examples/opencontext/multi-agent-company/context/customers/acme.json

@@ -0,0 +1,31 @@
+{
+  "id": "customers.acme",
+  "type": "customer",
+  "layer": "L2",
+  "title": "ACME Manufacturing",
+  "authority": "reference",
+  "owner": "sales",
+  "durability": "operational",
+  "classification": "internal",
+  "canonical_source": true,
+  "updated": "2026-08-01T00:00:00Z",
+  "tags": [
+    "customer"
+  ],
+  "content": {
+    "name": "ACME Manufacturing",
+    "plan": "enterprise",
+    "lanes": 34,
+    "payment": {
+      "card": "4111111111111111",
+      "terms": "net-30"
+    },
+    "contacts": [
+      {
+        "name": "Dana Okafor",
+        "role": "ops",
+        "email": "dana@acme.example"
+      }
+    ]
+  }
+}

examples/opencontext/multi-agent-company/context/customers/acme/churn-risk.md

@@ -0,0 +1,20 @@
+---
+id: customers.acme.churn-risk
+type: knowledge
+layer: L2
+title: ACME churn risk
+authority: inferred
+owner: finance
+confidence: 0.6
+durability: operational
+classification: confidential
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+tags: [churn, internal]
+---
+
+Model scores ACME at elevated churn risk after two late renewals.
+
+`authority: inferred` and `confidence: 0.6` — this is a model's opinion, not
+a fact, and it never outranks anything canonical. It is excluded from the
+sales scope outright so it cannot leak into a customer conversation.

examples/opencontext/multi-agent-company/context/decisions/2026-08-01-agent-roles.md

@@ -0,0 +1,31 @@
+---
+id: decisions.2026-08-01-agent-roles
+type: decision
+layer: L5
+title: Give every agent a role, never a bespoke prompt
+authority: approved
+owner: founders
+status: accepted
+durability: permanent
+classification: internal
+canonical_source: true
+created: 2026-08-01T00:00:00Z
+updated: 2026-08-01T00:00:00Z
+decision: Every agent is onboarded by assigning it a role in opencontext.yaml.
+rationale:
+  - A bespoke prompt per agent is context that only exists inside that agent.
+  - Roles make offboarding a one-line revocation instead of an investigation.
+  - Two agents in the same role provably receive the same context.
+alternatives:
+  - option: Hand-written system prompts per agent
+    rejected_because: The organization's knowledge ends up inside vendors we do not control.
+consequences:
+  - Adding an agent means editing the manifest, which is reviewed like code.
+approved_by:
+  - role: founders
+    at: 2026-08-01T00:00:00Z
+references: [organization]
+tags: [governance, agents]
+---
+
+This is the decision that makes the rest of the repository worth maintaining.

examples/opencontext/multi-agent-company/context/glossary.md

@@ -0,0 +1,16 @@
+---
+id: glossary
+type: glossary
+layer: L1
+title: Terminology
+authority: canonical
+owner: founders
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+---
+
+- **Lane** — an origin/destination pair we quote and track on.
+- **Tender** — an offer of a shipment to a carrier.
+- **Churn risk** — an internal score. Never shown or hinted to a customer.

examples/opencontext/multi-agent-company/context/knowledge/architecture.md

@@ -0,0 +1,18 @@
+---
+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
+tags: [architecture]
+---
+
+Ingest normalises carrier feeds. Core holds shipment state. Alerts is a
+stateless evaluator over Core.
+
+Only Core writes to the database.

examples/opencontext/multi-agent-company/context/knowledge/runbooks.md

@@ -0,0 +1,17 @@
+---
+id: knowledge.runbooks
+type: knowledge
+layer: L2
+title: Runbook index
+authority: approved
+owner: operations
+durability: operational
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [procedures.deploy]
+tags: [runbook]
+---
+
+- Carrier feed stalled → replay from the last checkpoint.
+- Alert storm → damp the evaluator before touching Core.

examples/opencontext/multi-agent-company/context/mission.md

@@ -0,0 +1,15 @@
+---
+id: mission
+type: mission
+layer: L0
+title: Why Meridian exists
+authority: canonical
+owner: founders
+durability: permanent
+classification: public
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+---
+
+Give mid-sized manufacturers the supply-chain visibility that used to require
+an enterprise contract and a consulting engagement.

examples/opencontext/multi-agent-company/context/organization.md

@@ -0,0 +1,20 @@
+---
+id: organization
+type: identity
+layer: L1
+title: How Meridian is organized
+authority: canonical
+owner: founders
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+---
+
+Five functions, each with a human lead and at least one agent:
+sales, support, engineering, finance, and operations.
+
+Agents are execution capacity. They are onboarded by being pointed at this
+repository, and offboarded by revoking a role. Nothing they learned in the
+course of working leaves with them, because anything worth keeping was
+written here.

examples/opencontext/multi-agent-company/context/policies/change-management.md

@@ -0,0 +1,18 @@
+---
+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
+tags: [process]
+applies_to: [engineering, operations]
+---
+
+Production changes need a reviewed pull request and a rollback plan.
+Migrations are additive first.

examples/opencontext/multi-agent-company/context/policies/payroll.md

@@ -0,0 +1,21 @@
+---
+id: policies.payroll
+type: policy
+layer: L3
+title: Payroll
+authority: canonical
+owner: finance
+status: approved
+durability: long-lived
+classification: confidential
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+permissions:
+  read: [finance]
+tags: [finance]
+---
+
+Payroll runs on the 25th.
+
+Confidential, and additionally restricted with an object-level read grant —
+so even a role whose include pattern matches `policies.*` is refused.

examples/opencontext/multi-agent-company/context/policies/pricing.md

@@ -0,0 +1,19 @@
+---
+id: policies.pricing
+type: policy
+layer: L3
+title: Pricing
+authority: canonical
+owner: finance
+status: approved
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+tags: [pricing]
+applies_to: [sales, finance]
+---
+
+Visibility starts at $2,500/month for 25 lanes; additional lanes are $95 each.
+
+Discounts above 15% require finance approval.

examples/opencontext/multi-agent-company/context/policies/refunds.md

@@ -0,0 +1,18 @@
+---
+id: policies.refunds
+type: policy
+layer: L3
+title: Refund policy
+authority: canonical
+owner: support
+status: approved
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+tags: [refunds]
+applies_to: [support]
+---
+
+Refunds are accepted within 30 days. Enterprise accounts on net-30 terms are
+credited against the next invoice rather than refunded.

examples/opencontext/multi-agent-company/context/products/visibility.md

@@ -0,0 +1,19 @@
+---
+id: products.visibility
+type: product
+layer: L2
+title: Meridian Visibility
+authority: canonical
+owner: product
+durability: long-lived
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+tags: [product]
+---
+
+Tracks shipments across carriers and raises an alert when one will miss its
+window.
+
+It does not book freight and does not clear customs. Decline both rather
+than improvising an answer.

examples/opencontext/multi-agent-company/context/sops/deploy.md

@@ -0,0 +1,19 @@
+---
+id: procedures.deploy
+type: procedure
+layer: L4
+title: How to deploy
+authority: approved
+owner: operations
+status: approved
+durability: operational
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [policies.change-management]
+applies_to: [operations]
+---
+
+1. Confirm the rollback plan exists before starting.
+2. Deploy to one region, watch error rates for ten minutes, then continue.
+3. Roll back rather than roll forward.

examples/opencontext/multi-agent-company/context/sops/quote.md

@@ -0,0 +1,19 @@
+---
+id: procedures.quote
+type: procedure
+layer: L4
+title: How to produce a quote
+authority: approved
+owner: sales
+status: approved
+durability: operational
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [policies.pricing, products.visibility]
+applies_to: [sales]
+---
+
+1. Confirm lane count and contract length.
+2. Apply list pricing.
+3. Above 15% off, stop and escalate to finance.

examples/opencontext/multi-agent-company/context/sops/refund.md

@@ -0,0 +1,19 @@
+---
+id: procedures.refund
+type: procedure
+layer: L4
+title: How to process a refund
+authority: approved
+owner: support
+status: approved
+durability: operational
+classification: internal
+canonical_source: true
+updated: 2026-08-01T00:00:00Z
+references: [policies.refunds]
+applies_to: [support]
+---
+
+1. Check the purchase date against the refund policy.
+2. Enterprise accounts are credited, not refunded.
+3. Outside the window, escalate.

examples/opencontext/multi-agent-company/opencontext.yaml

@@ -0,0 +1,136 @@
+# One shared context repository, five agents, five different bundles.
+#
+# This is the whole thesis in one file: the organization's knowledge lives
+# here, and the agents are interchangeable readers of it. Replace any of
+# them tomorrow and nothing below changes.
+opencontext: "1.0"
+id: meridian
+name: Meridian
+
+context:
+  mission: ./context/mission.md
+  organization: ./context/organization.md
+  glossary: ./context/glossary.md
+
+collections:
+  products: ./context/products/**
+  customers: ./context/customers/**
+  policies: ./context/policies/**
+  procedures: ./context/sops/**
+  decisions: ./context/decisions/**
+  knowledge: ./context/knowledge/**
+
+roles:
+  # Everything every worker needs, human or agent. Everyone inherits it.
+  everyone:
+    description: Shared identity and terminology.
+    include:
+      - mission
+      - organization
+      - glossary
+    max_classification: internal
+
+  sales:
+    inherits: [everyone]
+    include:
+      - products.*
+      - customers.*
+      - policies.pricing
+      - procedures.quote
+    exclude:
+      - customers.*.churn-risk
+    permissions:
+      - quote.create
+      - customer.read
+    redact:
+      - path: payment.card
+        mode: mask
+
+  support:
+    inherits: [everyone]
+    include:
+      - products.*
+      - customers.*
+      - policies.refunds
+      - procedures.refund
+    permissions:
+      - ticket.write
+      - customer.read
+    redact:
+      - path: payment.card
+        mode: mask
+      - path: contacts[*].email
+        mode: hash
+
+  engineering:
+    inherits: [everyone]
+    include:
+      - products.*
+      - knowledge.*
+      - policies.change-management
+      - decisions.*
+    permissions:
+      - repo.write
+
+  finance:
+    inherits: [everyone]
+    include:
+      - policies.*
+      - customers.*
+    permissions:
+      - invoice.write
+    max_classification: confidential
+
+  operations:
+    inherits: [everyone]
+    include:
+      - procedures.*
+      - knowledge.runbooks
+      - policies.change-management
+    permissions:
+      - deploy.production
+
+agents:
+  sales-agent:
+    roles: [sales]
+  support-agent:
+    roles: [support]
+  dev-agent:
+    roles: [engineering]
+  finance-agent:
+    roles: [finance]
+  ops-agent:
+    roles: [operations]
+
+# Repository-wide redaction, applied to every role including finance.
+# A raw card number has no business in a context bundle at all, so this is
+# stated once here rather than repeated in each role that might read it.
+redact:
+  - path: payment.card
+    mode: mask
+    replacement: "[REDACTED]"
+    reason: PAN is never needed to answer a question about an account
+
+authority:
+  precedence:
+    - canonical
+    - approved
+    - reference
+    - observed
+    - inferred
+    - historical
+
+freshness:
+  default_ttl: 365d
+
+provenance:
+  required: true
+
+audit:
+  context_reads: true
+  context_writes: true
+  decisions: true
+
+health:
+  minimum_score: 90
+  require_owner: true