productfoo 0.0.0-stage → 1.0.1

package/schemas/bug-capsule.schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://foo.example/schemas/bug-capsule.schema.json",
+  "title": "BugCapsule 0.1",
+  "type": "object",
+  "required": ["schema_version", "capsule_id", "occurred_at", "producer", "product", "invocation", "failure", "report", "evidence", "similarity", "links", "extensions"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "capsule_id": { "$ref": "#/$defs/uuidV7" },
+    "occurred_at": { "$ref": "#/$defs/rfc3339Utc" },
+    "producer": { "$ref": "#/$defs/producer" },
+    "product": { "$ref": "#/$defs/product" },
+    "invocation": { "$ref": "#/$defs/invocation" },
+    "failure": { "$ref": "#/$defs/failure" },
+    "report": { "$ref": "#/$defs/report" },
+    "evidence": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "$ref": "#/$defs/evidence" }
+    },
+    "similarity": { "$ref": "#/$defs/similarity" },
+    "links": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "$ref": "#/$defs/link" }
+    },
+    "extensions": { "$ref": "#/$defs/extensions" }
+  },
+  "$defs": {
+    "string": { "type": "string", "maxLength": 4096 },
+    "uuidV7": {
+      "type": "string",
+      "maxLength": 4096,
+      "format": "uuid",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "rfc3339Utc": {
+      "type": "string",
+      "maxLength": 4096,
+      "format": "date-time",
+      "pattern": "^(?:\\d{4})-(?:\\d{2})-(?:\\d{2})T(?:\\d{2}):(?:\\d{2}):(?:\\d{2})(?:\\.\\d+)?Z$"
+    },
+    "fieldValue": {
+      "type": "object",
+      "required": ["state"],
+      "additionalProperties": false,
+      "properties": {
+        "state": { "enum": ["collected", "not_collected", "withheld", "unavailable"] },
+        "value": { "$ref": "#/$defs/string" },
+        "reason": { "$ref": "#/$defs/string" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "state": { "const": "collected" } }, "required": ["state"] },
+          "then": { "required": ["value"], "not": { "required": ["reason"] } },
+          "else": { "required": ["reason"], "not": { "required": ["value"] } }
+        }
+      ]
+    },
+    "producer": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": { "name": { "$ref": "#/$defs/string" }, "version": { "$ref": "#/$defs/string" } }
+    },
+    "product": {
+      "type": "object",
+      "required": ["name", "component", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "$ref": "#/$defs/string" },
+        "component": { "$ref": "#/$defs/string" },
+        "version": { "$ref": "#/$defs/string" }
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "required": ["command", "runtime"],
+      "additionalProperties": false,
+      "properties": {
+        "command": { "$ref": "#/$defs/string" },
+        "runtime": {
+          "type": "object",
+          "required": ["node", "platform", "arch"],
+          "additionalProperties": false,
+          "properties": {
+            "node": { "$ref": "#/$defs/string" },
+            "platform": { "$ref": "#/$defs/string" },
+            "arch": { "$ref": "#/$defs/string" }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "required": ["class", "code", "classifier_version", "classification", "message", "stack"],
+      "additionalProperties": false,
+      "properties": {
+        "class": { "enum": ["none", "usage_error", "gate_block", "not_found", "io_error", "command_error"] },
+        "code": {
+          "enum": ["E_COMMAND_MISSING", "E_PACKET_DIR_MISSING", "E_SWARM_TARGET_MISSING", "E_IDEATE_IDEA_MISSING", "E_SPEC_WORK_MISSING", "E_UNKNOWN_DOMAIN", "E_BAD_FLAG", "E_NOT_A_RESEARCH_PAPER", "E_PACKET_NOT_FOUND", "E_SPEC_NOT_FOUND", "E_SKILL_NOT_FOUND", "E_GATE_B1_SECRET", "E_GATE_B2_SPEC_ID", "E_GATE_B4_BUDGET", "E_GATE_B5_UNGOVERNED", "E_GATE_B5_CLAIM_UNLABELED", "E_GATE_BLOCKED", "E_GATE_INTERVIEW", "E_CONTRACT_DRIFT", "E_IO", "E_UNKNOWN"]
+        },
+        "classifier_version": { "const": "0.1" },
+        "classification": { "enum": ["known", "fallback"] },
+        "message": { "$ref": "#/$defs/fieldValue" },
+        "stack": { "$ref": "#/$defs/fieldValue" }
+      }
+    },
+    "report": {
+      "type": "object",
+      "required": ["expected", "actual", "reproduction"],
+      "additionalProperties": false,
+      "properties": {
+        "expected": { "$ref": "#/$defs/fieldValue" },
+        "actual": { "$ref": "#/$defs/fieldValue" },
+        "reproduction": { "$ref": "#/$defs/fieldValue" }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["kind", "state", "content_type"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["diagnostic", "user_report"] },
+        "state": { "enum": ["collected", "not_collected", "withheld", "unavailable"] },
+        "content_type": { "$ref": "#/$defs/string" }
+      }
+    },
+    "similarity": {
+      "type": "object",
+      "required": ["version", "signals"],
+      "additionalProperties": false,
+      "properties": {
+        "version": { "const": "0.1" },
+        "signals": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "type": "object",
+            "required": ["kind", "value"],
+            "additionalProperties": false,
+            "properties": {
+              "kind": { "const": "error_fingerprint" },
+              "value": { "$ref": "#/$defs/string" }
+            }
+          }
+        }
+      }
+    },
+    "link": {
+      "type": "object",
+      "required": ["relation", "provider", "external_id", "provenance", "authority"],
+      "additionalProperties": false,
+      "properties": {
+        "relation": { "$ref": "#/$defs/string" },
+        "provider": { "$ref": "#/$defs/string" },
+        "external_id": { "$ref": "#/$defs/string" },
+        "provenance": { "const": "reporter_observed" },
+        "authority": { "const": "reference" }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "properties": {
+        "foo": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "spec_context": {
+              "type": "object",
+              "required": ["spec_id", "packet_path", "requirement_ids", "task_ids", "provenance"],
+              "additionalProperties": false,
+              "properties": {
+                "spec_id": { "$ref": "#/$defs/string" },
+                "packet_path": { "$ref": "#/$defs/string" },
+                "revision": { "$ref": "#/$defs/string" },
+                "requirement_ids": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/string" } },
+                "task_ids": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/string" } },
+                "provenance": { "const": "reporter_observed" }
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/discovery-evidence-envelope.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "foo://specs/nango-discovery-connector-v0/discovery-evidence-envelope.schema.json",
+  "title": "productfoo discovery evidence envelope (closed)",
+  "description": "The sanitized evidence envelope produced by hosted processing. Mirrors src/discoveryEvidence.ts: closed key sets, no raw content, no PII, no injection patterns (nango-discovery-connector-v0 V-015). The source_fingerprint grammar is validated by the receiving apply path (T-005's versioned grammar) and is only required non-empty here.",
+  "type": "object",
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "kind": { "const": "discovery_evidence" },
+    "study_id": { "type": "string", "minLength": 1 },
+    "lane": { "enum": ["study_linked", "unassigned_call_evidence"] },
+    "source": {
+      "type": "object",
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "stable_url": { "type": "string", "minLength": 1 },
+        "source_fingerprint": { "type": "string", "minLength": 1 },
+        "completed_at": { "type": "string", "minLength": 1 },
+        "locator_capability": { "enum": ["timestamp", "section", "none"] }
+      },
+      "required": ["provider", "source_fingerprint", "completed_at", "locator_capability"],
+      "additionalProperties": false
+    },
+    "findings": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "finding_id": { "type": "string", "minLength": 1 },
+          "headline": { "type": "string", "minLength": 1 },
+          "paraphrase": { "type": "string", "minLength": 1 },
+          "evidence_type": { "enum": ["stated", "observed", "inferred"] },
+          "locator": { "type": "string", "minLength": 1 },
+          "confidence": { "enum": ["low", "medium", "high"] },
+          "dissent": { "type": "string" },
+          "hypothesis_id": { "type": "string", "minLength": 1 },
+          "explicit_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "relationship_hint": { "enum": ["supports", "contradicts", "new"] }
+        },
+        "required": ["finding_id", "headline", "paraphrase", "evidence_type", "confidence", "dissent"],
+        "additionalProperties": false
+      }
+    },
+    "contact_candidates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "company": { "type": "string", "minLength": 1 },
+          "title": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "properties": {
+        "transcript_complete": { "type": "boolean" },
+        "caveats": { "type": "array", "items": { "type": "string" } }
+      },
+      "required": ["transcript_complete", "caveats"],
+      "additionalProperties": false
+    },
+    "privacy_attestation": {
+      "type": "object",
+      "properties": {
+        "pii_redacted": { "const": true },
+        "direct_quotes": { "const": false }
+      },
+      "required": ["pii_redacted", "direct_quotes"],
+      "additionalProperties": false
+    },
+    "raw_content_present": { "const": false }
+  },
+  "required": ["schema_version", "kind", "study_id", "lane", "source", "findings", "coverage", "privacy_attestation", "raw_content_present"],
+  "additionalProperties": false
+}

