@unson/brainbase-mcp 0.3.1 → 0.4.1

package/docs/architecture/judgment-dag-core.md

@@ -0,0 +1,313 @@
+---
+title: Brainbase Judgment DAG Core
+status: accepted
+date: 2026-08-20
+scope: OSS Brainbase / shared core
+supersedes_in_part: docs/architecture/brainbase-memory-loop-product-boundary.md
+---
+
+# Brainbase Judgment DAG Core
+
+## Decision
+
+Brainbase OSS and organization deployments share the same Judgment DAG semantic model and runtime core.
+
+Brainbase is not only a memory/knowledge store. Its core responsibility is to externalize, preserve, replay, evaluate, and improve the structure by which a person or organization turns context into judgment and action.
+
+The prior product boundary that limited OSS Brainbase to `Remember / Organize / Retrieve / Learn` is revised. Brainbase owns the **judgment substrate**; Mana may own autonomous operating loops, continuous follow-through, and outcome ownership on top of that substrate.
+
+```text
+Brainbase = Remember / Organize / Retrieve / Judge / Replay / Learn
+Mana      = Operate / Prioritize continuously / Act autonomously / Follow-through
+```
+
+Brainbase may represent and execute judgment nodes. It does not become an always-on autonomous operator merely because it can execute a DAG.
+
+## Core hypothesis
+
+A person or organization can be modeled as a stateful system that repeatedly executes a directed judgment graph:
+
+```text
+State(t)
+   ↓
+Context / Observation DAG
+   ↓
+Judgment DAG
+   ↓
+Resource / Risk DAG
+   ↓
+Execution DAG
+   ↓
+Outcome
+   ↓
+Evaluation DAG
+   ↓
+State(t+1) + DAG update
+```
+
+The durable asset is not the document corpus itself. It is the reusable structure connecting evidence, assumptions, judgments, decisions, commitments, actions, outcomes, and updates.
+
+## Shared five-layer model
+
+### Layer 1: Context DAG
+Produces normalized observations and state required by downstream judgment.
+
+Allowed:
+- facts and observations
+- metrics and snapshots
+- entity resolution
+- source provenance
+- temporal validity
+
+Forbidden:
+- strategic choice
+- resource allocation
+- external action
+
+### Layer 2: Judgment DAG
+Produces reusable interpretations and decisions from Context outputs.
+
+Examples:
+- priority judgment
+- pricing judgment
+- product fit judgment
+- go/no-go judgment
+- policy selection
+
+Forbidden:
+- direct mutation of execution state
+- hidden reads from raw sources that bypass Context contracts
+- direct resource commitment
+
+### Layer 3: Resource / Risk DAG
+Converts judgments into bounded commitments.
+
+Examples:
+- budget
+- time allocation
+- staffing
+- risk limit
+- approval threshold
+- scope
+
+Forbidden:
+- reimplementing upstream business judgment
+- performing the external action itself
+
+### Layer 4: Execution DAG
+Turns approved commitments into actions and records execution artifacts.
+
+An **outcome** is the result that the Execution DAG generates and records. It is
+an execution-layer node, not an independent sixth layer. The canonical node
+type-to-layer mapping is `observation -> context`, `judgment/decision ->
+judgment`, `resource -> resource`, `execution/outcome -> execution`, and
+`evaluation -> evaluation`.
+
+Examples:
+- create task
+- send proposal
+- deploy software
+- sign/route contract
+- schedule meeting
+
+Forbidden:
+- silently changing upstream judgment or policy
+- acquiring authority that was not granted by the DAG
+
+### Layer 5: Evaluation DAG
+Compares outcomes against explicit goals and evaluation criteria.
+
+Examples:
+- forecast error
+- KPI pass/fail
+- decision quality
+- resource efficiency
+- user value confirmation
+
+Evaluation can propose an update to a judgment/policy/DAG version; it does not silently rewrite canonical judgment without the required authority.
+
+## Node contract
+
+A shared Judgment DAG node SHOULD converge on the following semantic contract:
+
+```text
+id
+node_type
+layer
+scope
+version
+description
+
+depends_on[]
+input_contract
+output_contract
+
+runner_type
+  deterministic
+  agent
+  human
+  committee
+  external
+
+authority
+confidence
+valid_from
+valid_to
+provenance
+
+evaluation
+```
+
+Initial node types should stay intentionally small:
+
+```text
+observation
+judgment
+decision
+resource
+execution
+outcome
+evaluation
+```
+
+The `outcome` node type therefore remains in the Execution layer even though
+the flow diagram shows it between Execution and Evaluation.
+
+Ontology growth must be driven by failed real use cases, not by speculative completeness.
+
+## Edge contract
+
+Knowledge/identity relations and judgment dependencies are different concepts and must not be collapsed.
+
+Judgment DAG edges include:
+
+```text
+depends_on
+supports
+contradicts
+gates
+supersedes
+produces
+evaluated_by
+triggers
+```
+
+`depends_on` defines executable DAG topology. `node.depends_on` is the
+topology SSOT: every dependency pair must have exactly one matching
+`relation=depends_on` edge, and every `relation=depends_on` edge must have
+exactly one matching node dependency. The edge is a required complete mirror,
+not an optional duplicate declaration; a one-sided or mismatched
+representation is `invalid_contract`. Relations such as `member_of`,
+`owned_by`, or `accountable_for` remain graph semantics and can be referenced
+by DAG nodes.
+
+## Scope model: personal and organization use the same DAG
+
+Do not create separate `PersonalDecision` and `CompanyDecision` schemas.
+
+A node is scoped instead:
+
+```text
+scope:
+  type: personal | project | organization
+  id: <scope-id>
+```
+
+This enables promotion:
+
+```text
+Personal Judgment
+   ↓ evidence / repeated success
+Project Judgment
+   ↓ promotion / authority
+Organization Policy
+```
+
+A judgment can therefore move from an individual's learned heuristic into an organizational capability without translation into a separate schema.
+
+J0-1 does not implement cross-scope promotion or authority evidence. Before
+execution, both nodes in every dependency pair must have exactly equal
+`scope.type` and `scope.id`; otherwise validation fails closed with the
+machine-readable code `scope_boundary_violation`. A structurally valid DAG is
+not evidence of execution authority, approval, or promotion. Those governance
+boundaries remain later-scope work.
+
+## Runtime principles inherited from FX / keiba DAG work
+
+Brainbase adopts the architecture lessons proven in the `sintariran/FX` and `sintariran/keiba` DAG systems:
+
+1. **Layer ownership is explicit.** A downstream layer must not reimplement an upstream decision.
+2. **Inputs and outputs cross typed contracts.** No hidden state side channels.
+3. **Dependencies are validated before execution.** Missing or reverse-layer dependencies are errors.
+4. **Every run produces artifacts and an execution log.** A judgment must be replayable and auditable.
+5. **DAG versions are first-class.** A changed judgment structure is a new version, not an invisible mutation.
+6. **Evaluation is separate from execution.** Metrics must not be gamed by modifying the system under evaluation.
+
+## OSS / organization boundary
+
+The Judgment DAG core is OSS-level product capability.
+
+OSS includes:
+- node/edge semantic model
+- dependency validation
+- local execution runtime
+- human and agent runners
+- local artifact/execution log
+- versioning
+- replay/evaluation primitives
+- personal/project/organization scope primitives
+- basic authority metadata
+
+Organization/Enterprise adds operational concerns rather than a different brain model:
+- organization identity and directory integration
+- robust RBAC / authority graph
+- approval and escalation workflows
+- multi-user concurrency
+- managed connectors
+- audit/compliance retention
+- hosted runtime and HA
+- cross-project governance
+- enterprise security boundaries
+
+## Mana boundary after this decision
+
+Mana is no longer defined as the only place where judgment can occur.
+
+Brainbase owns **what the judgment graph is, what it depends on, who/what can run it, what it produced, and how it evaluated**.
+
+Mana owns the higher-order operating behavior that repeatedly decides *when* to run graphs, prioritizes across goals, initiates work, monitors progress, follows through, and intervenes over time.
+
+```text
+Brainbase: executable organizational cognition
+Mana: autonomous organizational operation
+```
+
+## Non-goals
+
+- Do not migrate the entire Brainbase ontology to a large Company Ontology in one release.
+- Do not make all knowledge executable.
+- Do not let an LLM infer authority implicitly.
+- Do not create a single monolithic company DAG.
+- Do not auto-promote personal judgments into organization policy without explicit evidence and authority.
+
+## First proving ground
+
+`Brainbase Deployment` is the first dogfooding domain.
+
+The initial DAG should capture:
+
+```text
+Customer Context
+  ↓
+Maturity / Problem Structure Judgment
+  ↓
+Deployment Pattern Selection
+  ↓
+Scope / Resource Decision
+  ↓
+Proposal / Implementation
+  ↓
+Outcome Evaluation
+```
+
+Human judgment can initially be a runner. Each repeated decision should then be tested for delegation to an agent. The key success signal is a falling count of decisions that still require the original expert directly.

