bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-10-01 12:23:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
logicsrc/README.md
Anthony Ettinger 9ae7ad8962
OpenFleet reference implementation: @logicsrc/openfleet, logicsrc fleet, and Claude Code hooks (#185) 
* OpenFleet reference implementation: @logicsrc/openfleet 0.1.0 and logicsrc fleet

Ship what docs/openfleet.md describes. The new workspace package holds the
record (write once, never overwrite, 0600), the ledger (append-only JSON
Lines, merged across ledger*.jsonl by at), the ceiling rules (whole fleet
ceiling, narrowed swarm keys, a merge that never widens, refusals by key),
claiming and deriving exactly as the spec's "Claiming and deriving" and
rule 13, and fold(), which turns any $OPENFLEET_HOME plus the engine
rosters into the tree the landing page shows.

logicsrc fleet open|cap|tree|stop|log are the sysop's verbs, every one with
--json. open and cap exit 4 when OPENFLEET_MEMBER is set; stop exits 4
outside the caller's subtree, ends nested swarms first, goes through each
member's own engine (claude stop, moshcode herd kill, tmux kill-pane, a
signal for claude-p) and writes one swarm.end per swarm. tree reads claude
agents --json --all and ~/.moshcode/herd/sessions.json when it can, draws
recordless sessions as roster roots of the implicit fleet, and writes
member.end lost for a recorded member its engine no longer lists.

Claude Code takes part through hooks: logicsrc fleet hooks install merges
SessionStart, UserPromptSubmit, PreToolUse, Stop and SessionEnd into
~/.claude/settings.json without clobbering it, and logicsrc fleet hook
<Event> runs each one. SessionStart claims, derives or writes a root record
and hands the member its variables through CLAUDE_ENV_FILE; UserPromptSubmit
checks the ceiling with the permission mode the engine reports and writes
member.start, or refuses the first prompt with exit 2 and ceiling.refuse;
PreToolUse denies an edit outside piece.owns; Stop and SessionEnd write
member.end. A hand-started root takes the engine's reported approvals
before member.start, since the command line only guesses them. Hooks
never fail the engine: everything is caught and logged to hooks.log.

The spec and the landing page now say what ships, keep Status 0.1, and
record the two verified Claude Code limits: a background job dispatched from
claude agents gets no launcher environment, and OPENFLEET_* exported at
SessionStart reach the member's tools but not later hooks, so hooks key on
session_id through $OPENFLEET_HOME/sessions/<session_id>.json. PRD 0008
covers the work. CLI 0.2.1 -> 0.3.0; build and build:cli chains build the
package before the CLI; README and docs/cli.md list the group.

Tests: 95 in the package (record, ledger merge, every narrower case, the
worked example's claim and derive, the folded tree, hook install
idempotence, each hook handler including the exit-2 refusal and the
PreToolUse deny, every verb with fake deps) and 4 in the CLI.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

* OpenFleet fix round: rebuild the ceiling from the ledger, once-markers, rule 6 in tree, lost only for what a roster can hold

The review of the reference implementation against moshcode found the two
readers disagreeing on the same files. This round applies the shared
rulings so both sides read a ledger the same way.

