docs(specs): ok-shell-job-runner spec + knowledge-lint research thread#352
Open
tim-inkeep wants to merge 1 commit intomainfrom
Open
docs(specs): ok-shell-job-runner spec + knowledge-lint research thread#352tim-inkeep wants to merge 1 commit intomainfrom
tim-inkeep wants to merge 1 commit intomainfrom
Conversation
Threads together six new research reports + the integration architecture
+ the v1 spec for the OK shell-job runner ("OK Minions") + the bundled
`ok lint` aggregator. Plus the prior-session GBrain parity audit that
the integration architecture builds on.
Research thread (6 reports):
- linting-coverage-and-gaps: 1P inventory of OK's current lint state
(5 endpoints exist; no aggregator, no ok lint command, content side
is essentially zero).
- knowledge-linting-karpathy-workflow: 17-check taxonomy across Karpathy
+ GBrain + community implementations; deterministic-vs-LLM split;
4-trigger cadence taxonomy.
- agent-host-hooks-cross-host: cross-host capability matrix - 5 hosts
ship full hooks (Claude Code, Cursor, Codex, Windsurf, Copilot CLI),
2 have zero (Claude Desktop, Cowork), MCP-portable alternatives.
- consolidate-and-overnight-patterns: reframes consolidate-class
operations as part of knowledge lint discipline; 5-trigger taxonomy;
community overnight workflows (eugeniughelbur 5-phase nightly,
Pratiyush llmwiki sync, Anthropic Routines).
- ok-knowledge-lint-integration: earlier integration plan (superseded
by ok-integrated-knowledge-lint-architecture).
- ok-integrated-knowledge-lint-architecture: unified design doc - 3
operations (lint/recompile/consolidate) x 5 triggers x 3 distribution
layers x stream isolation. Generic shell-job runner modeled on GBrain
Minions; agent-CLI-agnostic by design.
Spec (specs/2026-04-28-ok-shell-job-runner/):
- 25 LOCKED/DIRECTED decisions (D1-D25), 23 functional requirements
(FR1-FR23), 14 risk rows.
- State substrate: JSON-file-per-run at .open-knowledge/jobs/runs/<ULID>.json
(zero new dependencies; bun:sqlite migration noted as easy v2 path).
- ok lint reads on-disk markdown directly; no Hocuspocus dependency
for the deterministic-only path. Persona P1 (no-LLM user) gets a
two-line YAML setup with zero LLM cost.
- Off-by-default OK_ALLOW_SHELL_JOBS=1 security gate (mirrors GBrain).
- Includes audit + design-challenge passes (meta/audit-findings.md,
meta/design-challenge.md, meta/_changelog.md) capturing the
thread of decisions.
Also includes reports/gbrain-vs-openknowledge-parity/ from a prior
session - the canonical 1P GBrain capability audit that the integration
architecture and spec both build on. Not authored in this thread but
load-bearing for the cross-references.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Threads together six new research reports + the integration architecture + the v1 spec for the OK shell-job runner ("OK Minions") + the bundled
ok lintaggregator. Plus the prior-session GBrain parity audit that the integration architecture builds on.What this PR is: docs-only — no code changes. A spec ready for
/ship(or for a separate implementation PR) plus the research that grounds it.What this PR is not: an implementation. The runner +
ok lint+ their tests are followup work (~1,030–1,230 LOC acrosspackages/cli/src/scheduler/,packages/cli/src/lint/, two CLI commands, one MCP tool, config schema extension, examples).What landed
Research thread (6 reports)
linting-coverage-and-gaps— 1P inventory of OK's current lint state (5 graph-health endpoints exist; no aggregator, nook lint, content side is essentially zero).knowledge-linting-karpathy-workflow— 17-check taxonomy across Karpathy + GBrain + community implementations; deterministic-vs-LLM split; 4-trigger cadence taxonomy.agent-host-hooks-cross-host— cross-host capability matrix. 5 hosts ship full PreToolUse/PostToolUse hooks (Claude Code, Cursor, Codex, Windsurf, Copilot CLI); 2 have zero (Claude Desktop, Cowork); MCP-portable alternatives inventoried.consolidate-and-overnight-patterns— reframes consolidate-class operations as part of the broader knowledge-lint discipline; introduces the 5-trigger taxonomy (per-event, session-end, daily, weekly, continuous-decay); surveys community overnight workflows (eugeniughelbur 5-phase nightly, Pratiyushllmwiki sync, Anthropic Routines).ok-knowledge-lint-integration— earlier integration plan (superseded byok-integrated-knowledge-lint-architecture).ok-integrated-knowledge-lint-architecture— unified design doc. 3 operations (lint / recompile / consolidate) × 5 triggers × 3 distribution layers × stream isolation. Generic shell-job runner modeled directly on GBrain Minions; agent-CLI-agnostic by design.Spec (
specs/2026-04-28-ok-shell-job-runner/).open-knowledge/jobs/runs/<ULID>.json. Zero new dependencies — purenode:fs/promises.bun:sqlitemigration documented as easy v2 path.ok lintreads on-disk markdown directly — no Hocuspocus dependency for the deterministic-only path. Persona P1 (no-LLM user) gets a two-line YAML setup with zero LLM cost.OK_ALLOW_SHELL_JOBS=1security gate (mirrors GBrain'sGBRAIN_ALLOW_SHELL_JOBS=1).cmd:is whatever they pick — bash script, Claude Code, Codex, Aider+Ollama, Anthropic Routines, custom orchestrator.meta/audit-findings.md,meta/design-challenge.md,meta/_changelog.md) capturing the full thread of decisions.Bundled prior-session research
reports/gbrain-vs-openknowledge-parity/— the canonical 1P GBrain capability audit from a prior session (2026-04-27). Not authored in this thread but load-bearing — the integration architecture and spec both build on its Minions /dream/ durable-jobs evidence.Why this matters
OK is interactive-only today. Every lint check, every wiki-health audit fires when somebody asks. If nobody asks, nothing happens. This spec adds a thin scheduling adapter (modeled on GBrain's production-validated Minions architecture) that lets users wire any agent CLI — or none — into a cron-style schedule. Persona P1 (laptop user, no LLM subscription) gets bookkeeping for free; Personas P2/P3 wire their agents of choice.
The deeper principle: OK is to knowledge what git is to code. Substrate, not framework. The runner doesn't know what an LLM is; the user picks.
Test plan
This is a docs-only PR. No automated test surface.
specs/2026-04-28-ok-shell-job-runner/SPEC.mdend-to-end.meta/audit-findings.md) — H1 (substrate) and M11 (ok lintHocuspocus dependency) were the two decision-reopens; both resolved permeta/_changelog.md.§16 Agent constraintsSCOPE/EXCLUDE/STOP_IF/ASK_FIRST are tight enough for a downstream/ship.reports/gbrain-vs-openknowledge-parity/) is the version you intend to land — it was untracked at the start of this session, included here because the integration architecture cross-references it.🤖 Generated with Claude Code