@unson/brainbase-mcp 0.3.1 → 0.4.1

package/contracts/judgment-dag/digest.json

@@ -0,0 +1,32 @@
+{
+  "contract": "judgment-dag-core",
+  "algorithm": "sha256",
+  "canonicalization": "UTF-8 lines sorted by path as path + NUL + sha256 + LF",
+  "files": [
+    {
+      "path": "contracts/judgment-dag/fixture.json",
+      "sha256": "c191ea129c55c97d131998698a79f656c900150fb97abb4715aa44d2abca39c5"
+    },
+    {
+      "path": "contracts/judgment-dag/schema.json",
+      "sha256": "af783617e76dc3cdc878210311821f9b0e982b31102ab6bf46ad726d5423745d"
+    },
+    {
+      "path": "contracts/judgment-dag/source-lock.json",
+      "sha256": "c7b3020fe3952d90bd8ed991f613be66c0798983bb6cc2285a9aefff7ab2f0e9"
+    },
+    {
+      "path": "docs/architecture/judgment-dag-core.md",
+      "sha256": "24305aaa97df9c734d468c49f52784e94b77a4f506bae41d482bee05625d7e2a"
+    },
+    {
+      "path": "docs/management/judgment-dag-milestones.md",
+      "sha256": "ef51313f33de64f702fd6c86012984bd70cf99eeca5b4f4cfc27f6cb266172bd"
+    },
+    {
+      "path": "README.md",
+      "sha256": "a263114611c100feb75f9d35ad793593eafb7dea217d846a99efacc06c7efa24"
+    }
+  ],
+  "digest": "e97cefb8dadd451d5929c266376f3774fa84dcdde412e5ff3305b9b70d580ecd"
+}

package/contracts/judgment-dag/fixture.json

@@ -0,0 +1,21 @@
+{
+  "id": "j0-valid",
+  "version": "2026-08-20.1",
+  "nodes": [
+    { "id": "context.customer", "node_type": "observation", "layer": "context", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "customer observation", "depends_on": [], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "context.customer" }], "evaluation": { "criteria": ["context.customer is evaluated"] } },
+    { "id": "context.account", "node_type": "observation", "layer": "context", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "account observation", "depends_on": [], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "context.account" }], "evaluation": { "criteria": ["context.account is evaluated"] } },
+    { "id": "judgment.fit", "node_type": "judgment", "layer": "judgment", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "fit judgment", "depends_on": ["context.customer", "context.account"], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "judgment.fit" }], "evaluation": { "criteria": ["judgment.fit is evaluated"] } },
+    { "id": "resource.scope", "node_type": "resource", "layer": "resource", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "resource scope", "depends_on": ["judgment.fit"], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "resource.scope" }], "evaluation": { "criteria": ["resource.scope is evaluated"] } },
+    { "id": "execution.proposal", "node_type": "execution", "layer": "execution", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "execution proposal", "depends_on": ["resource.scope"], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "execution.proposal" }], "evaluation": { "criteria": ["execution.proposal is evaluated"] } },
+    { "id": "execution.outcome", "node_type": "outcome", "layer": "execution", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "execution outcome", "depends_on": ["execution.proposal"], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "execution.outcome" }], "evaluation": { "criteria": ["execution.outcome is evaluated"] } },
+    { "id": "evaluation.result", "node_type": "evaluation", "layer": "evaluation", "scope": { "type": "project", "id": "project-j0-fixture" }, "version": "1.0.0", "description": "evaluation result", "depends_on": ["execution.outcome"], "input_contract": "fixture.input.v1", "output_contract": "fixture.output.v1", "runner_type": "deterministic", "authority": ["fixture-owner"], "confidence": 1, "valid_from": "2026-08-20T00:00:00.000Z", "valid_to": null, "provenance": [{ "source": "j0-fixture", "reference": "evaluation.result" }], "evaluation": { "criteria": ["evaluation.result is evaluated"] } }
+  ],
+  "edges": [
+    { "from": "context.customer", "to": "judgment.fit", "relation": "depends_on" },
+    { "from": "context.account", "to": "judgment.fit", "relation": "depends_on" },
+    { "from": "judgment.fit", "to": "resource.scope", "relation": "depends_on" },
+    { "from": "resource.scope", "to": "execution.proposal", "relation": "depends_on" },
+    { "from": "execution.proposal", "to": "execution.outcome", "relation": "depends_on" },
+    { "from": "execution.outcome", "to": "evaluation.result", "relation": "depends_on" }
+  ]
+}

