docs: define modular local agent contracts

README.md

@@ -14,3 +14,11 @@ The pack is source material for a dedicated research workspace. Keep the complet
 | [kb-synthesize](skills/kb-synthesize/SKILL.md) | Build a synthesis with revision-bound dependencies. |
 
 The [manifest](manifest.json) records versions and explicit compatibility status. Pending service compatibility means no connected workflow is claimed. Until tools exist, requested local drafts stay under the selected workspace's `Drafts/` and remain unaccepted; no canonical writes or fabricated receipts are permitted.
+
+The manifest's `modules` array is the authoritative descriptor registry for the profile, protocols, skills and pipelines. Each entry identifies its implementation, provided/required instruction contracts, compatible checkpoint contract and exact file hash. Its snapshot digest covers that array using the declared canonical serialization. Recompute hashes and the snapshot after changing a module; any published pack change requires a new pack version. The entry lists above are discovery indexes and must agree with the registry.
+
+For portable Markdown hashing, decode UTF-8, remove an optional BOM and normalize CRLF/CR line endings to LF, then hash the UTF-8 bytes with SHA-256. Preserve every other character and the final newline. This keeps Windows checkout conversion from changing instruction identity; it is not a signature or proof of trusted origin.
+
+Checkpoint contract `gewu.local-checkpoint@0.1.0` requires run identity, explicit scope/objective, snapshot digest, resolved module contract IDs and file hashes, host/model metadata where available, input/output hashes, stage, coverage, budgets, pending operation identities and last service receipt. Unavailable service fields are explicitly absent; they are never fabricated. This is a draft instruction contract, not an executable checkpoint validator. Resume must verify the saved snapshot and hashes before using saved stages. A successor run requires explicit contract compatibility and downstream revalidation.
+
+Empty service-capability lists mean schema binding is pending, as declared by `service_capability_status`; they do not mean connected workflows need no capabilities. Bind and test those requirements when the service schemas exist. Host-adapter descriptors belong to a future installer/configuration implementation and are not supplied by this pack.

manifest.json