package/schemas/discovery-processing-receipt.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "foo://specs/nango-discovery-connector-v0/discovery-processing-receipt.schema.json",
+  "title": "productfoo discovery processing receipt (signed, payload-free)",
+  "description": "The signed trust envelope that attests one discovery processing attempt: its authorization bindings, source identity, and the envelope hash it covers. Carries no evidence payload and no provider content (nango-discovery-connector-v0 R-007, V-015). Payload closure mirrors the DiscoveryProcessingReceiptPayload type in src/discoveryProcess.ts.",
+  "type": "object",
+  "properties": {
+    "namespace": { "const": "foo" },
+    "artifact_kind": { "const": "discovery-processing-receipt" },
+    "artifact_id": { "type": "string", "pattern": "^att:[a-f0-9]{16,64}$" },
+    "key_id": { "type": "string", "minLength": 1 },
+    "issued_at": { "type": "string", "minLength": 1 },
+    "not_before": { "type": "string", "minLength": 1 },
+    "expires_at": { "type": "string", "minLength": 1 },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "previous_hash": { "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "payload": { "$ref": "#/$defs/receiptPayload" },
+    "signature": { "type": "string", "minLength": 1 }
+  },
+  "required": ["namespace", "artifact_kind", "artifact_id", "key_id", "issued_at", "not_before", "expires_at", "sequence", "previous_hash", "payload", "signature"],
+  "additionalProperties": false,
+  "$defs": {
+    "receiptPayload": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "discovery_processing_receipt" },
+        "receipt_version": { "const": "v1" },
+        "subject_ref": { "type": "string", "minLength": 1 },
+        "workspace_ref": { "type": "string", "minLength": 1 },
+        "connection_ref": { "type": "string", "pattern": "^conn:[a-z0-9][a-z0-9.-]*$" },
+        "target_ref": { "type": "string", "pattern": "^dtarget:[a-z0-9][a-z0-9.-]*$" },
+        "target_id": { "type": "string", "minLength": 1 },
+        "lane": { "enum": ["study", "inbox"] },
+        "source_fingerprint": { "type": "string", "minLength": 1 },
+        "approval_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+        "grant_digest": { "type": "string", "minLength": 1 },
+        "revocation_epoch": { "type": "integer", "minimum": 0 },
+        "envelope_hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+        "attempt_id": { "type": "string", "pattern": "^att:[a-f0-9]{16,64}$" },
+        "processing": {
+          "type": "object",
+          "properties": {
+            "processing_version": { "type": "string", "minLength": 1 },
+            "prompt_version": { "type": "string", "minLength": 1 },
+            "policy_version": { "type": "string", "minLength": 1 },
+            "synthesizer_model": { "type": "string", "minLength": 1 },
+            "envelope_schema_version": { "const": "0.1" }
+          },
+          "required": ["processing_version", "prompt_version", "policy_version", "synthesizer_model", "envelope_schema_version"],
+          "additionalProperties": false
+        },
+        "limits": {
+          "type": "object",
+          "properties": {
+            "max_response_bytes": { "type": "integer", "minimum": 1 },
+            "fetch_timeout_ms": { "type": "integer", "minimum": 1 },
+            "max_model_input_tokens": { "type": "integer", "minimum": 1 }
+          },
+          "required": ["max_response_bytes", "fetch_timeout_ms", "max_model_input_tokens"],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "kind", "receipt_version", "subject_ref", "workspace_ref", "connection_ref", "target_ref", "target_id",
+        "lane", "source_fingerprint", "approval_digest", "grant_digest", "revocation_epoch", "envelope_hash",
+        "attempt_id", "processing", "limits"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/discovery-service-contract.schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "foo://specs/nango-discovery-connector-v0/discovery-service-contract.schema.json",
+  "title": "productfoo discovery service result (closed union)",
+  "description": "The complete result surface a productfoo host can receive from the discovery service (readiness, listing, processing). additionalProperties is false at every level; the fields an operation/status cannot carry are forbidden explicitly (nango-discovery-connector-v0 V-015). A discovery_process_session result in the needs_local_apply state (T-006) is the one non-success variant that carries the signed sanitized pair: envelope plus processing_receipt behind a portable_bundle handoff with requires_human true — productfoo retains no copy of that bundle. Coverage for the processing operation is closed; readiness and listing coverage stays the open record shipped by T-003.",
+  "type": "object",
+  "properties": {
+    "schema_version": { "const": "0.1" },
+    "operation": { "enum": ["discovery_connection_ready", "discovery_list_sessions", "discovery_process_session"] },
+    "status": {
+      "description": "The packet's 22 stable states — flow (ready, processed, clean_no_op, needs_local_apply, needs_review), blocked/handoff (not_connected, needs_source_approval, needs_service_grant, needs_provider_access, needs_provider_connector, awaiting_match, ambiguous_match, needs_research_proof, needs_service_verification, revocation_pending), and failure (auth_expired, result_lost, transcript_too_large, provider_timeout, revoked, budget_exhausted, invalid).",
+      "enum": [
+        "ready", "processed", "clean_no_op", "needs_local_apply", "needs_review",
+        "not_connected", "needs_source_approval", "needs_service_grant", "needs_provider_access", "needs_provider_connector",
+        "awaiting_match", "ambiguous_match", "needs_research_proof", "needs_service_verification", "revocation_pending",
+        "auth_expired", "result_lost", "transcript_too_large", "provider_timeout", "revoked",
+        "budget_exhausted", "invalid"
+      ]
+    },
+    "errors": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/serviceError" }
+    },
+    "handoff": {
+      "anyOf": [{ "$ref": "#/$defs/handoff" }, { "type": "null" }]
+    },
+    "next_actions": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "coverage": { "type": "object" },
+    "capabilities": { "$ref": "#/$defs/capabilities" },
+    "connection_ref": { "type": "string", "pattern": "^conn:[a-z0-9][a-z0-9.-]*$" },
+    "target_ref": { "type": "string", "pattern": "^dtarget:[a-z0-9][a-z0-9.-]*$" },
+    "stable_url": { "type": "string", "minLength": 1 },
+    "sessions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/listedSession" }
+    },
+    "envelope": { "$ref": "foo://specs/nango-discovery-connector-v0/discovery-evidence-envelope.schema.json" },
+    "processing_receipt": { "$ref": "foo://specs/nango-discovery-connector-v0/discovery-processing-receipt.schema.json" }
+  },
+  "required": ["schema_version", "operation", "status", "errors", "handoff", "next_actions", "coverage"],
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": { "properties": { "operation": { "const": "discovery_connection_ready" } }, "required": ["operation"] },
+      "then": {
+        "properties": {
+          "sessions": false,
+          "stable_url": false,
+          "envelope": false,
+          "processing_receipt": false
+        }
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "discovery_list_sessions" } }, "required": ["operation"] },
+      "then": {
+        "properties": { "stable_url": false, "envelope": false, "processing_receipt": false },
+        "required": ["sessions"]
+      }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "discovery_process_session" } }, "required": ["operation"] },
+      "then": {
+        "properties": { "capabilities": false, "sessions": false },
+        "required": ["connection_ref", "target_ref"]
+      }
+    },
+    {
+      "if": {
+        "properties": { "operation": { "const": "discovery_process_session" }, "status": { "const": "processed" } },
+        "required": ["operation", "status"]
+      },
+      "then": {
+        "required": ["envelope", "processing_receipt", "connection_ref", "target_ref"],
+        "properties": {
+          "coverage": { "$ref": "#/$defs/processingCoverage" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "operation": { "const": "discovery_process_session" }, "status": { "const": "needs_local_apply" } },
+        "required": ["operation", "status"]
+      },
+      "then": {
+        "required": ["envelope", "processing_receipt", "connection_ref", "target_ref", "handoff"],
+        "properties": {
+          "handoff": { "$ref": "#/$defs/portableBundleHandoff" },
+          "coverage": { "$ref": "#/$defs/processingCoverage" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "operation": { "const": "discovery_process_session" }, "status": { "not": { "anyOf": [{ "const": "processed" }, { "const": "needs_local_apply" }] } } },
+        "required": ["operation", "status"]
+      },
+      "then": {
+        "properties": { "envelope": false, "processing_receipt": false, "stable_url": false }
+      }
+    }
+  ],
+  "$defs": {
+    "serviceError": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "enum": [
+            "adapter_stale", "not_connected", "auth_expired", "capability_missing", "approval_missing",
+            "access_denied", "network", "provider_failure", "service_bug"
+          ]
+        },
+        "message": { "type": "string", "minLength": 1 },
+        "trace_id": { "type": "string", "minLength": 1 }
+      },
+      "required": ["code", "message"],
+      "additionalProperties": false
+    },
+    "handoff": {
+      "type": "object",
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "minLength": 1 },
+        "resume_command": { "type": "string", "minLength": 1 },
+        "requires_human": { "type": "boolean" }
+      },
+      "required": ["kind", "requires_human"],
+      "additionalProperties": false
+    },
+    "portableBundleHandoff": {
+      "description": "The T-006 needs_local_apply handoff: the signed sanitized bundle must be carried by a person or an explicit host handoff to a local runtime; productfoo never applies it remotely or retains a copy.",
+      "type": "object",
+      "properties": {
+        "kind": { "const": "portable_bundle" },
+        "url": { "type": "string", "minLength": 1 },
+        "resume_command": { "type": "string", "minLength": 1 },
+        "requires_human": { "const": true }
+      },
+      "required": ["kind", "requires_human"],
+      "additionalProperties": false
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "list_sessions": { "type": "boolean" },
+        "open_transcript": { "type": "boolean" },
+        "stable_link": { "type": "boolean" },
+        "timestamps": { "type": "boolean" }
+      },
+      "required": ["list_sessions", "open_transcript", "stable_link", "timestamps"],
+      "additionalProperties": false
+    },
+    "listedSession": {
+      "type": "object",
+      "properties": {
+        "schema_version": { "const": "0.1" },
+        "provider": { "type": "string", "minLength": 1 },
+        "connection_alias": { "type": "string", "minLength": 1 },
+        "completed_at": { "type": "string", "minLength": 1 },
+        "completion_state": { "const": "completed" },
+        "title": { "type": "string" },
+        "participants": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "stable_url": { "type": "string", "minLength": 1 },
+        "capabilities": { "$ref": "#/$defs/capabilities" },
+        "access": { "enum": ["available", "denied"] },
+        "session_ref": { "type": "string", "minLength": 1 }
+      },
+      "required": ["schema_version", "provider", "connection_alias", "completed_at", "completion_state", "title", "participants", "capabilities", "access", "session_ref"],
+      "additionalProperties": false
+    },
+    "processingCoverage": {
+      "type": "object",
+      "properties": {
+        "provider_metadata_probes": { "type": "integer", "minimum": 0 },
+        "transcript_body_calls": { "type": "integer", "minimum": 0 },
+        "synthesis_requests": { "type": "integer", "minimum": 0 },
+        "receipts_issued": { "type": "integer", "minimum": 0 },
+        "raw_content_retained": { "const": false },
+        "attempt_id": { "type": "string", "pattern": "^att:[a-f0-9]{16,64}$" },
+        "recorded_attempt_state": { "enum": ["claimed", "receipt_issued", "lost"] }
+      },
+      "required": ["provider_metadata_probes", "transcript_body_calls", "synthesis_requests", "receipts_issued", "raw_content_retained"],
+      "additionalProperties": false
+    }
+  }
+}

