Status: Research Preview —
0.1.0-draftThis repository is an early design proposal. It is not an industry standard, is not covered by compatibility guarantees, and is not ready for consequential production decisions.
Coding agents do useful multi-step work because they operate inside an environment that already knows how to judge their output: compilers, type systems, tests, linters, static analysis, version control, code review, and CI supply objective pass/fail signals against an explicit target.
Most business AI agents lack that environment. Their goals are ambiguous, their evidence is scattered across documents and systems, the meaning of a term depends on context, and feedback is delayed or subjective — so the same decision is hard to evaluate definitively. What is missing is not more information; it is an explicit judgment layer and a way to test it.
Judgment Pack makes that layer explicit. A Judgment Pack is a portable, vendor-neutral JSON document that declares what decision is being made, what evidence it requires, when it applies, how exceptions and uncertainty are handled, which outcomes are possible, and when a human must take over — so the reasoning behind a decision can be inspected, tested, versioned, and moved between independent tools.
AI systems increasingly participate in business decisions, but prompts, retrieval configurations, and application code do not provide a stable interchange format for the judgment behind those decisions. The Judgment Pack Specification (JPS) explores a portable, vendor-neutral way to represent reusable organizational judgment so that it can be inspected, tested, and moved between independent tools.
A Judgment Pack is a JSON document that declares a single decision: what decision is being made, what evidence it requires, where its claims came from, when it applies, how exceptions and uncertainty are handled, which outcomes are possible, and when a human must take over. It captures the reasoning an organization wants applied to a decision, in a form that is separate from any one runtime, model, or user interface.
A new specification is necessary because existing artifacts each capture only part of this and none of them are portable:
- A knowledge base or retrieval index answers "what information is available?" It does not declare which decision that information serves, when a rule applies, or when to escalate.
- A prompt couples intent to a specific model and phrasing; it is not a structured, checkable document that a second tool can validate and reuse.
- A workflow engine encodes control flow and orchestration, not the evidence requirements, exceptions, and uncertainty handling behind a decision.
- An evaluation dataset records inputs and expected outputs; it does not represent the rules and reasoning being evaluated.
JPS aims to make that reasoning a first-class, interchangeable document, without standardizing any one product, model, or workflow.
This research preview exists to test whether a small declarative core can support independent tools and runtimes without standardizing any one product, model, or workflow.
The specification is successful only if independent implementations can exchange the same pack and agree on its document structure and declared field and reference semantics. Portable evaluation is a possible later profile, not a claim of this draft.
Core 0.1.0-draft supports testing carrier, structural, and semantic document conformance. It does
not define evaluator conformance or a portable decision result.
- A JSON-based interchange format for decision intent, evidence requirements, rules, exceptions, outcomes, uncertainty handling, escalation, sources, and traceability.
- A specification that separates document conformance from factual truth and organizational authorization.
- A potential foundation for validators, authoring tools, registries, evaluation systems, and execution engines maintained by different vendors.
- A claim that a conforming pack is correct, safe, authorized, or suitable for a particular use.
- A prompt format, chain-of-thought format, retrieval API, workflow engine, or general-purpose rule language.
- A standard for model selection, inference, optimization, calibration, enterprise identity, or user-interface behavior.
- A stable standard. All
0.xmaterial may change incompatibly.
| Path | Purpose |
|---|---|
spec/judgment-pack-core.md |
Normative prose for document conformance |
schema/judgment-pack-core.schema.json |
Normative Draft 2020-12 structural schema |
examples/ |
Synthetic examples from unrelated domains |
conformance/ |
47 non-normative document-conformance test cases |
TESTING.md |
A 10–15 minute external testing exercise |
VERSIONING.md |
Release and compatibility policy |
CHANGELOG.md |
Draft and published change history |
docs/design-principles.md |
Design principles, non-goals, and origin and scope |
FAQ.md |
Answers to common and hard architectural questions |
rfcs/ |
Open change proposals (RFCs), including the process |
ROADMAP.md |
Evidence-gated path toward a specification |
web/ |
Static documentation site and deployment guide |
.vscode/tasks.json |
One-command local documentation preview |
The docs/ directory records the specification's design constraints, its explicit non-goals, and
how the spec stays independent of any implementation. The specification defines documents only and
contains no end-user tooling. Conforming implementations may be open-source or proprietary and
consume immutable specification releases like any other implementation; see the Implementations page
for the current landscape.
{
"specVersion": "0.1.0-draft",
"id": "https://example.com/judgment-packs/expense-approval",
"version": "0.1.0",
"title": "Expense approval",
"decision": {
"intent": "Determine whether an expense may be automatically approved.",
"question": "May this expense be approved without human review?"
},
"outcomes": [
{ "id": "approve", "label": "Approve" },
{ "id": "manual-review", "label": "Manual review" }
],
"rules": [
{
"id": "large-expense",
"description": "Large expenses require a human decision.",
"when": {
"op": "fact",
"path": "/expense/amount",
"operator": "greater-than",
"value": "5000"
},
"outcome": "manual-review",
"onUnknown": "escalate"
}
],
"fallbackOutcome": "approve"
}See the complete example before relying on this abbreviated shape.
These are deliberately separate claims:
- Carrier conformance: the serialized input satisfies the JSON and carrier requirements.
- Structural conformance: the document satisfies the JPS schema, including asserted formats.
- Semantic document conformance: local references and cross-field constraints satisfy the normative prose.
- Factual grounding: evidence supports the pack's claims.
- Organizational authorization: an accountable organization permits the pack's use.
- Operational fitness: a particular runtime applies it safely and effectively.
This research preview specifies the first three document claims. It explicitly does not specify evaluator conformance; the condition and resolution sections are informative experiments only. A validator must never imply factual grounding, organizational authorization, or operational fitness. The core specification defines the normative artifact roles and precedence.
Follow TESTING.md to validate the supplied examples, observe the schema/semantics
boundary, make a small synthetic authoring change, and report reproducible feedback. In addition to
the minimal example, the repository includes deliberately non-operational examples for software
change readiness and records disposition review.
The repository also includes a minimal static documentation site. Build it locally with:
python3 -m pip install -r requirements-dev.txt
python3 web/build.py
python3 -m http.server 8000 --bind 127.0.0.1 --directory publicThen open http://localhost:8000. The generated public/ directory contains only static HTML,
CSS, and raw artifacts; no pack is executed and no source locator is fetched. See
web/DEPLOYMENT.md for preview-first hosting guidance.
Open the repository in WSL with VS Code, then select Terminal → Run Task → JPS: Preview site.
The task creates the ignored .venv/, installs the pinned dependencies, rebuilds public/, and
serves it at http://localhost:8000. Follow the link in the task terminal and
press Ctrl+C there to stop the server.
Use Terminal → Run Build Task or Ctrl+Shift+B to install dependencies and rebuild the site
without starting the server. The task definitions are in .vscode/tasks.json.
These exercises test documents, not decisions. Do not infer or automate a real outcome from a pack and do not present agreement between experimental evaluators as JPS conformance.
Start with TESTING.md for a short exercise or
CONTRIBUTING.md to propose a change. Material changes should begin as a
Request for Comments (RFC), include compatibility and security analysis, and add positive
and negative examples.
The specification is developed in public by its maintainers and community contributors. Participate via GitHub and the project Slack. The specification is not controlled by any required commercial runtime; the long-term goal is reproducible behavior across independent implementations, which may be open-source or proprietary.
Licensed under the Apache License 2.0. See LICENSE.