package/contracts/judgment-dag/schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Unson-LLC/brainbase/blob/develop/contracts/judgment-dag/schema.json",
+  "title": "Brainbase Judgment DAG core contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "version", "nodes", "edges"],
+  "properties": {
+    "id": { "$ref": "#/$defs/identifier" },
+    "version": { "type": "string", "minLength": 1, "pattern": "\\S" },
+    "nodes": { "type": "array", "items": { "$ref": "#/$defs/node" } },
+    "edges": { "type": "array", "items": { "$ref": "#/$defs/edge" } }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?![\\s\\S]*[\\u0000-\\u001F\\u007F])(?=[\\s\\S]*\\S)[\\s\\S]+$"
+    },
+    "metadata": {
+      "anyOf": [
+        { "type": "string" },
+        { "type": "number" },
+        { "type": "boolean" },
+        { "type": "null" },
+        { "type": "array", "items": { "$ref": "#/$defs/metadata" } },
+        { "type": "object", "additionalProperties": { "$ref": "#/$defs/metadata" } }
+      ]
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": { "enum": ["personal", "project", "organization"] },
+        "id": { "$ref": "#/$defs/identifier" }
+      }
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "node_type", "layer", "scope", "version", "description", "depends_on", "input_contract", "output_contract", "runner_type"],
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "node_type": { "enum": ["observation", "judgment", "decision", "resource", "execution", "outcome", "evaluation"] },
+        "layer": { "enum": ["context", "judgment", "resource", "execution", "evaluation"] },
+        "scope": { "$ref": "#/$defs/scope" },
+        "version": { "type": "string", "minLength": 1, "pattern": "\\S" },
+        "description": { "type": "string", "minLength": 1, "pattern": "\\S" },
+        "depends_on": { "type": "array", "items": { "$ref": "#/$defs/identifier" }, "uniqueItems": true },
+        "input_contract": { "type": "string", "minLength": 1, "pattern": "\\S" },
+        "output_contract": { "type": "string", "minLength": 1, "pattern": "\\S" },
+        "runner_type": { "enum": ["deterministic", "agent", "human", "committee", "external"] },
+        "authority": { "$ref": "#/$defs/metadata" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "valid_from": { "type": ["string", "null"] },
+        "valid_to": { "type": ["string", "null"] },
+        "provenance": { "type": "array", "items": { "$ref": "#/$defs/metadata" } },
+        "evaluation": { "$ref": "#/$defs/metadata" }
+      },
+      "allOf": [
+        { "if": { "properties": { "node_type": { "const": "observation" } } }, "then": { "properties": { "layer": { "const": "context" } } } },
+        { "if": { "properties": { "node_type": { "enum": ["judgment", "decision"] } } }, "then": { "properties": { "layer": { "const": "judgment" } } } },
+        { "if": { "properties": { "node_type": { "const": "resource" } } }, "then": { "properties": { "layer": { "const": "resource" } } } },
+        { "if": { "properties": { "node_type": { "enum": ["execution", "outcome"] } } }, "then": { "properties": { "layer": { "const": "execution" } } } },
+        { "if": { "properties": { "node_type": { "const": "evaluation" } } }, "then": { "properties": { "layer": { "const": "evaluation" } } } }
+      ]
+    },
+    "edge": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to", "relation"],
+      "properties": {
+        "from": { "$ref": "#/$defs/identifier" },
+        "to": { "$ref": "#/$defs/identifier" },
+        "relation": { "enum": ["depends_on", "supports", "contradicts", "gates", "supersedes", "produces", "evaluated_by", "triggers"] }
+      }
+    }
+  }
+}