@@ -18,9 +18,325 @@
     "contributions": "protocols/CONTRIBUTIONS.md"
   },
   "skills": [
-    {"id": "kb-ingest", "version": "0.1.0", "entry": "skills/kb-ingest/SKILL.md", "pipeline": "pipelines/ingest.md", "pipeline_version": "0.1.0"},
+    {
-    {"id": "kb-query", "version": "0.1.0", "entry": "skills/kb-query/SKILL.md", "pipeline": "pipelines/query.md", "pipeline_version": "0.1.0"},
+      "id": "kb-ingest",
-    {"id": "kb-curate", "version": "0.1.0", "entry": "skills/kb-curate/SKILL.md", "pipeline": "pipelines/curate.md", "pipeline_version": "0.1.0"},
+      "version": "0.1.0",
-    {"id": "kb-synthesize", "version": "0.1.0", "entry": "skills/kb-synthesize/SKILL.md", "pipeline": "pipelines/synthesize.md", "pipeline_version": "0.1.0"}
+      "entry": "skills/kb-ingest/SKILL.md",
-  ]
+      "pipeline": "pipelines/ingest.md",
+      "pipeline_version": "0.1.0"
+    },
+    {
+      "id": "kb-query",
+      "version": "0.1.0",
+      "entry": "skills/kb-query/SKILL.md",
+      "pipeline": "pipelines/query.md",
+      "pipeline_version": "0.1.0"
+    },
+    {
+      "id": "kb-curate",
+      "version": "0.1.0",
+      "entry": "skills/kb-curate/SKILL.md",
+      "pipeline": "pipelines/curate.md",
+      "pipeline_version": "0.1.0"
+    },
+    {
+      "id": "kb-synthesize",
+      "version": "0.1.0",
+      "entry": "skills/kb-synthesize/SKILL.md",
+      "pipeline": "pipelines/synthesize.md",
+      "pipeline_version": "0.1.0"
+    }
+  ],
+  "checkpoint_contract": {
+    "id": "gewu.local-checkpoint",
+    "version": "0.1.0",
+    "status": "draft-instruction-contract"
+  },
+  "modules": [
+    {
+      "module_id": "profile",
+      "kind": "profile",
+      "entry": "AGENTS.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.profile.profile",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0",
+        "gewu.skill.kb-ingest@0.1.0",
+        "gewu.skill.kb-query@0.1.0",
+        "gewu.skill.kb-curate@0.1.0",
+        "gewu.skill.kb-synthesize@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "2bb326e760704bb555238f2d3e04e7cc238f01f6f281f21824f8196e700a30ef",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "evidence",
+      "kind": "protocol",
+      "entry": "protocols/EVIDENCE.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.protocol.evidence",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "9b7316c02d82608c34d24d1d69f24016c33ba966373cb57e9b90b70ba76ac865",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "scope",
+      "kind": "protocol",
+      "entry": "protocols/SCOPE.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.protocol.scope",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "521691d9739829b6ed64b8259a2768385c52e6a5f396bcd0b7800d33d5e8cd83",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "contributions",
+      "kind": "protocol",
+      "entry": "protocols/CONTRIBUTIONS.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.protocol.contributions",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "f66e7c97036c85f0ceeaba69caf54720ea8d98021fda73bc4a7c9667775d8387",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-ingest",
+      "kind": "skill",
+      "entry": "skills/kb-ingest/SKILL.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.skill.kb-ingest",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0",
+        "gewu.pipeline.kb-ingest-pipeline@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "b0abe4d6db8020f16e86789fa409a19fda1e7385882172d84e3cc430ed4e7b6d",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-ingest-pipeline",
+      "kind": "pipeline",
+      "entry": "pipelines/ingest.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.pipeline.kb-ingest-pipeline",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "ebdb65bfdb331eae1c5d0618caebac4585287c5057d64307b57b1ae7bd404962",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-query",
+      "kind": "skill",
+      "entry": "skills/kb-query/SKILL.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.skill.kb-query",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0",
+        "gewu.pipeline.kb-query-pipeline@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "e2e1986d0c4ffc76982e76a9976f290e6eed18e469fc682acbeed898ef30775c",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-query-pipeline",
+      "kind": "pipeline",
+      "entry": "pipelines/query.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.pipeline.kb-query-pipeline",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "d78cbb2e5cb691704a7b5300856d053801b1aeaa06e6b45cb442959413735d64",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-curate",
+      "kind": "skill",
+      "entry": "skills/kb-curate/SKILL.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.skill.kb-curate",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0",
+        "gewu.pipeline.kb-curate-pipeline@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "ed49d08d581c92c26755944e931665e197074f32c33f44b462208398ec50e515",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-curate-pipeline",
+      "kind": "pipeline",
+      "entry": "pipelines/curate.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.pipeline.kb-curate-pipeline",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "665a51f5c42a81cf37aaccfc7791b494f487fc3aa70cf8d6cfd9437dc8bfcff1",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-synthesize",
+      "kind": "skill",
+      "entry": "skills/kb-synthesize/SKILL.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.skill.kb-synthesize",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0",
+        "gewu.pipeline.kb-synthesize-pipeline@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "444433c4c5dc4f22183a4987edc38982868b6bf70e578b59303eb8c4fcf26b9c",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "kb-synthesize-pipeline",
+      "kind": "pipeline",
+      "entry": "pipelines/synthesize.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.pipeline.kb-synthesize-pipeline",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [
+        "gewu.protocol.evidence@0.1.0",
+        "gewu.protocol.scope@0.1.0",
+        "gewu.protocol.contributions@0.1.0"
+      ],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "d8fdd640d4d2bfa2556eb676274f2bae9e6e70e6a760bac586e17f870be501cb",
+      "hash_encoding": "utf8-no-bom-lf"
+    },
+    {
+      "module_id": "checkpoint-guide",
+      "kind": "guide",
+      "entry": "README.md",
+      "implementation_version": "0.1.0",
+      "provided_contract": {
+        "id": "gewu.local-checkpoint",
+        "version": "0.1.0"
+      },
+      "requires_contracts": [],
+      "required_service_capabilities": [],
+      "service_capability_status": "unbound-service-schema-pending",
+      "compatible_checkpoint_contracts": [
+        "gewu.local-checkpoint@0.1.0"
+      ],
+      "sha256": "3557c41c1db1892eeaa1f5bd3b8061e8c13b828bc6c608273836448ec2842fe4",
+      "hash_encoding": "utf8-no-bom-lf"
+    }
+  ],
+  "snapshot": {
+    "algorithm": "sha256",
+    "scope": "modules array serialized as UTF-8 JSON with sorted keys and compact separators",
+    "digest": "d968ab13ec3492452842f88feba763b928ece50464dddea0e2cadb91425ca6c4"
+  }
 }

protocols/CONTRIBUTIONS.md

@@ -6,6 +6,8 @@ Use read tools for retrieval and typed MCP proposals for contributions. Source u
 
 Before a connected operation, persist run/operation identity and input digest in a local checkpoint, then associate service run/proposal IDs as returned. Checkpoints include pack/skill/pipeline versions and hashes, scope, source/extraction references, stage, output hashes, coverage, pending side effects and last receipt. Exclude secrets. Use the host's available safe file tools; these instructions alone do not establish atomic journaling or a durable scheduler.
 
+Use the checkpoint contract in the [pack README](../README.md) and resolve the module registry in the manifest. Record its snapshot digest and every applicable module's contract ID/version and file hash, including the profile and shared protocols. Verify those hashes before resuming; a mismatch requires the original snapshot or an explicitly revalidated successor run.
+
 When a result is uncertain, query upload/proposal/run status using the same operation identity before retrying. Never generate a fresh proposal ID to hide network uncertainty. Resume from preserved artifacts and service receipts; changed content requires a new revision. Do not rerun a model and assume it reproduces the same output.
 
 Bound work by source/batch size, stage/model budget and correction attempts. After two unchanged validation failures, stop for diagnosis and report findings. Coverage/skips remain explicit at any stop. Cancellation cannot undo an accepted proposal; check status when a call may have completed.