Add plain-language status doc and minimal decision store contract

plugins/reporting-governance/test/decision-store.test.mjs

@@ -0,0 +1,133 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  createDecisionRecordArtifact,
+  createDecisionRecordFileName,
+  createFileDecisionStore,
+  validateDecisionRecordArtifact,
+} from '../src/storage/index.mjs';
+import { planDecisionExecution } from '../src/core/decision-runner.mjs';
+
+const packageRoot = path.resolve(import.meta.dirname, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+
+const capabilityDescriptor = {
+  capabilities: {
+    enforcement: {
+      force_checkpoint: { supported: true, level: 'partial' },
+      escalate: { supported: true, level: 'full' }
+    },
+    notification_path: {
+      queue_items: { supported: true, level: 'full' },
+      spool_handoff: { supported: true, level: 'full' },
+      sender_binding: { supported: true, level: 'full' },
+      direct_send: { supported: false, level: 'none' },
+      truth_model: {
+        delivery_states: ['prepared', 'queued', 'dispatched', 'pending_external_send', 'acked', 'blocked'],
+        ack_requires_proven_send: true,
+        pending_external_send_supported: true
+      }
+    }
+  }
+};
+
+function createPlannedDecision() {
+  return planDecisionExecution({
+    decision: {
+      decision: 'force_checkpoint',
+      policy_id: 'no-silence.missed-checkpoint',
+      severity: 'high',
+      reason: 'checkpoint overdue',
+      required_actions: [
+        { action: 'notify_operator', target: 'operator_channel', mandatory: true },
+        { action: 'emit_event', target: 'event_stream', mandatory: true }
+      ],
+      operator_notice: {
+        required: true,
+        channel: 'telegram',
+        urgency: 'high',
+        message: 'Required update.',
+        deadline: '2026-01-01T00:00:00.000Z'
+      }
+    },
+    capabilityDescriptor,
+  });
+}
+
+test('decision artifact validates minimal package-owned contract', () => {
+  const planned = createPlannedDecision();
+  const artifact = createDecisionRecordArtifact({
+    decision: planned.decision,
+    receipt: planned.receipt,
+    recordedAt: '2026-05-08T04:00:00.000Z',
+    source: {
+      event_id: 'evt_watchdog_001',
+      task_id: 'task-reporting-governance',
+      correlation_id: 'corr-001',
+    },
+  });
+
+  assert.equal(artifact.kind, 'DecisionRecordArtifact');
+  assert.equal(artifact.apiVersion, 'reporting-governance/v1alpha1');
+  assert.equal(artifact.metadata.policy_id, 'no-silence.missed-checkpoint');
+  assert.equal(artifact.spec.receipt.delivery_state, 'pending_external_send');
+  assert.equal(validateDecisionRecordArtifact(artifact), artifact);
+});
+
+test('decision artifact filename is stable and readable', () => {
+  const planned = createPlannedDecision();
+  const artifact = createDecisionRecordArtifact({
+    decision: planned.decision,
+    receipt: planned.receipt,
+    recordedAt: '2026-05-08T04:00:00.000Z',
+  });
+
+  const fileName = createDecisionRecordFileName(artifact);
+  assert.match(fileName, /^2026-05-08T04-00-00-000Z-no-silence\.missed-checkpoint-force_checkpoint-dec_[a-f0-9-]+\.json$/);
+});
+
+test('file decision store writes and reloads a validated decision artifact inside repo root', async (t) => {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'reporting-governance-decision-store-'));
+  t.after(() => fs.rmSync(sandbox, { recursive: true, force: true }));
+
+  const fakeRepoRoot = path.join(sandbox, 'repo');
+  fs.mkdirSync(fakeRepoRoot, { recursive: true });
+
+  const planned = createPlannedDecision();
+  const store = createFileDecisionStore({
+    decisionsDir: path.join(fakeRepoRoot, 'state', 'decisions'),
+    repoRootOverride: fakeRepoRoot,
+  });
+
+  const written = store.write({
+    decision: planned.decision,
+    receipt: planned.receipt,
+    recordedAt: '2026-05-08T04:00:00.000Z',
+    source: {
+      event_id: 'evt_watchdog_001',
+      task_id: 'task-reporting-governance',
+      correlation_id: 'corr-001',
+    },
+  });
+
+  assert.equal(fs.existsSync(written.artifactPath), true);
+  assert.match(path.basename(written.artifactPath), /^2026-05-08T04-00-00-000Z-no-silence\.missed-checkpoint-force_checkpoint-dec_[a-f0-9-]+\.json$/);
+
+  const loaded = store.load(written.artifactPath);
+  assert.equal(loaded.artifact.metadata.event_id, 'evt_watchdog_001');
+  assert.equal(loaded.artifact.spec.receipt.delivery_state, 'pending_external_send');
+});
+
+test('file decision store rejects decision directory escaping repo root', () => {
+  assert.throws(
+    () => createFileDecisionStore({
+      decisionsDir: path.resolve(repoRoot, '..', 'escape'),
+      repoRootOverride: repoRoot,
+    }),
+    /decision store decisionsDir must stay within repo root/
+  );
+});

plugins/reporting-governance/test/exports-boundary.integration.test.mjs

@@ -66,18 +66,27 @@ test('package root export resolves public package surface only', () => {
       import * as plugin from '@openclaw/plugin-reporting-governance';
       process.stdout.write(JSON.stringify({
         packageName: plugin.packageName,
+        artifactKinds: plugin.artifactKinds,
         hasRunWatchdogChain: typeof plugin.runWatchdogChain,
         hasPlanDecisionExecution: typeof plugin.planDecisionExecution,
         hasExecuteGovernanceContract: typeof plugin.executeGovernanceContract,
         hasExecuteRuntimeIntegratedGovernance: typeof plugin.executeRuntimeIntegratedGovernance,
+        hasCreateDecisionRecordArtifact: typeof plugin.createDecisionRecordArtifact,
+        hasCreateFileDecisionStore: typeof plugin.createFileDecisionStore,
       }));
     `);
 
     assert.equal(result.packageName, '@openclaw/plugin-reporting-governance');
+    assert.deepEqual(result.artifactKinds, {
+      deploymentProfile: 'DeploymentProfileArtifact',
+      decisionRecord: 'DecisionRecordArtifact',
+    });
     assert.equal(result.hasRunWatchdogChain, 'function');
     assert.equal(result.hasPlanDecisionExecution, 'function');
     assert.equal(result.hasExecuteGovernanceContract, 'function');
     assert.equal(result.hasExecuteRuntimeIntegratedGovernance, 'function');
+    assert.equal(result.hasCreateDecisionRecordArtifact, 'function');
+    assert.equal(result.hasCreateFileDecisionStore, 'function');
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }

plugins/reporting-governance/test/package-structure.test.mjs

@@ -20,6 +20,8 @@ const requiredPaths = [
   'src/adapters/orchestrator.mjs',
   'src/storage',
   'src/storage/profile-artifact.mjs',
+  'src/storage/decision-artifact.mjs',
+  'src/storage/decision-store.mjs',
   'src/reference/openclaw-watchdog-chain.md',
   'capabilities/openclaw-watchdog-reference.json',
   'examples/openclaw-watchdog-reference.descriptor.example.json',