package/contracts/judgment-dag/source-lock.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "contract": "judgment-dag-core",
+  "repository": "https://github.com/Unson-LLC/brainbase",
+  "status": "accepted",
+  "accepted_base_commit": "7e5d5693f988f4ba84072c5910ef32f0e70871e1",
+  "sources": [
+    {
+      "kind": "architecture",
+      "path": "docs/architecture/judgment-dag-core.md",
+      "sha256": "24305aaa97df9c734d468c49f52784e94b77a4f506bae41d482bee05625d7e2a"
+    },
+    {
+      "kind": "milestones",
+      "path": "docs/management/judgment-dag-milestones.md",
+      "sha256": "ef51313f33de64f702fd6c86012984bd70cf99eeca5b4f4cfc27f6cb266172bd"
+    }
+  ],
+  "notes": [
+    "Outcome is produced and recorded by the Execution DAG and maps to the execution layer.",
+    "This J0 contract slice does not implement runner, artifact, execution-log, replay, evaluation, or mutation protection; those remain J0-2 non-goals and unverified.",
+    "Public DAG identifiers reject C0 and DEL control characters so dependency pair keys cannot collide.",
+    "J0 multi-tenancy evidence is limited to exact scope equality; cross-scope authorization, runtime, secret, database, and deployment are non-goals."
+  ]
+}

package/contracts/public-message-candidate.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://brainbase.pages.dev/contracts/public-message-candidate.schema.json",
+  "title": "Brainbase approved public-message candidate",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "candidate_id",
+    "status",
+    "source",
+    "approval",
+    "copy"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0"
+    },
+    "candidate_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]{2,127}$"
+    },
+    "status": {
+      "const": "approved"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "entity_id",
+        "snapshot_hash",
+        "exported_at",
+        "scope"
+      ],
+      "properties": {
+        "type": {
+          "const": "brainbase_graph"
+        },
+        "entity_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "entity_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "snapshot_hash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "exported_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "scope": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "approved_by",
+        "approved_at",
+        "reason"
+      ],
+      "properties": {
+        "status": {
+          "const": "approved"
+        },
+        "approved_by": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "approved_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000
+        }
+      }
+    },
+    "copy": {
+      "$ref": "#/$defs/copy"
+    }
+  },
+  "$defs": {
+    "copy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "headline",
+        "short_definition",
+        "definition",
+        "human_role",
+        "ai_role",
+        "package_description"
+      ],
+      "properties": {
+        "headline": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "short_definition": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160
+        },
+        "definition": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 400
+        },
+        "human_role": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "ai_role": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 240
+        },
+        "package_description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 240
+        }
+      }
+    }
+  }
+}

package/dist/cli.js

@@ -65,7 +65,7 @@ export async function runCli(argv = process.argv.slice(2), io = process) {
             case 'ontology:migrate':
                 return await ontologyMigrate(parsed, io);
             case 'judgment:hook':
-                return await judgmentHook(io);
+                return await judgmentHook(parsed, io);
             case 'judgment:install':
                 return await judgmentInstall(parsed, io);
             case 'doctor':
@@ -83,12 +83,25 @@ export async function runCli(argv = process.argv.slice(2), io = process) {
         return 1;
     }
 }
