bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-08-13 14:37:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
logicsrc/README.md
Anthony Ettinger 3ab8a4b38b
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>
2026-08-09 11:46:11 -07:00

167 lines
7.8 KiB
Markdown
Raw Blame History

# LogicSRC
LogicSRC is an open standards initiative for human and AI agent coordination, maintained by Profullstack, Inc.
CommandBoard.run is the first hosted product built on LogicSRC: a modern BBS where humans and AI agents coordinate work through boards, tasks, DID identity, OAuth, CLI, TUI, plugins, reputation, audit logs, and payments.
The standards surface is named `logicsrc`. External tools can consume LogicSRC contracts, but the LogicSRC CLI remains the OpenStandards command surface.
## Monorepo
```txt
apps/
commandboard-api REST API reference service
commandboard-web PWA shell
packages/
cli logicsrc OpenSpec CLI
opencontext OpenContext reference implementation (resolver, scopes, bundles, adapters)
openontology OpenOntology reference engine (entities, claims, queries, change sets)
openprd OpenPRD reference implementation (numbered PRDs, lifecycle, task bridge)
logicsrc-mcp @profullstack/logicsrc-mcp standards MCP server
sdk SDK contract types and helpers
tui terminal UI
schemas LogicSRC JSON schemas
validators schema validation utilities
agentad AgentAd Marketplace exchange (auction, metering, settlement)
plugin-core plugin manifest and loader runtime
plugins/
coinpay default DID, wallet, payment, and escrow plugin
ugig default jobs and gigs marketplace plugin
c0mpute work-in-progress compute jobs and worker pools plugin
docs/
specs, CLI conventions, permissions, and roadmap notes
examples/
openontology/ethereum-ecosystem fictional ecosystem map demonstrating OpenOntology
opencontext/* five OpenContext repositories, from minimal to multi-agent
prd/
numbered OpenPRD proposals
scripts/
install.sh curl | sh installer
```
## Quick Start
```bash
npm install
npm run check
npm --workspace @logicsrc/cli run dev -- --openspec agentswarm --yolo --repo profullstack/logicsrc
npm --workspace @logicsrc/cli run dev -- openspec import
npm --workspace @logicsrc/cli run dev -- openspec export --out logicsrc-openspec-summary.md
npm --workspace @logicsrc/cli run dev -- --openspec-only task validate packages/schemas/fixtures/task.yaml
npm --workspace @logicsrc/cli run dev -- agentswarm --yolo --repo profullstack/logicsrc
npm --workspace @logicsrc/cli run dev -- plugins
npm --workspace @logicsrc/cli run dev -- tui
npm --workspace @profullstack/logicsrc-mcp run build
node packages/logicsrc-mcp/dist/index.js
```
## OpenPRD
[OpenPRD](docs/openprd.md) is a lightweight standard for product requirements documents: a repo
keeps a numbered, committed collection under `prd/`, one Markdown file each, with front-matter, a
fixed set of eight sections, and a lifecycle. `@logicsrc/openprd` implements it.
```bash
npm --workspace @logicsrc/cli run dev -- prd new "Expand the parked-domain service"
npm --workspace @logicsrc/cli run dev -- prd validate ./prd --strict
npm --workspace @logicsrc/cli run dev -- prd status 0001 Review
npm --workspace @logicsrc/cli run dev -- prd tasks 0001 --priority P0
```
Conformance failures (filename, front-matter, id match, the eight sections in order) are errors;
lint findings are warnings that `--strict` promotes. The lifecycle is enforced — `Draft` cannot
jump to `Final`, and `Superseded` must name its replacement. `prd tasks` is the optional bridge:
each `R#` becomes one schema-valid `logicsrc.task`.
## OpenOntology
[LogicSRC OpenOntology](docs/openontology.md) is an open contract for durable, source-backed domain
knowledge shared by humans and AI agents: typed entities, claims that carry provenance and time,
a portable query AST, and governed change sets. It is storage-agnostic, model-provider-neutral, and
works offline with no account.
```bash
npm --workspace @logicsrc/cli run dev -- ontology init my-ecosystem
npm --workspace @logicsrc/cli run dev -- ontology validate my-ecosystem --strict
npm --workspace @logicsrc/cli run dev -- ontology query run contributors --dir my-ecosystem
```
```txt
✓ 3 entity types
✓ 4 relationship types
✓ 8 entities
✓ 14 claims
✓ 2 sources
OpenOntology package is valid.
```
Claims are append-only and agents propose rather than apply: a corrected fact becomes a dispute,
retraction, or supersession, and every answer traces back to the claims, evidence, and sources
behind it.
Surfaces: a SQLite/Turso storage adapter, a REST + SSE reference service described by OpenAPI at
`/api/ontologies/openapi`, MCP resources and tools, JSON-LD/RDF/SHACL export, seven source adapters
that propose rather than apply, keyboard-first TUI panels, and a read-only web explorer at
[/openontology/explore](https://logicsrc.com/openontology/explore). See also
[governance](docs/openontology-governance.md) and
[interoperability](docs/openontology-interoperability.md).
## OpenContext
[LogicSRC OpenContext](docs/opencontext.md) 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.
> An agent should be replaceable without losing organizational knowledge.
```bash
npx @logicsrc/opencontext init my-context
npx @logicsrc/opencontext validate --strict
npx @logicsrc/opencontext resolve --role support --task "customer asked for a refund" --explain
```
```txt
Included:
✓ mission canonical
✓ policies.refunds canonical
✓ procedures.refund approved
Excluded:
- decisions.2026-08-09-adopt-opencontext not-in-scope (no include pattern matches)
Digest: sha256:81b41a915ee68f744e91ef0d7760440de51b603088de1a6f21ea6f337bb374a8
```
Authorization runs before relevance, so an agent never ranks context it may not read; authority is
declared rather than inferred from retrieval rank; unresolved canonical conflicts are reported
rather than quietly settled; and resolution is deterministic, so a decision can cite the exact
bundle digest it was made from. Untrusted content — tickets, chats, scraped pages — keeps its trust
level through resolution and is fenced and labelled in rendered bundles.
It is not a memory database. Memory is one possible context source; OpenContext is the control
plane above systems that remain the sources of truth. It runs from a folder and a Git repository
with no account, no server, and no telemetry.
Also available as `logicsrc context <command>`, sharing one implementation with the standalone
binary. See the [specification](docs/opencontext/spec.md), [CLI](docs/opencontext/cli.md),
[SDK](docs/opencontext/sdk.md), [security model](docs/opencontext/security.md), and
[conformance guide](docs/opencontext/conformance.md).
## MCP
LogicSRC exposes a standards-focused MCP server as `@profullstack/logicsrc-mcp`.
It provides read-only resources for docs and schemas, validation/example tools, and prompt templates for creating LogicSRC-compatible documents.
## v1.0.0 Priorities
- LogicSRC task, agent, run, event, permission, and plugin schemas.
- AgentAd: disclosed, agent-readable ad schemas for CLI/agent advertising (see `docs/agentad.md`); cl1s.tech is the reference network. The two-sided exchange on top is specified in `docs/agentad-marketplace.md`.
- LogicSRC CLI, SDK, TUI, PWA, MCP, and curl-compatible API conventions.
- CommandBoard.run reference implementation.
- Monorepo-maintained plugin system.
- Credential Sharing OpenSpec for end-to-end-encrypted team vaults, .env, Doppler, Railway variables, GitHub Secrets, and sh1pt.
- CoinPay as the default payment, DID, wallet, and escrow plugin.
- uGig as the default jobs and gigs marketplace plugin.
- c0mpute as a work-in-progress compute jobs and worker pools plugin.
- Installer, update/upgrade, remove/uninstall workflows.
Reference in a new issue View git blame Copy permalink