mirror of
https://github.com/profullstack/logicsrc.git
synced 2026-08-13 14:37:26 +00:00
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>
This commit is contained in:
GitHub
parent
1bb7ba6e60
commit
3ab8a4b38b
212 changed files with 17249 additions and 7 deletions
268
docs/opencontext/cli.md
Normal file
268
docs/opencontext/cli.md
Normal file
|
|
@ -0,0 +1,268 @@
|
|||
# CLI reference
|
||||
|
||||
```bash
|
||||
npx @logicsrc/opencontext <command> # standalone
|
||||
logicsrc context <command> # inside the LogicSRC CLI
|
||||
```
|
||||
|
||||
Both call the same implementation, so they cannot drift. The specification treats CLI behaviour — flags, output shapes, exit codes — as a conformance surface.
|
||||
|
||||
The manifest is discovered by searching upward from the working directory, so commands work from anywhere inside a project.
|
||||
|
||||
## Exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
| --- | --- |
|
||||
| `0` | ok |
|
||||
| `1` | invalid — validation failed, conflicts found, health below minimum |
|
||||
| `2` | usage — bad flag, unknown role or agent |
|
||||
| `3` | not found — no manifest, no such object |
|
||||
|
||||
## Global flags
|
||||
|
||||
```txt
|
||||
-C, --dir <path> project directory or manifest path (default: search upward)
|
||||
--format <format> table, json, yaml, markdown, ndjson
|
||||
--output <file> write to a file instead of stdout
|
||||
--offline never reach the network
|
||||
--at <timestamp> resolve as of an RFC 3339 instant or YYYY-MM-DD date
|
||||
```
|
||||
|
||||
`--at 2026-08-09` is read as the *end* of that day, so it includes everything that happened during it.
|
||||
|
||||
Human-readable output is the default; `--format json` is the automation contract. There is no telemetry, and no network call for a local-only project.
|
||||
|
||||
## `init`
|
||||
|
||||
```bash
|
||||
opencontext init [dir] [--id acme] [--name "ACME Corporation"] [--yes] [--force]
|
||||
```
|
||||
|
||||
Creates a project that passes `validate --strict` and scores 100% on `doctor` with no edits — including two roles with genuinely different scopes, so the permission model is visible from the start.
|
||||
|
||||
`--yes` takes every default, suitable for agents and scripts. Existing files are kept unless `--force`.
|
||||
|
||||
## `validate`
|
||||
|
||||
```bash
|
||||
opencontext validate [--strict]
|
||||
```
|
||||
|
||||
Checks the manifest, object schemas, ids, references, supersession chains, role graph, permissions, provenance, and secrets.
|
||||
|
||||
`--strict` additionally fails on warnings and requires namespaced extensions.
|
||||
|
||||
Errors name the file, line, field, expected value, actual value, and a remediation:
|
||||
|
||||
```txt
|
||||
✗ context/policies/refunds.md:3: policies.refunds: authority must be equal to one of the allowed values
|
||||
field: authority
|
||||
expected: ["canonical","approved","reference","observed","inferred","historical"]
|
||||
actual: gospel
|
||||
→ Use one of the listed values.
|
||||
```
|
||||
|
||||
## `doctor`
|
||||
|
||||
```bash
|
||||
opencontext doctor [--strict] [--min-score 90]
|
||||
```
|
||||
|
||||
Validation plus the questions that need a clock: what is stale, expired, overdue for review, orphaned, unowned, or broken.
|
||||
|
||||
```txt
|
||||
OpenContext Health
|
||||
────────────────────────────────
|
||||
Mission ✓ canonical
|
||||
Brand ✓ current
|
||||
Pricing ✓ current
|
||||
Engineering SOPs ⚠ stale
|
||||
|
||||
Orphaned context 7
|
||||
Conflicting context 2
|
||||
Expired context 4
|
||||
Stale context 3
|
||||
Missing owners 3
|
||||
Broken sources 1
|
||||
|
||||
Context health: 91%
|
||||
```
|
||||
|
||||
## `get`
|
||||
|
||||
```bash
|
||||
opencontext get <id> [--agent a] [--role r...]
|
||||
opencontext get policies.refunds@2
|
||||
```
|
||||
|
||||
Prints one object, subject to authorization. A denied read and a missing object are reported identically.
|
||||
|
||||
## `list`
|
||||
|
||||
```bash
|
||||
opencontext list [--agent a] [--role r...] [--type policy] [--layer L3]
|
||||
[--authority canonical] [--owner support] [--tag refunds]
|
||||
[--include-historical]
|
||||
```
|
||||
|
||||
```txt
|
||||
id type layer authority owner state
|
||||
------------------ --------- ----- --------- -------- -------
|
||||
mission mission L0 canonical founders current
|
||||
policies.refunds policy L3 canonical support current
|
||||
procedures.refund procedure L4 approved support stale
|
||||
```
|
||||
|
||||
Objects the scope cannot read never appear, not even as a row of metadata.
|
||||
|
||||
## `search`
|
||||
|
||||
```bash
|
||||
opencontext search "refund policy" [--agent a] [--role r...] [--limit 20] [--type policy]
|
||||
```
|
||||
|
||||
Lexical search over ids, titles, tags, summaries, and content. Results pass authorization **before** any content is returned.
|
||||
|
||||
## `resolve`
|
||||
|
||||
```bash
|
||||
opencontext resolve --agent support-agent --task "Customer ACME requested a refund" --explain
|
||||
opencontext resolve --role support --task "continue ticket 4821" --format markdown
|
||||
```
|
||||
|
||||
```txt
|
||||
--agent <agent> the consumer to resolve for
|
||||
--role <role...> resolve for these roles
|
||||
--task <task> drives relevance ranking
|
||||
--explain why each object was included, excluded, or outranked
|
||||
--include-historical include superseded and expired context
|
||||
--limit <n> keep the N most relevant; the rest are reported as excluded
|
||||
--min-relevance <n> drop objects scoring below this
|
||||
--include <pattern...> narrow the scope further; can never widen it
|
||||
```
|
||||
|
||||
With `--explain` and no `--format`, the human explanation is printed. Otherwise the bundle is emitted as JSON (default), YAML, or Markdown.
|
||||
|
||||
## `bundle`
|
||||
|
||||
```bash
|
||||
opencontext bundle --agent support-agent --format json --output bundle.json
|
||||
```
|
||||
|
||||
The same resolution as `resolve`, always emitting the full bundle document. Useful as a CI artifact.
|
||||
|
||||
## `conflicts`
|
||||
|
||||
```bash
|
||||
opencontext conflicts [--strict]
|
||||
```
|
||||
|
||||
Duplicate canonical objects, declared conflicts, duplicate ids, broken supersession, and multiple active versions. `--strict` exits non-zero on any finding, not only errors.
|
||||
|
||||
## `stale`
|
||||
|
||||
```bash
|
||||
opencontext stale [--strict] [--at 2026-12-01]
|
||||
```
|
||||
|
||||
Context past its freshness window, expired, not yet valid, or overdue for review.
|
||||
|
||||
## `history`
|
||||
|
||||
```bash
|
||||
opencontext history pricing.enterprise
|
||||
```
|
||||
|
||||
```txt
|
||||
History of pricing.enterprise
|
||||
|
||||
v1 superseded canonical 2026-01-01T00:00:00Z → superseded by pricing.enterprise
|
||||
v2 current canonical 2026-08-01T00:00:00Z
|
||||
|
||||
Commits:
|
||||
9f2c1ab3 2026-08-01 Dana Okafor Raise enterprise floor to $2,500
|
||||
```
|
||||
|
||||
Declared version history first — that is what the organization believed and when. Git commits follow, when git is available; without it, declared history is still shown.
|
||||
|
||||
## `diff`
|
||||
|
||||
```bash
|
||||
opencontext diff pricing.enterprise@1 pricing.enterprise@2
|
||||
```
|
||||
|
||||
```txt
|
||||
~ pricing.enterprise (changed)
|
||||
authority:
|
||||
- reference
|
||||
+ canonical
|
||||
content:
|
||||
- Enterprise plans start at $1,800/month.
|
||||
+ Enterprise plans start at $2,500/month.
|
||||
```
|
||||
|
||||
Compares the fields whose change is a governance event, not every byte.
|
||||
|
||||
## `graph`
|
||||
|
||||
```bash
|
||||
opencontext graph [--root policies.refunds] [--depth 2] [--owners] [--sources]
|
||||
opencontext graph --format dot > context.dot
|
||||
```
|
||||
|
||||
References, supersession, conflicts, dependencies, ownership, and sources. Text, JSON, and Graphviz DOT.
|
||||
|
||||
## `schema`
|
||||
|
||||
```bash
|
||||
opencontext schema # list the published schemas
|
||||
opencontext schema object # print one
|
||||
```
|
||||
|
||||
## `add` and `supersede`
|
||||
|
||||
```bash
|
||||
opencontext add policies.returns --type policy --title Returns --content "Within 14 days."
|
||||
opencontext supersede policies.refunds --content "Within 60 days." --dry-run
|
||||
```
|
||||
|
||||
```txt
|
||||
--type <type> required for add
|
||||
--title, --content, --layer, --authority, --owner
|
||||
--file <path> where to write it
|
||||
--promote permit canonical or approved authority
|
||||
--dry-run show what would be written
|
||||
```
|
||||
|
||||
Writes validate authorization and schema before touching disk. Promotion to `canonical` or `approved` requires `--promote` — it is a governance act, not a side effect of writing. Superseding leaves the previous version on disk.
|
||||
|
||||
## `version`
|
||||
|
||||
```bash
|
||||
opencontext version # the supported specification version
|
||||
```
|
||||
|
||||
## CI
|
||||
|
||||
```yaml
|
||||
- run: npx @logicsrc/opencontext validate --strict
|
||||
- run: npx @logicsrc/opencontext doctor --strict
|
||||
- run: npx @logicsrc/opencontext bundle --role support --output bundle.json
|
||||
```
|
||||
|
||||
Common gates:
|
||||
|
||||
```bash
|
||||
opencontext conflicts --strict # reject duplicate canonical policies
|
||||
opencontext stale --strict # reject expired required context
|
||||
opencontext doctor --strict --min-score 95 # enforce a health floor
|
||||
```
|
||||
|
||||
## Piping
|
||||
|
||||
Output is stdout, diagnostics are stderr, and a closed pipe (`opencontext list | head`) exits cleanly rather than printing a stack trace.
|
||||
|
||||
```bash
|
||||
opencontext list --format ndjson | jq -r 'select(.lifecycle=="stale") | .id'
|
||||
opencontext bundle --role support | jq '.digest'
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue