wendkeep 0.78.0 → 0.80.0

package/hooks/session-stop.mjs

@@ -27,6 +27,11 @@ import {
 import { enqueueMemoryEvent, projectMemoryOutbox } from './memory-store.mjs';
 import { detectMemoryMode } from './memory-mode.mjs';
 import { sanitizeMemoryText } from './memory-schema.mjs';
+import {
+  buildStructuredTaskHandoff,
+  buildTaskContractSnapshot,
+  evaluateTaskContracts,
+} from '../src/task-contracts.mjs';
 import { assertVaultPathSafe } from './vault-path-safety.mjs';
 import {
   projectStopMemoryAttempt,
@@ -1406,6 +1411,40 @@ export async function main({
       summary: finalSummary,
       noteRel: sessionRel,
     });
+    let structuredSharedHandoff = sharedHandoff;
+    const effectiveProfile = String(
+      handoffEvidenceAuthority?.context?.operating_profile_task?.profile
+      || entry?.operating_profile_task?.profile
+      || 'GOVERN',
+    ).toUpperCase();
+    if (handoffEvidenceAuthority?.mode === 'contextual') {
+      try {
+        const taskSnapshot = activeContextChangeSlug
+          ? buildTaskContractSnapshot({
+            vaultBase,
+            projectRoot: input.cwd || process.cwd(),
+            changeSlug: activeContextChangeSlug,
+            identity: handoffEvidenceAuthority.identity,
+          })
+          : null;
+        structuredSharedHandoff = buildStructuredTaskHandoff({
+          profile: effectiveProfile,
+          sessionId,
+          snapshot: taskSnapshot,
+          evaluations: taskSnapshot ? evaluateTaskContracts(taskSnapshot) : [],
+          context: handoffEvidenceAuthority.context,
+          shared: sharedHandoff,
+        });
+      } catch (error) {
+        if (effectiveProfile === 'ASSURE') {
+          const detail = `${error?.code || 'HANDOFF_STRUCTURED_REQUIRED'}: ${error?.message || error}`;
+          process.stderr.write(`[wendkeep] Stop ASSURE bloqueado: ${detail}\n`);
+          writeHookOutput({ systemMessage: `wendkeep: Stop ASSURE exige handoff estruturado: ${detail}` });
+          return;
+        }
+        structuredSharedHandoff = sharedHandoff;
+      }
+    }
     memoryHandoff = {
       projectId,
       identity,
@@ -1418,7 +1457,7 @@ export async function main({
       observedAt: turnIdentity.observedAt || new Date(0).toISOString(),
       summary: finalSummary,
       evidence: memoryEvidence,
-      ...(sharedHandoff ? { shared: sharedHandoff } : {}),
+      ...(structuredSharedHandoff ? { shared: structuredSharedHandoff } : {}),
     };
     memoryAttempt = stageMemory(vaultBase, {
       handoff: memoryHandoff,

package/hooks/spec-core.mjs

@@ -1,11 +1,12 @@
 // hooks/spec-core.mjs — living spec (07-Specs) + change delta merge (OpenSpec native).
-// Pure parsing/merge + promoteSpecs (fs). No import from change-core (avoids a cycle).
-import { createHash } from 'node:crypto';
+// Pure parsing/merge + read-only promotion planning. No import from change-core (avoids a cycle).
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { getLocale } from './locale.mjs';
 import {
-  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, writeVaultFileAtomic, writeVaultFileSync,
+  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath,
+  writeVaultFileAtomic, writeVaultFileSync,
 } from './vault-path-safety.mjs';
 
 // Canonical SHA-256 fingerprint of tarefas.md — freshness binding between package/verdict and gate.
@@ -148,9 +149,20 @@ export function checkSpecsState(vaultBase) {
   return { ok: changed.length === 0, missing: false, changed, current, recorded };
 }
 
-function recordPromotedSpecs(vaultBase, capabilities) {
+function recordPromotedSpecs(vaultBase, capabilities, { writeAtomic = writeVaultFileSync } = {}) {
   const existing = readSpecsState(vaultBase);
-  if (!existing) return adoptSpecsState(vaultBase);
+  if (!existing) {
+    const state = { version: 1, generatedAt: new Date().toISOString(), specs: readLivingSpecs(vaultBase) };
+    mkdirVaultPath(vaultBase, join(vaultBase, '.brain'), { label: 'raiz do estado de specs' });
+    writeAtomic(
+      vaultBase,
+      join(vaultBase, SPECS_STATE_FILE),
+      `${JSON.stringify(state, null, 2)}\n`,
+      'utf8',
+      { label: 'estado consolidado de specs' },
+    );
+    return state;
+  }
   const current = readLivingSpecs(vaultBase);
   const specs = { ...(existing.specs || {}) };
   for (const capability of capabilities) {
@@ -158,7 +170,7 @@ function recordPromotedSpecs(vaultBase, capabilities) {
     else delete specs[capability];
   }
   const state = { version: 1, generatedAt: new Date().toISOString(), specs };
-  writeVaultFileSync(
+  writeAtomic(
     vaultBase,
     join(vaultBase, SPECS_STATE_FILE),
     `${JSON.stringify(state, null, 2)}\n`,
@@ -348,12 +360,10 @@ export function discoverSpecDeltas(changeDir) {
 // per-change (many changes promote into the same file; the per-change record lives in
 // _arquivo). Generated + read-only. Written on init and refreshed on every archive so
 // existing vaults self-heal. Bilingual by vault locale.
-export function ensureSpecsReadme(vaultBase) {
+function specsReadmeBody(vaultBase) {
   const loc = getLocale(vaultBase);
   const en = loc.id === 'en';
-  const dir = join(vaultBase, loc.folders.specs);
-  mkdirVaultPath(vaultBase, dir, { label: 'raiz de specs consolidadas' });
-  const body = en
+  return en
     ? `# Specs — generated living contract
 
 **One file per _capability_, not per change.** Each file is the current, cumulative contract
@@ -382,7 +392,18 @@ Pense como código-fonte vs commits: esta pasta é o *código atual* de cada cap
   \`wendkeep change archive\` promove para esta pasta.
 - Histórico por mudança → \`${loc.folders.changes}/_arquivo/\`. Contrato atual → aqui.
 `;
-  writeVaultFileSync(vaultBase, join(dir, 'README.md'), body, 'utf8', { label: 'README de specs' });
+}
+
+export function renderSpecsReadme(vaultBase) {
+  return specsReadmeBody(vaultBase);
+}
+
+export function ensureSpecsReadme(vaultBase, { writeAtomic = writeVaultFileSync } = {}) {
+  const loc = getLocale(vaultBase);
+  const dir = join(vaultBase, loc.folders.specs);
+  mkdirVaultPath(vaultBase, dir, { label: 'raiz de specs consolidadas' });
+  const body = specsReadmeBody(vaultBase);
+  writeAtomic(vaultBase, join(dir, 'README.md'), body, 'utf8', { label: 'README de specs' });
 }
 
 export function assertSpecPromotionTargetsSafe(vaultBase, changeDir, specs) {
@@ -426,8 +447,14 @@ export function assertSpecPromotionTargetsSafe(vaultBase, changeDir, specs) {
   return { specsRoot: checkedRoot.target };
 }
 
-// Merge each capability's delta (in the change) into the living spec in 07-Specs.
-export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, dateStr } = {}) {
+// Derive the immutable before/postimage plan used by the archive CLI. This helper
+// is deliberately read-only: publication is private to src/change.mjs, after the
+// provenance gate, receipt, recapture, and operation lock have all succeeded.
+export function buildSpecPromotionPlan(vaultBase, changeDir, specs, {
+  changeWikilink,
+  dateStr,
+  recoveryRoot,
+} = {}) {
   const loc = getLocale(vaultBase);
   const specsDir = loc.folders.specs;
   const promoted = [];
@@ -459,25 +486,62 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
       content: renderSpec(cap, applied.reqs, { footer, reqHeading: loc.reqHeading }),
     });
   }
-  mkdirVaultPath(vaultBase, specsRoot, { label: 'raiz de specs consolidadas' });
+  const statePath = join(vaultBase, SPECS_STATE_FILE);
+  const readmePath = join(specsRoot, 'README.md');
+  const existingState = readSpecsState(vaultBase);
+  const nextSpecs = existingState ? { ...(existingState.specs || {}) } : readLivingSpecs(vaultBase);
   for (const item of materialized) {
-    writeVaultFileSync(
-      vaultBase,
-      item.livePath,
-      item.content,
-      'utf8',
-      { label: `spec consolidada ${item.capability}` },
-    );
-    promoted.push(item.capability);
+    nextSpecs[item.capability] = {
+      hash: contentHashOf(item.content),
+      requirements: Object.fromEntries(parseRequirements(item.content)
+        .map((requirement) => [requirement.id || requirement.name, contentHashOf(JSON.stringify(requirement))])),
+    };
   }
-  recordPromotedSpecs(vaultBase, promoted);
-  ensureSpecsReadme(vaultBase); // self-heal the explainer so existing vaults get it on archive
-  return { promoted, warnings };
+  const stateContent = `${JSON.stringify({
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    specs: nextSpecs,
+  }, null, 2)}\n`;
+  const planned = [
+    ...materialized.map((item) => ({
+      kind: 'capability', capability: item.capability, path: item.livePath, content: item.content,
+    })),
+    { kind: 'state', path: statePath, content: stateContent },
+    { kind: 'readme', path: readmePath, content: specsReadmeBody(vaultBase) },
+  ];
+  const image = (content, exists = true) => ({
+    exists,
+    content_base64: Buffer.from(content, 'utf8').toString('base64'),
+    digest: `sha256:${contentHashOf(content)}`,
+  });
+  const promotionRecoveryRoot = recoveryRoot
+    || join(vaultBase, '.brain', 'runtime', 'spec-promotion-plans', randomUUID());
+  const plan = {
+    schema_version: 1,
+    entries: planned.map((entry, index) => {
+      const beforeExists = existsSync(entry.path);
+      const beforeContent = beforeExists ? readFileSync(entry.path, 'utf8') : '';
+      return {
+        kind: entry.kind,
+        capability: entry.capability || null,
+        target: relative(vaultBase, entry.path).replaceAll('\\', '/'),
+        claim_target: relative(vaultBase, join(promotionRecoveryRoot, `${index}-${randomUUID()}.before`)).replaceAll('\\', '/'),
+        candidate_target: relative(vaultBase, join(promotionRecoveryRoot, `${index}-${randomUUID()}.candidate`)).replaceAll('\\', '/'),
+        before: image(beforeContent, beforeExists),
+        after: image(entry.content, true),
+      };
+    }),
+  };
+  const changes = materialized.map((item) => ({
+    capability: item.capability,
+    before_digest: plan.entries.find((entry) => entry.capability === item.capability).before.digest,
+    after_digest: `sha256:${contentHashOf(item.content)}`,
+  }));
+  plan.changes = changes;
+  promoted.push(...materialized.map((item) => item.capability));
+  return { promoted, warnings, changes, plan };
 }
 
-// Gate check for the independent verdict (Wave A). A requirement-bearing change must have
-// a verdict that is ok and covers every declared req id. A requirement-less change passes:
-// nothing for an independent verifier to check — the sensor gate is already the proof.
 export function evaluateVerdict(verdict, reqIds, {
   tasksHash,
   effectiveSpecHash,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "precheck": "node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs",
+    "precheck": "node --check src/task-contracts.mjs && node --check src/task-leases.mjs && node --check src/task.mjs && node --check src/change.mjs && node --check src/archive-operation-lock.mjs && node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/provenance-gate.mjs && node --check src/provenance-sources.mjs && node --check src/receipt-ledger.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check hooks/session-stop.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs && node --check packages/vault/src/memory-handoff.mjs",
     "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",

package/packages/cli/src/index.mjs

@@ -64,6 +64,8 @@ Usage:
   wendkeep context repair --key <repository:worktree:work-session> --revision <n> --reason <text> --session <id> [--json]
                            Inspect or explicitly recover a quarantined causal scope conflict.
                            Repair revalidates orphan/removed contexts or expired request leases without deleting history.
+  wendkeep task <sub>          Typed task contracts: list | show | evaluate | claim | release.
+                           Resolves the change from the causal active context; supports --session/--change/--json.
   wendkeep change <sub>        Change lifecycle: new [--simple|--guide] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            --session <id> selects the causal active_context for implicit change operations.
@@ -292,6 +294,11 @@ async function main(argv) {
       runChange(rest);
       break;
     }
+    case 'task': {
+      const { runTask } = await import('../../../src/task.mjs');
+      process.exit(runTask(rest));
+      break;
+    }
     case 'session': {
       const { runSession } = await import('../../../src/session.mjs');
       runSession(rest);

package/packages/vault/src/memory-handoff.mjs

@@ -61,6 +61,10 @@ export function normalizeSharedHandoff(shared) {
     const value = sanitizeValue(shared[field]);
     if (hasMeaningfulValue(value)) normalized[field] = value;
   }
+  if (Object.hasOwn(shared, 'handoff_contract')) {
+    const contract = sanitizeValue(shared.handoff_contract);
+    if (hasMeaningfulValue(contract)) normalized.handoff_contract = contract;
+  }
 
   return Object.keys(normalized).length ? normalized : null;
 }
@@ -257,6 +261,17 @@ export function buildSessionMemoryEvents({
   const events = [];
 
   if (normalizedShared) {
+    if (normalizedShared.handoff_contract) {
+      const contract = normalizedShared.handoff_contract;
+      events.push(makeEvent(context, {
+        memoryKey: 'handoff.latest',
+        value: contract,
+        authority: contract.schema_version === 1 && contract.authority === 'verified'
+          ? 'verified' : 'reported',
+        evidence: Array.isArray(contract.evidence) && contract.evidence.length
+          ? contract.evidence : [noteRel],
+      }));
+    }
     for (const [field, memoryKey] of SHARED_HANDOFF_FIELDS) {
       if (!Object.hasOwn(normalizedShared, field)) continue;
       events.push(makeEvent(context, {

package/schema/artifact-manifest-v1.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/artifact-manifest-v1.schema.json",
+  "title": "WendKeep Artifact Manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "artifacts"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artifact" }
+    }
+  },
+  "$defs": {
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+        "type": { "enum": ["name", "path", "glob", "file-count"] },
+        "path": { "type": "string" },
+        "glob": { "type": "string" },
+        "min": { "type": "integer", "minimum": 0 },
+        "max": { "type": "integer", "minimum": 0 },
+        "fromFilesystem": { "type": "boolean" }
+      },
+      "allOf": [
+        { "if": { "properties": { "type": { "const": "path" } } }, "then": { "required": ["path"] } },
+        { "if": { "properties": { "type": { "enum": ["glob", "file-count"] } } }, "then": { "required": ["glob"] } }
+      ]
+    }
+  }
+}

package/schema/handoff-contract-v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/handoff-contract-v1.schema.json",
+  "title": "WendKeep Handoff Contract v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version", "handoff_id", "from", "to", "active_context_id", "task_id",
+    "task_contract_id", "artifacts", "evidence", "decisions", "next_actions", "blockers",
+    "head_sha", "tasks_sha256", "spec_sha256", "authority"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "handoff_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "from": { "type": "string", "minLength": 1 },
+    "to": { "type": "string", "minLength": 1 },
+    "active_context_id": { "type": "string", "minLength": 1 },
+    "task_id": { "type": "string" },
+    "task_contract_id": { "type": "string" },
+    "artifacts": { "$ref": "#/$defs/stringArray" },
+    "evidence": { "$ref": "#/$defs/stringArray" },
+    "decisions": { "$ref": "#/$defs/stringArray" },
+    "next_actions": { "$ref": "#/$defs/stringArray" },
+    "blockers": { "$ref": "#/$defs/stringArray" },
+    "head_sha": { "type": "string", "minLength": 1 },
+    "tasks_sha256": { "type": "string", "minLength": 1 },
+    "spec_sha256": { "type": "string", "minLength": 1 },
+    "authority": { "enum": ["verified", "reported"] }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    }
+  }
+}

package/schema/task-contract-v1.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/task-contract-v1.schema.json",
+  "title": "WendKeep Task Contract v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version", "contract_id", "task_id", "change_slug", "title", "phase", "status",
+    "inputs", "expected_outputs", "acceptance_criteria", "requirement_ids",
+    "required_sensors", "required_artifacts", "dependencies", "owner", "work_session_id",
+    "evidence_envelope_id", "checked", "authored_sha256", "binding"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "contract_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "task_id": { "type": "string", "minLength": 1 },
+    "change_slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "title": { "type": "string" },
+    "phase": { "enum": ["execute", "verify"] },
+    "status": { "enum": ["ready", "blocked", "pending-evaluation", "completed", "stale"] },
+    "inputs": { "$ref": "#/$defs/stringArray" },
+    "expected_outputs": { "$ref": "#/$defs/stringArray" },
+    "acceptance_criteria": { "$ref": "#/$defs/stringArray" },
+    "requirement_ids": { "$ref": "#/$defs/stringArray" },
+    "required_sensors": { "$ref": "#/$defs/stringArray" },
+    "required_artifacts": { "$ref": "#/$defs/stringArray" },
+    "dependencies": { "$ref": "#/$defs/stringArray" },
+    "owner": { "type": ["string", "null"] },
+    "work_session_id": { "type": ["string", "null"] },
+    "evidence_envelope_id": { "type": ["string", "null"] },
+    "checked": { "type": "boolean" },
+    "authored_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "binding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "project_id", "active_context_id", "head_sha", "tasks_sha256",
+        "effective_spec_sha256", "artifact_manifest_sha256"
+      ],
+      "properties": {
+        "project_id": { "type": "string", "minLength": 1 },
+        "active_context_id": { "type": "string", "minLength": 1 },
+        "head_sha": { "type": "string", "minLength": 1 },
+        "tasks_sha256": { "type": "string", "minLength": 1 },
+        "effective_spec_sha256": { "type": "string", "minLength": 1 },
+        "artifact_manifest_sha256": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    }
+  }
+}

package/schema/wendkeep.provenance-receipt-v2.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/rogersialves/wendkeep/blob/main/schema/wendkeep.provenance-receipt-v2.schema.json",
+  "title": "WendKeep Provenance Receipt v2",
+  "description": "A canonical, hash-chained receipt for a provenance-gated operation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "sequence",
+    "receipt_id",
+    "previous_hash",
+    "receipt_hash",
+    "kind",
+    "subject",
+    "claims",
+    "observations",
+    "recorded_at"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 2
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "receipt_id": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "previous_hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Hash of the previous v2 receipt, or the canonical legacy/empty prefix for genesis."
+    },
+    "receipt_hash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 of the canonical receipt without receipt_hash."
+    },
+    "kind": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9._-]{1,63}$"
+    },
+    "subject": {
+      "type": "object",
+      "description": "Sanitized identity and current operation target.",
+      "additionalProperties": true
+    },
+    "claims": {
+      "type": "object",
+      "description": "Sanitized claims made by the operation.",
+      "additionalProperties": true
+    },
+    "observations": {
+      "type": "object",
+      "description": "Sanitized source observations keyed by adapter/kind.",
+      "additionalProperties": true
+    },
+    "recorded_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}