@openauditmodel/cli 0.1.0

package/profiles/deployment-and-change-management/profile.json

@@ -0,0 +1,298 @@
+{
+  "profileVersion": "0.1",
+  "name": "deployment-and-change-management",
+  "version": "0.1",
+  "status": "experimental",
+  "coreVersions": ["0.1"],
+  "title": "Deployment and Change Management Profile",
+  "description": "Additional conformance requirements for audit events that describe material change to a running system: releases, deployments, promotions, rollbacks, cancellations, infrastructure application, configuration and secret changes, and change requests. Every requirement adds to the OpenAuditModel Core Specification; none relaxes it. The profile supports fully automated continuous delivery as well as human-gated release: it never decides which change needs approval, it requires the producer to record whether one was required. Routine pipeline telemetry such as polling, build log output and secret reads is deliberately not governed.",
+  "rules": [
+    {
+      "id": "DEPLOY-CORE-001",
+      "description": "Every governed change identifies the deployment, release or change record it belongs to, and the environment the change was applied to.",
+      "rationale": "One change produces events from many stages and often from several different services, and nothing else in an event ties those stages together: `id` is unique per event and `resource` legitimately differs between the release, the approval and the target. Without a shared identifier a reviewer cannot say which approval belongs to which deployment, or which rollback undid which release. The environment is recorded separately from `application.environment` because `application` describes the system that performed the change, not the system that received it: a delivery platform runs in one environment and deploys into others, and conflating the two makes every environment-scoped review wrong.",
+      "severity": "error",
+      "events": [
+        "change.request.approve",
+        "change.request.cancel",
+        "change.request.close",
+        "change.request.create",
+        "change.request.reject",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update",
+        "configuration.secret.rotate",
+        "configuration.setting.create",
+        "configuration.setting.delete",
+        "configuration.setting.update"
+      ],
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "requiredMetadata": [
+        {
+          "path": "/deployment/id",
+          "type": "string"
+        },
+        {
+          "path": "/deployment/environment",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DEPLOY-CORE-002",
+      "description": "Every governed change states whether policy required it to be approved.",
+      "rationale": "This profile deliberately does not decide which changes need a human approval. Continuous delivery, human-gated release, scheduled maintenance and emergency repair are all legitimate delivery models, and a profile that demanded an approval on every production deployment would describe one of them and be switched off by everyone using another. The producer declares the policy in this flag and DEPLOY-APPROVAL-002 enforces the consequence. The flag is required rather than inferred because a conditional rule contributes nothing when its path is absent: silence would read as \"no approval was required\" when it may mean \"nobody recorded whether one was\", and those are the two answers a change review most needs to tell apart.",
+      "severity": "error",
+      "events": [
+        "change.request.approve",
+        "change.request.cancel",
+        "change.request.close",
+        "change.request.create",
+        "change.request.reject",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update",
+        "configuration.secret.rotate",
+        "configuration.setting.create",
+        "configuration.setting.delete",
+        "configuration.setting.update"
+      ],
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "requiredMetadata": [
+        {
+          "path": "/deployment/approvalRequired",
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "id": "DEPLOY-CORE-003",
+      "description": "A governed change should record why it was made, the pipeline that produced it, and the identifier that correlates it with the rest of the operation.",
+      "rationale": "These are the fields a reviewer reaches for first and a producer omits most often. They are recommended rather than required because a routine automated deployment often has no justification beyond the change having been merged, because not every change comes from a pipeline, and because a configuration change made by hand from a console has no correlation identifier to carry. A missing one should prompt a question rather than fail a build.",
+      "severity": "warning",
+      "events": [
+        "change.request.approve",
+        "change.request.cancel",
+        "change.request.close",
+        "change.request.create",
+        "change.request.reject",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update",
+        "configuration.secret.rotate",
+        "configuration.setting.create",
+        "configuration.setting.delete",
+        "configuration.setting.update"
+      ],
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "recommendedPaths": ["/reason", "/request/correlationId", "/metadata/deployment/pipelineId"]
+    },
+    {
+      "id": "DEPLOY-RELEASE-001",
+      "description": "A release or infrastructure event names the version it concerns.",
+      "rationale": "A deployment trail that does not name a version records that something was released without recording what. Every later question depends on it: which build introduced a regression, whether an environment is running the artifact that was approved, and whether a rollback reached the version it aimed at. The profile requires an identifier and asserts nothing about its form, because semantic versions, tags, ordinal build numbers and content digests are all in legitimate use and no scheme is universal. What was changed by the release belongs in `relatedResources`, which is recommended rather than required so that a single-target deployment is not forced to duplicate its own `resource`.",
+      "severity": "error",
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "requiredMetadata": [
+        {
+          "path": "/deployment/version",
+          "type": "string"
+        }
+      ],
+      "recommendedPaths": ["/relatedResources", "/change/deploymentId"]
+    },
+    {
+      "id": "DEPLOY-RELEASE-002",
+      "description": "An event that changes what is running records the version it replaced.",
+      "rationale": "An incident review starts from what was running before, and that answer is only cheaply available at the moment of the change: reconstructing it later means trusting that no other event was lost from the same environment. Recording both versions on the event that moved between them makes the transition self-describing, lets a rollback be matched to the deployment it reverted, and turns \"which version was live at this time?\" into a lookup rather than a replay. A first deployment into an empty environment has a real answer too, and producers should record it explicitly rather than omit the field.",
+      "severity": "error",
+      "events": [
+        "deployment.release.deploy",
+        "deployment.release.promote",
+        "deployment.release.rollback",
+        "deployment.infrastructure.apply"
+      ],
+      "requiredMetadata": [
+        {
+          "path": "/deployment/previousVersion",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DEPLOY-REVERT-001",
+      "description": "Reverting or stopping a change in flight records the decision that permitted it and why the change was undone.",
+      "rationale": "A rollback or a cancellation discards work that the normal path had already accepted, and it is usually performed under time pressure by whoever was available rather than by whoever owns the change. Without a recorded authorization decision nothing distinguishes a considered revert from one person overriding another team, and without a justification the trail cannot say whether the change was withdrawn because it was wrong, because it was risky, or because something unrelated was failing at the time. Approval is recommended rather than required here precisely because a revert is often the correct emergency action and the approval is retrospective.",
+      "severity": "error",
+      "events": ["deployment.release.rollback", "deployment.release.cancel"],
+      "requiredPaths": ["/authorization", "/reason"],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "DEPLOY-CONFIG-001",
+      "description": "A configuration, feature, policy, retention or secret change records the decision that permitted it and which settings changed.",
+      "rationale": "Configuration is where controls are switched off, and a configuration change usually leaves no trace in business data at all, so the event is the only evidence that it happened. The authorization decision is what separates a change policy allowed from one that bypassed policy. The names of the settings that changed are required rather than their values, because the field list is the one representation every configuration system can produce and the one that never discloses a secret: a rotation records that the secret field changed and nothing about the secret. Producers may add sanitized before and after values where they are safe; this profile does not require them.",
+      "severity": "error",
+      "events": [
+        "configuration.setting.create",
+        "configuration.setting.update",
+        "configuration.setting.delete",
+        "configuration.secret.rotate",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update"
+      ],
+      "requiredPaths": ["/authorization", "/change/changedFields"]
+    },
+    {
+      "id": "DEPLOY-APPROVAL-001",
+      "description": "An event that is itself an approval decision records the resulting approval status.",
+      "rationale": "These events exist to record a human decision, so an approval event without an approval state records that a decision was reached without recording which one. The status is required because it is the fact the event is about; the workflow and the approving principals are recommended because a two-person review conducted in a ticket is a real approval process and has no workflow engine behind it. The profile does not require the status to match the event name: an approval attempt can fail, and an event that had to lie about its own outcome to conform would be worse evidence than one that did not conform.",
+      "severity": "error",
+      "events": ["deployment.release.approve", "change.request.approve", "change.request.reject"],
+      "requiredPaths": ["/approval/status"],
+      "recommendedPaths": ["/approval/workflowId", "/approval/approvers"]
+    },
+    {
+      "id": "DEPLOY-APPROVAL-002",
+      "description": "When the producer has declared that policy required approval, the event that carried the change out records the approval state it was carried out under.",
+      "rationale": "This is the rule the approvalRequired flag exists for, and it is deliberately about the executing event rather than the approving one: the question a review asks is not whether an approval exists somewhere but whether the change that actually reached the environment was covered by it. Requiring the status rather than an approved status is intentional. A change executed while approval was still pending is a control bypass, and the specification requires producers to record that honestly rather than suppress it; a rule that only accepted `approved` would make the most important event in the trail unrepresentable and would be met by omitting the flag instead.",
+      "severity": "error",
+      "events": [
+        "deployment.release.deploy",
+        "deployment.release.promote",
+        "deployment.release.rollback",
+        "deployment.release.cancel",
+        "deployment.infrastructure.apply",
+        "configuration.setting.create",
+        "configuration.setting.update",
+        "configuration.setting.delete",
+        "configuration.secret.rotate",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update"
+      ],
+      "when": {
+        "path": "/metadata/deployment/approvalRequired",
+        "equals": true
+      },
+      "requiredPaths": ["/approval/status"],
+      "recommendedPaths": ["/change/ticketId"]
+    },
+    {
+      "id": "DEPLOY-EMERGENCY-001",
+      "description": "A change the producer has flagged as bypassing the normal change path is justified.",
+      "rationale": "An emergency change, a break-glass repair and an overridden pipeline gate are the same fact from an audit point of view: the controls that normally govern change were not applied, by a decision someone made at the time. That decision is the thing a post-incident review needs and the thing nobody writes down afterwards, because the people involved were busy. The profile does not define when a change may bypass the path, and it does not require the bypass to have been approved; it requires the reason to exist while the answer is still known. The incident the change responded to and any retrospective approval are recommended for the same reason.",
+      "severity": "error",
+      "events": [
+        "change.request.approve",
+        "change.request.cancel",
+        "change.request.close",
+        "change.request.create",
+        "change.request.reject",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update",
+        "configuration.secret.rotate",
+        "configuration.setting.create",
+        "configuration.setting.delete",
+        "configuration.setting.update"
+      ],
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "when": {
+        "path": "/metadata/deployment/emergency",
+        "equals": true
+      },
+      "requiredPaths": ["/reason"],
+      "recommendedPaths": ["/approval", "/change/incidentId"]
+    },
+    {
+      "id": "DEPLOY-FAILURE-001",
+      "description": "A change that failed records the state the target was left in.",
+      "rationale": "A failed change is not self-describing. `outcome: failure` says the operation did not complete; it does not say whether the target was left untouched, left half-updated, or automatically reverted, and those three answers call for completely different responses. The state is the one fact only the producer can supply and the one nobody can reconstruct from the outside once the pipeline has moved on. The profile requires the answer to be recorded and does not constrain the vocabulary used to express it, because what counts as partially applied depends on what was being changed. The core model already requires a sanitized error code on a failure; a human readable message is recommended in addition.",
+      "severity": "error",
+      "events": [
+        "change.request.approve",
+        "change.request.cancel",
+        "change.request.close",
+        "change.request.create",
+        "change.request.reject",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update",
+        "configuration.secret.rotate",
+        "configuration.setting.create",
+        "configuration.setting.delete",
+        "configuration.setting.update"
+      ],
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "when": {
+        "path": "/event/outcome",
+        "equals": "failure"
+      },
+      "requiredMetadata": [
+        {
+          "path": "/deployment/resultingState",
+          "type": "string"
+        }
+      ],
+      "recommendedPaths": ["/event/error/message"]
+    },
+    {
+      "id": "DEPLOY-FAILURE-002",
+      "description": "A change that succeeded for some targets and failed for others records the state the targets were left in.",
+      "rationale": "A deployment across many instances is the clearest case in the model for `outcome: partial`, and it is also the case where the resulting state matters most: a partially applied change means two versions are serving at once, which is a configuration nobody designed and nobody tested. This rule is a duplicate of DEPLOY-FAILURE-001 with a different condition because the v0.1 rule language allows exactly one equality condition per rule and has no disjunction. Stating the requirement twice is preferred to stating it once and quietly leaving the partial case ungoverned.",
+      "severity": "error",
+      "events": [
+        "change.request.approve",
+        "change.request.cancel",
+        "change.request.close",
+        "change.request.create",
+        "change.request.reject",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update",
+        "configuration.secret.rotate",
+        "configuration.setting.create",
+        "configuration.setting.delete",
+        "configuration.setting.update"
+      ],
+      "eventPrefixes": ["deployment.release.", "deployment.infrastructure."],
+      "when": {
+        "path": "/event/outcome",
+        "equals": "partial"
+      },
+      "requiredMetadata": [
+        {
+          "path": "/deployment/resultingState",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DEPLOY-AUTOMATION-001",
+      "description": "When automation carried the change out, the principal it acted for should be named in `subject` and the transfer of authority in `delegation`.",
+      "rationale": "Automation performs most material change, so the actor on a deployment event is usually a service and the person who decided the change should happen is not in the event at all. The core model can express that in two ways, and this profile picks one: the human author is the `subject`, the service is the `actor`, and `delegation` says how authority moved between them. Recording the author in metadata would work for one product and be unreadable across two. It is a recommendation rather than a requirement because unattended automation such as drift correction or a scheduled reconciliation genuinely has no human author, and the resulting warning is the correct signal for a reviewer rather than a defect.",
+      "severity": "warning",
+      "events": [
+        "deployment.release.deploy",
+        "deployment.release.promote",
+        "deployment.release.rollback",
+        "deployment.release.cancel",
+        "deployment.infrastructure.apply",
+        "configuration.setting.create",
+        "configuration.setting.update",
+        "configuration.setting.delete",
+        "configuration.secret.rotate",
+        "configuration.feature.toggle",
+        "configuration.policy.update",
+        "configuration.retention.update"
+      ],
+      "when": {
+        "path": "/actor/type",
+        "equals": "service"
+      },
+      "recommendedPaths": ["/subject", "/delegation"]
+    }
+  ]
+}

package/profiles/document-management/README.md

@@ -0,0 +1,120 @@
+# Document Management Profile
+
+**Status: Experimental. Implemented in v0.1, 11 rules.**
+
+Scope: applications that store, version, share and retain documents — content platforms, contract
+systems, records management, engineering document control, knowledge bases.
+
+The profile is vendor-neutral. It describes operations that any document system performs, not the
+feature list of any product. It assumes no particular storage backend, approval workflow or
+regulatory framework.
+
+The enforceable rules are in [profile.json](profile.json).
+
+```bash
+auditmodel check-profile examples/profiles/document-management/valid --profile document-management
+```
+
+## What this profile governs
+
+| Event                                            | Governed |
+| ------------------------------------------------ | -------- |
+| `document.file.upload`, `.delete`, `.download`   | yes      |
+| `document.share.*`                               | yes      |
+| `document.permission.*`                          | yes      |
+| `document.version.*`                             | yes      |
+| `document.retention.*`                           | yes      |
+| `document.legal-hold.*`                          | yes      |
+| `document.file.view` and other high-volume reads | **no**   |
+
+### Why reads are excluded
+
+A document system emits a view event every time anyone opens anything. Requiring an authorization
+decision, a classification and a justification on each of them would add cost to the highest-volume
+event in the system in exchange for very little review value, and the requirement would be switched
+off rather than met.
+
+The exclusion is structural, not a matter of discipline: **no selector in this profile uses a bare
+`document.` prefix**, so `document.file.view` matches no rule and `check-profile` reports it as not
+applicable. A test asserts that, because widening one prefix later would silently start governing
+every read in a deployment.
+
+Excluded does not mean unaudited. A view event is still a conforming OpenAuditModel event, and
+[data-access.md](../../semantic-conventions/data-access.md) covers recording reads.
+
+## Rules
+
+| Rule                | Applies to                       | Requires                                                     |
+| ------------------- | -------------------------------- | ------------------------------------------------------------ |
+| `DOC-CORE-001`      | every governed event             | `/authorization`, `/resource/classification`                 |
+| `DOC-CORE-002`      | every governed event             | _recommends_ `/reason`, `/resource/parentId`, correlation ID |
+| `DOC-SHARE-001`     | `document.share.*`               | `/metadata/share/recipientType`                              |
+| `DOC-SHARE-002`     | `document.share.create`          | `/metadata/share/permission`; recommends an expiry           |
+| `DOC-SHARE-003`     | external `document.share.create` | `/reason`, `/metadata/share/expiresAt`                       |
+| `DOC-PERM-001`      | `document.permission.*`          | `/metadata/permission/granteeId`, `/metadata/permission/id`  |
+| `DOC-VERSION-001`   | `document.version.*`             | `/metadata/version/id`                                       |
+| `DOC-VERSION-002`   | `document.version.rollback`      | `/reason`, `/metadata/version/previousId`                    |
+| `DOC-DELETE-001`    | `document.file.delete`           | `/reason`; recommends `/approval`                            |
+| `DOC-RETENTION-001` | `document.retention.*`           | `/change`, `/reason`, `/metadata/retention/class`            |
+| `DOC-HOLD-001`      | `document.legal-hold.*`          | `/reason`, `/metadata/legalHold/active`                      |
+
+Each rule's full text and rationale is in [profile.json](profile.json).
+
+## Design decisions
+
+**External sharing is the only conditional rule.** `DOC-SHARE-003` fires only when the producer has
+declared `/metadata/share/recipientType` to be `external`. The profile does not try to decide what
+external means for a given deployment — a partner tenant is external to some organizations and
+internal to others — so the producer makes that call and the profile enforces the consequence.
+
+This is the same shape as the IAM profile's privileged-role rule, and it is the only conditional
+mechanism v0.1 offers: one path compared for equality against one scalar.
+
+**Expiry is recommended generally and required externally.** Indefinite internal access is often a
+deliberate and correct choice. Indefinite external access rarely is.
+
+**Approval is recommended, never required.** Many document systems legitimately let an owner delete
+their own draft or reclassify their own file. A rule that required approval for every deletion would
+describe one organization's process and be ignored by everyone else.
+
+**Metadata is namespaced.** Requirements use `/metadata/share/...`, `/metadata/version/...`,
+`/metadata/retention/...` rather than flat keys, matching the IAM profile's `/metadata/role/...`
+convention. Namespacing keeps two profiles from assigning different meanings to the same key when an
+event is governed by both — `expiresAt` on a share and on a credential are not the same fact.
+
+**Retention and legal hold record state, not obligations.** The profile requires that the resulting
+retention class and hold condition be recorded, and that the change be justified. It says nothing
+about how long anything must be kept, what any class means, or what any jurisdiction requires.
+Conformance with these rules is not compliance with any legal duty.
+
+**Array contents are never inspected.** The v0.1 rule language checks presence, JSON type and scalar
+equality. It cannot assert that `/evidence` contains an entry of a particular type, and this profile
+does not pretend otherwise.
+
+## Not required, and why
+
+- **Watermarking, password protection, download permissions.** Real controls, but product features
+  rather than universal document operations. They belong in `metadata` or an extension.
+- **A document approval event family.** Approval is already modelled by `workflow.approval.*` in
+  [workflow-and-approval.md](../../semantic-conventions/workflow-and-approval.md), and by the core
+  `/approval` object. Inventing `document.approval.*` would duplicate both.
+- **`/organization/workspaceId` as an alternative to `/resource/parentId`.** The earlier placeholder
+  proposed "one or the other", which the rule language cannot express — there is no disjunction.
+  `parentId` is recommended rather than required, so a flat repository is not forced to invent a
+  container.
+
+## Fixtures
+
+[examples/profiles/document-management/](../../examples/profiles/document-management/) — ten valid,
+eleven invalid, one not-applicable. Every valid fixture is core-conforming and privacy-clean; every
+invalid fixture is core-**valid** and fails exactly one profile rule.
+
+## Open questions
+
+- Is a share to an internal group meaningfully different from a share to an external recipient, or is
+  `recipientType` sufficient? The profile currently assumes the producer's declaration is enough.
+- How should a share whose scope changes over time be modelled: as revoke plus create, or as an
+  update? The profile accepts either and requires the recipient type in both.
+- Should `document.file.download` of a restricted document require stronger evidence, such as
+  multi-factor authentication? Expressing that needs a producer-set discriminator like the IAM
+  profile's `privileged` flag, and there is no adoption evidence yet for what it should be called.

package/profiles/document-management/profile.json

@@ -0,0 +1,170 @@
+{
+  "profileVersion": "0.1",
+  "name": "document-management",
+  "version": "0.1",
+  "status": "experimental",
+  "coreVersions": ["0.1"],
+  "title": "Document Management Profile",
+  "description": "Additional conformance requirements for document management audit events: creation, deletion, download, versioning, sharing, access policy, retention and legal hold. Every requirement adds to the OpenAuditModel Core Specification; none relaxes it. High-volume read events such as document.file.view are deliberately not governed.",
+  "rules": [
+    {
+      "id": "DOC-CORE-001",
+      "description": "Every governed document operation records the authorization decision that permitted it and the classification of the document it acted on.",
+      "rationale": "A document operation without a recorded decision cannot be reviewed: nothing distinguishes an action policy allowed from one that bypassed policy. Without a classification, a reviewer cannot tell whether the operation touched public material or the most sensitive record the organization holds, and every triage decision downstream depends on that difference.",
+      "severity": "error",
+      "events": ["document.file.upload", "document.file.delete", "document.file.download"],
+      "eventPrefixes": [
+        "document.share.",
+        "document.permission.",
+        "document.version.",
+        "document.retention.",
+        "document.legal-hold."
+      ],
+      "requiredPaths": ["/authorization", "/resource/classification"]
+    },
+    {
+      "id": "DOC-CORE-002",
+      "description": "A governed document operation should record why it happened, where the document lives, and how it correlates with the wider operation.",
+      "rationale": "These are the fields a reviewer reaches for first and a producer omits most often. They are recommended rather than required because a conforming system may legitimately have no container hierarchy, and because a missing justification should prompt a question rather than fail a build.",
+      "severity": "warning",
+      "events": ["document.file.upload", "document.file.delete", "document.file.download"],
+      "eventPrefixes": [
+        "document.share.",
+        "document.permission.",
+        "document.version.",
+        "document.retention.",
+        "document.legal-hold."
+      ],
+      "recommendedPaths": ["/reason", "/resource/parentId", "/request/correlationId"]
+    },
+    {
+      "id": "DOC-SHARE-001",
+      "description": "A share event records the kind of recipient the access was granted to or withdrawn from.",
+      "rationale": "Whether a document went to a colleague, a partner or an anonymous link is the single fact that determines the risk of the operation, and it cannot be reconstructed later from an identifier alone.",
+      "severity": "error",
+      "eventPrefixes": ["document.share."],
+      "requiredMetadata": [
+        {
+          "path": "/share/recipientType",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DOC-SHARE-002",
+      "description": "Creating a share records the permission granted, and should record when the access ends.",
+      "rationale": "A share that does not say what the recipient may do records that something was shared without recording what was given away. An expiry is recommended here and required for external recipients, because indefinite internal access is often a deliberate and reasonable choice.",
+      "severity": "error",
+      "events": ["document.share.create"],
+      "requiredMetadata": [
+        {
+          "path": "/share/permission",
+          "type": "string"
+        }
+      ],
+      "recommendedPaths": ["/metadata/share/expiresAt"]
+    },
+    {
+      "id": "DOC-SHARE-003",
+      "description": "A share to an external recipient is time-bounded and justified.",
+      "rationale": "An external share is a disclosure outside the organization's control. Without an expiry it is indefinite, and without a stated reason there is no record of who decided the disclosure was acceptable. This rule fires only when the producer has declared the recipient external, so the profile does not have to guess what external means for a given deployment.",
+      "severity": "error",
+      "events": ["document.share.create"],
+      "when": {
+        "path": "/metadata/share/recipientType",
+        "equals": "external"
+      },
+      "requiredPaths": ["/reason"],
+      "requiredMetadata": [
+        {
+          "path": "/share/expiresAt",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DOC-PERM-001",
+      "description": "A document permission change names the principal whose access changed and the permission involved.",
+      "rationale": "An access-policy change that does not say whose access changed is not reviewable at all. The principal is recorded in namespaced metadata rather than in `/subject`, because [actor-model.md](../../specification/actor-model.md) §5 defines `subject` as the principal *on whose behalf* the actor acted, and forbids its use as a generic target. A grantee or assignee is neither. This follows the identity profile, which records a role in `/metadata/role/id` for the same reason.",
+      "severity": "error",
+      "eventPrefixes": ["document.permission."],
+      "requiredMetadata": [
+        {
+          "path": "/permission/id",
+          "type": "string"
+        },
+        {
+          "path": "/permission/granteeId",
+          "type": "string"
+        }
+      ],
+      "recommendedPaths": ["/reason"]
+    },
+    {
+      "id": "DOC-VERSION-001",
+      "description": "A version event identifies the version it produced or restored.",
+      "rationale": "Version history is the record of what a document said at a point in time. An event that does not name the version cannot be tied to the content it describes.",
+      "severity": "error",
+      "eventPrefixes": ["document.version."],
+      "requiredMetadata": [
+        {
+          "path": "/version/id",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DOC-VERSION-002",
+      "description": "A rollback records the version it replaced and why the current content was discarded.",
+      "rationale": "A rollback destroys the prevailing content. Without the replaced version the trail cannot say what was undone, and without a reason it cannot say whether the change was a correction or a reversal of someone else's work.",
+      "severity": "error",
+      "events": ["document.version.rollback"],
+      "requiredPaths": ["/reason"],
+      "requiredMetadata": [
+        {
+          "path": "/version/previousId",
+          "type": "string"
+        }
+      ]
+    },
+    {
+      "id": "DOC-DELETE-001",
+      "description": "Deleting a document is justified, and should be approved.",
+      "rationale": "Deletion is the operation an audit trail is least able to reconstruct after the fact, because the evidence is what was removed. Approval is recommended rather than required: many systems legitimately allow an owner to delete their own draft, and a rule that forbade it would be ignored rather than followed.",
+      "severity": "error",
+      "events": ["document.file.delete"],
+      "requiredPaths": ["/reason"],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "DOC-RETENTION-001",
+      "description": "A retention change records the resulting retention class, the transition and why it was made.",
+      "rationale": "Retention determines how long the evidence exists at all, so a change to it is a change to the audit trail's own reach. The profile requires the state and the transition to be recorded; it does not say what any retention class must mean, or how long anything must be kept, because those are organization and jurisdiction decisions this specification does not make.",
+      "severity": "error",
+      "eventPrefixes": ["document.retention."],
+      "requiredPaths": ["/change", "/reason"],
+      "requiredMetadata": [
+        {
+          "path": "/retention/class",
+          "type": "string"
+        }
+      ],
+      "recommendedPaths": ["/approval"]
+    },
+    {
+      "id": "DOC-HOLD-001",
+      "description": "A legal hold event records whether the hold is in force and why it changed.",
+      "rationale": "A hold suspends normal retention, so an event that does not state the resulting condition leaves the document's disposition ambiguous. The profile records the state and the justification only; it asserts nothing about any jurisdiction's obligations, and conformance with this rule is not compliance with any legal duty.",
+      "severity": "error",
+      "eventPrefixes": ["document.legal-hold."],
+      "requiredPaths": ["/reason"],
+      "requiredMetadata": [
+        {
+          "path": "/legalHold/active",
+          "type": "boolean"
+        }
+      ],
+      "recommendedPaths": ["/approval"]
+    }
+  ]
+}