package/docs/management/judgment-dag-milestones.md

@@ -0,0 +1,143 @@
+---
+title: Brainbase Judgment DAG Milestones
+status: active
+date: 2026-08-20
+scope: OSS Brainbase
+---
+
+# Brainbase Judgment DAG Milestones
+
+This roadmap replaces any implicit assumption that OSS Brainbase stops at memory retrieval. The next milestones make the shared Judgment DAG core real without prematurely building a complete enterprise ontology.
+
+## M0 — Architecture lock
+
+Goal: freeze semantic boundaries before implementation.
+
+Exit criteria:
+- `judgment-dag-core.md` is accepted.
+- Personal and organization scopes share one node/edge model.
+- Brainbase/Mana boundary is documented as cognition vs autonomous operation.
+- FX/keiba lessons are explicitly adopted: layered ownership, typed boundaries, artifact logs, versioning, evaluation separation.
+
+## M1 — Local DAG kernel
+
+Goal: execute a small deterministic DAG locally.
+
+Deliverables:
+- `JudgmentDAGNode` / edge types
+- `depends_on` validation
+- layer validation
+- deterministic runner
+- execution artifact store
+- execution log
+- DAG version identifier
+
+Exit criteria:
+- A DAG with Context → Judgment → Resource → Execution → Evaluation runs deterministically.
+- Missing dependency and reverse-layer dependency fail before execution.
+- Every node output is inspectable after execution.
+- Existing Brainbase Graph/Decision storage remains compatible.
+
+## M2 — Human + Agent judgment runners
+
+Goal: allow a judgment node to be performed by a human or an agent without changing DAG semantics.
+
+Deliverables:
+- `runner_type = human | agent | deterministic | external`
+- pending human-step representation
+- agent input/output contract
+- explicit authority metadata
+- confidence/provenance recording
+
+Exit criteria:
+- The same judgment node can be run manually and by an agent.
+- Outputs can be compared without hidden context.
+- Agent execution cannot silently acquire additional authority.
+
+## M3 — Replay and evaluation
+
+Goal: make judgment quality testable rather than anecdotal.
+
+Deliverables:
+- immutable run snapshot / artifact reference
+- replay against historical context
+- explicit goal/evaluation criteria
+- outcome attachment
+- pass/fail or scored evaluation
+- node-level comparison between versions
+
+Exit criteria:
+- A prior DAG version can be replayed against a recorded context.
+- A new version can be compared with the prior version without rewriting historical artifacts.
+- Evaluation cannot mutate the event set it evaluates.
+
+## M4 — Brainbase Deployment dogfood
+
+Goal: externalize the first real expert judgment process.
+
+Initial flow:
+
+```text
+Customer Context
+  -> Maturity Judgment
+  -> Problem Structure Judgment
+  -> Deployment Pattern
+  -> Scope / Resource Decision
+  -> Proposal / Implementation
+  -> Outcome Evaluation
+```
+
+Exit criteria:
+- At least one real deployment is represented end-to-end.
+- Human-only judgment nodes are explicit.
+- Each expert escalation is logged as a missing/uncertain DAG capability rather than disappearing into chat.
+- KPI: number of decisions requiring the original expert is measurable per deployment.
+
+## M5 — Scope promotion
+
+Goal: prove Personal → Project → Organization judgment promotion using one schema.
+
+Deliverables:
+- scope metadata
+- promotion candidate workflow
+- evidence links
+- authority/approval gate
+- supersession handling
+
+Exit criteria:
+- A personal judgment can become project guidance and then organization policy without schema conversion.
+- The historical personal/project records remain queryable.
+- Promotion never occurs solely because an LLM repeats the same output.
+
+## M6 — Organization-ready primitives
+
+Goal: keep the core reusable while allowing enterprise products to extend it.
+
+Deliverables in OSS core:
+- authority references
+- approval hooks
+- organization scope primitives
+- audit event contract
+- connector/runtime adapter interfaces
+
+Not required in OSS M6:
+- SSO/SCIM
+- enterprise directory sync
+- HA hosted runtime
+- compliance retention policies
+- full multi-user approval UI
+
+Exit criteria:
+- `brainbase-unson` can implement enterprise authority/governance without forking the DAG semantic model.
+
+## Product metric hierarchy
+
+The roadmap is not complete merely because graph/node counts increase. Measure:
+
+1. **Replayability** — can Brainbase explain and rerun why a judgment occurred?
+2. **Delegatability** — can an agent/another human run the node using explicit contracts?
+3. **Expert escalation count** — how often is tacit expert judgment still required?
+4. **Outcome calibration** — do judgment versions improve against declared goals?
+5. **Promotion quality** — are reusable judgments correctly distinguished from case-specific decisions?
+
+The primary dogfood KPI is **expert escalation count per deployment**, not total stored knowledge.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.3.1",
-  "description": "Local-first Brainbase MCP server and personal onboarding kit.",
+  "version": "0.4.1",
+  "description": "Local-first Brainbase MCP for preserving decision context and helping humans and AI work from the same judgment criteria.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -10,12 +10,31 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./judgment-dag": {
+      "types": "./dist/judgment-dag.d.ts",
+      "import": "./dist/judgment-dag.js"
+    },
+    "./dist/*": "./dist/*",
+    "./contracts/judgment-dag/schema.json": "./contracts/judgment-dag/schema.json",
+    "./contracts/judgment-dag/fixture.json": "./contracts/judgment-dag/fixture.json",
+    "./contracts/judgment-dag/source-lock.json": "./contracts/judgment-dag/source-lock.json",
+    "./contracts/judgment-dag/digest.json": "./contracts/judgment-dag/digest.json",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "brainbase-mcp": "dist/index.js",
     "brainbase": "dist/cli.js"
   },
   "files": [
     "dist",
+    "contracts",
+    "docs/architecture/judgment-dag-core.md",
+    "docs/management/judgment-dag-milestones.md",
     "README.md",
     "LICENSE",
     "SECURITY.md"
@@ -25,13 +44,19 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
+    "test": "vitest run --exclude tests/npm-prepublication-evidence.integration.test.ts",
     "test:integration": "vitest run tests/mcp-contract.test.ts tests/ontology-cli.test.ts tests/npm-release-validation.integration.test.ts tests/npm-consumer-smoke.integration.test.ts",
     "test:consumer-smoke": "vitest run tests/npm-consumer-smoke.integration.test.ts",
     "test:integration:release-evidence": "vitest run tests/npm-release-validation.integration.test.ts tests/npm-prepublication-evidence.integration.test.ts",
     "test:e2e": "vitest run tests/e2e/brainbase-mcp-only-acceptance.spec.ts tests/e2e/story-brainbase-portable-ontology-kernel-acceptance.spec.ts",
     "docs:dev": "vitepress dev docs",
+    "docs:sync": "node scripts/sync-public-message.mjs --write",
+    "docs:check": "node scripts/check-public-docs.mjs",
     "docs:build": "vitepress build docs",
+    "docs:smoke": "node scripts/check-built-docs.mjs",
+    "docs:verify-public": "node scripts/verify-public-site.mjs",
+    "docs:promotion:plan": "node scripts/promote-public-message.mjs --plan",
+    "docs:promotion:apply": "node scripts/promote-public-message.mjs --apply",
     "docs:preview": "vitepress preview docs",
     "start": "node dist/index.js",
     "doctor": "node dist/cli.js doctor",
@@ -40,6 +65,7 @@
     "onboard:seed": "node dist/cli.js onboard:seed",
     "onboard:demo": "node dist/cli.js onboard:demo",
     "onboard:install": "node dist/cli.js onboard:install",
+    "contracts:generate": "node scripts/generate-judgment-dag-contract-artifacts.mjs",
     "release:plan": "node scripts/npm-release.mjs plan",
     "release:validate": "node scripts/npm-release.mjs validate",
     "release:publish": "node scripts/npm-release.mjs publish",
@@ -62,5 +88,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "0ff2753a492aef09235be2792570000ef03dfa4b"
+  "gitHead": "b6210adfb43cf4321148e06dc48e94f200b805a5"
 }