package/skills/AGENTS.md

@@ -0,0 +1,32 @@
+# Skill Instructions
+
+The root `AGENTS.md` still applies. This file adds procedure for work under
+`skills/`; it cannot weaken a root boundary or approval requirement.
+
+## Layout And Structure
+
+- Keep canonical skills flat at `skills/<name>/SKILL.md`; the folder name must
+  match the frontmatter `name`.
+- Every new or edited skill needs valid frontmatter, `## Usage`, and
+  `## Error Handling`.
+- Keep canonical wording runtime-neutral. Put runtime-specific behavior in an
+  explicit adapter or shim.
+
+## Governance
+
+- Treat `.agents/` as a pinned helper bundle, not canonical productfoo source. Promote
+  durable behavior into canonical skills, the registry, governance, root
+  instructions, or an approved spec.
+- Update `skills/skill-registry.yaml` for additions, renames, removals,
+  deprecations, or reclassification. Update `skills/README.md` when governance,
+  taxonomy, lifecycle, or adapter behavior changes.
+- Role skills preserve the `grill-me` pattern. Swarm skills preserve the
+  judgment ledger and expert preflight.
+- Edit generated swarm inputs, not rendered persona skills; verify them with
+  `node scripts/build-swarm-skills.mjs --verify`.
+
+## Verification
+
+- Run the structural, runtime-neutral wording, and adapter checks documented in
+  `skills/README.md`.
+- Run `npm test` before handoff when skill behavior or routing changes.