-async function judgmentHook(io) {
+function judgmentAutonomyOptions(parsed) {
+    const rawMode = first(parsed, 'autonomy-mode');
+    if (rawMode !== undefined && !['off', 'canary', 'on'].includes(rawMode)) {
+        throw new Error('judgment_autonomy_mode_invalid');
+    }
+    const project = first(parsed, 'autonomy-project')?.trim();
+    if (rawMode === 'canary' && !project)
+        throw new Error('judgment_autonomy_canary_project_missing');
+    return {
+        ...(rawMode ? { autonomyMode: rawMode } : {}),
+        ...(project ? { autonomyCanaryProjects: [project] } : {})
+    };
+}
+async function judgmentHook(parsed, io) {
     let payload = {};
     try {
         const input = await readHookStdin(io.stdin ?? process.stdin);
         payload = JSON.parse(input || '{}');
-        write(io, `${JSON.stringify(await processJudgmentHook(payload))}\n`);
+        write(io, `${JSON.stringify(await processJudgmentHook(payload, judgmentAutonomyOptions(parsed)))}\n`);
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
@@ -106,10 +119,20 @@ async function judgmentInstall(parsed, io) {
     if (target !== 'codex')
         throw new Error('judgment:install currently requires --target codex');
     const cliPath = fileURLToPath(new URL('./cli.js', import.meta.url));
+    const autonomy = judgmentAutonomyOptions(parsed);
+    const hookArguments = [
+        process.execPath,
+        cliPath,
+        'judgment:hook',
+        ...(autonomy.autonomyMode ? ['--autonomy-mode', autonomy.autonomyMode] : []),
+        ...(autonomy.autonomyCanaryProjects?.[0]
+            ? ['--autonomy-project', autonomy.autonomyCanaryProjects[0]]
+            : [])
+    ];
     const hook = {
         hooks: [{
                 type: 'command',
-                command: `${JSON.stringify(process.execPath)} ${JSON.stringify(cliPath)} judgment:hook`,
+                command: hookArguments.map((argument) => JSON.stringify(argument)).join(' '),
                 statusMessage: 'brainbase judgment resolver'
             }]
     };
@@ -1065,8 +1088,8 @@ function usage() {
   brainbase ontology:show
   brainbase ontology:audit [--dir path] [--ontology-version 0.0.0|1.0.0|2.0.0]
   brainbase ontology:migrate [--dir path] [--write --expected-input-digest digest]
-  brainbase judgment:install --target codex [--dry-run] [--output path]
-  brainbase judgment:hook
+  brainbase judgment:install --target codex [--autonomy-mode off|canary|on] [--autonomy-project code] [--dry-run] [--output path]
+  brainbase judgment:hook [--autonomy-mode off|canary|on] [--autonomy-project code]
   brainbase doctor [--dir path] [--judgment-hooks path]
 `;
 }

package/dist/judgment-autonomy.d.ts

@@ -0,0 +1,62 @@
+export type JudgmentAutonomyVerdict = 'continue' | 'human_required' | 'not_applicable';
+export type JudgmentAutonomyReasonCode = 'not_a_human_escalation' | 'routine_reversible_work' | 'semantic_judgment_required' | 'irreversible_external_action' | 'missing_authority_or_secret' | 'material_commitment' | 'owner_value_choice' | 'resolver_selected_clarification' | 'resolver_continue' | 'resolver_human_required';
+export interface JudgmentAutonomyInstructionPatch {
+    cancel: readonly string[];
+    do_next: readonly string[];
+    acceptance_criteria: readonly string[];
+}
+export interface JudgmentAutonomyContext {
+    turn_id: string;
+    request: string;
+    final_answer: string;
+    project_code?: string;
+    selected_dag_ids: readonly string[];
+}
+export interface JudgmentAutonomyResolverRequest {
+    schema_version: 'brainbase-autonomy-resolver-request-v1';
+    case_id: string;
+    turn_id: string;
+    task_request: string;
+    proposed_human_question: string;
+    project_code?: string;
+    selected_dag_ids: readonly string[];
+    policy: {
+        default_behavior: 'continue';
+        complexity_behavior: 'decompose_and_continue';
+        human_only: readonly [
+            'irreversible_external_action',
+            'missing_authority_or_secret',
+            'material_commitment',
+            'new_owner_value_choice'
+        ];
+    };
+}
+export interface JudgmentAutonomyResolverDecision {
+    schema_version: 'brainbase-autonomy-resolver-decision-v1';
+    case_id: string;
+    verdict: 'continue' | 'human_required';
+    reason_code: string;
+    reason: string;
+    basis: ReadonlyArray<{
+        entity_id: string;
+        application: string;
+    }>;
+    instruction_patch?: JudgmentAutonomyInstructionPatch;
+    human_question?: string;
+}
+export type JudgmentAutonomyResolver = (request: JudgmentAutonomyResolverRequest) => Promise<JudgmentAutonomyResolverDecision>;
+export interface JudgmentAutonomyEvaluation {
+    schema_version: 'brainbase-autonomy-evaluation-v1';
+    case_id: string;
+    verdict: JudgmentAutonomyVerdict;
+    reason_code: JudgmentAutonomyReasonCode;
+    reason: string;
+    question: string | null;
+    source: 'deterministic' | 'same_codex' | 'independent_resolver';
+    instruction_patch: JudgmentAutonomyInstructionPatch | null;
+    resolver_decision: JudgmentAutonomyResolverDecision | null;
+}
+export declare function visibleAnswerBody(answer: string): string;
+export declare function extractHumanDecisionQuestion(answer: string): string | null;
+export declare function evaluateJudgmentAutonomy(context: JudgmentAutonomyContext, resolver?: JudgmentAutonomyResolver): Promise<JudgmentAutonomyEvaluation>;
+export declare function renderJudgmentAutonomyContinuation(evaluation: JudgmentAutonomyEvaluation): string;