Ceiling (R-A, R-B, R-C, R1, R6, R10, R15, R17): memberCeiling rebuilds the
effective ceiling from the ledger on every read. The latest fleet-target
fleet.cap (else fleet.open, else the implicit fleet's) replaces the copy in
a record, so a sysop's widening cap reaches running members; then each
swarm.spawn narrowing down the path, then swarm caps last. In the implicit
fleet a parentless record's own approvals enters at the root; a ceiling a
writer left without the key is never read as native, and startMember fills
it with the engine's word while the record is unclaimed. A fleet.open or
cap with no hosts means the host it was written on (R23).

Once-markers (R-G, R28): member.start, member.end and swarm.end each take
an exclusive create under fleets/<fleet>/marks/<event>.<id> before the
append; a lost end takes <id>.lost so a real end can still supersede it.
The hooks let a real end follow a lost line (R9).

tree (R-F, R20): run by the sysop it enforces rule 6, stopping a member
past its effective until with state timeout and the members of a swarm or
fleet at its budget with state budget, then writes swarm.end for each swarm
touched once it is complete. An agent's tree stops nothing. lost is written
only for a member its engine's roster can hold: a claude-code background job
(8-hex member or session) or a moshcode pane, never an interactive session
claude agents does not list (R-E, R3, R14). A nested swarm is drawn under
the member that spawned it and its row shows the effective ceiling (R25).

stop and cap (R-D, R-H, R22, R27): swarm.end is written only once every
member and every nested swarm has an end line that counts; an engine that
will not end a member leaves it without an end line and the verb exits
non-zero. claude stop takes the job id: the member of a background job,
else the first eight characters of a session UUID; an interactive session
with no job id cannot be stopped and the tool says so. cap on a swarm
refuses a key that would widen. A derived claude-code job is named by its
job id and carries no pid.

Also: R-I (endMember ends only the engine-minted swarm of one), R35 (a
derived record's guessed approvals corrected at UserPromptSubmit), R32
(the UserPromptSubmit hook passes only exit 2 through), R31 (package
README), R36 (rule 13 says the launcher test is unimplemented in 0.1),
docs and PRD 0008 updated for lost, rule 6 and the markers. 113 openfleet
tests, 93 CLI tests, contract green.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

* openfleet hooks: no member.end for a member that never started

A first prompt refused by the ceiling still lets the session wind down through Stop and SessionEnd; those handlers now write nothing when the ledger holds no member.start for the member, so a refused member is never drawn as done.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

* logicsrc-mcp test: the next free PRD id is 0009 now that PRD 0008 exists

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01RZV4zJ2pDZLNN3kE5jFCmV

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-13 10:58:55 +00:00

202 lines
10 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)
openfleet OpenFleet reference implementation (record, ledger, sysop verbs, Claude Code hooks)
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
```
## OpenWall proposal
[OpenWall](docs/openwall.md) proposes broadcasts to explicitly selected connections, followers,
following, or service users, plus direct messages through verified contact routes. The draft
defines recipient consent, private delivery outcomes, and a public/private AT Protocol mapping.
Message and receipt JSON Schemas and fixtures are included; delivery services and the proposed
`logicsrc wall` commands are not implemented.
## 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).
## One command for every LogicSRC tool
`logicsrc` is the umbrella: every LogicSRC standard that has a CLI is a word after it, and the word runs the same code as the standalone command, so the two cannot drift.
```bash
logicsrc vault … # OpenCreds (also `opencreds`)
logicsrc prd … # OpenPRD
logicsrc ontology … # OpenOntology
logicsrc context … # OpenContext (also `opencontext`)
logicsrc fleet … # OpenFleet: open, cap, tree, stop, log, hooks install
logicsrc openmcp … # OpenMCP: relays, find, call, add, probe, serve (also `openmcp`)
logicsrc openspec … # import, export, change; any other word is OpenSpec.dev's own CLI (init, list, validate, archive, show)
logicsrc mcp # the LogicSRC MCP server over stdio (also `logicsrc-mcp`)
```
`openmcp` is the one that lives in its own repository ([logicsrc/openmcp](https://github.com/logicsrc/openmcp)); it is a dependency here and its `main` is called with your arguments untouched. It needs Node 24 (`node:sqlite`); on an older Node that one word says so and the rest of the CLI keeps working. The standalone install, which brings its own Node 24, is `curl -fsSL https://openmcp.logicsrc.com/install.sh | sh`.
## MCP
LogicSRC exposes a standards-focused MCP server as `@profullstack/logicsrc-mcp`, and `logicsrc mcp` runs it.
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, sh1pt, and `~/.ssh` keys.
- 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.
## OpenABTest draft
[OpenABTest](docs/openabtest.md) defines reusable experiment manifests and private
eligibility, assignment, exposure, conversion and accounting events. The Chovy
example compares 5%, 10% and 20% discounts on every referred purchase, with
sticky customer assignment and affiliate payout withheld until actual costs
and fees are reconciled. Schemas, validators and SDK constructors ship in 0.3.0;
assignment, analytics and payment runtimes remain the integrating service's job.
Reference in a new issue View git blame Copy permalink