@datafog/fogclaw 0.1.0

package/docs/runbooks/verify-release.md

@@ -0,0 +1,69 @@
+---
+title: "Verify/Release"
+use_when: "Running he-verify-release to decide GO/NO-GO with evidence, rollback readiness, and post-release checks recorded in the active plan."
+called_from:
+  - he-verify-release
+---
+
+# Verify/Release
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+The skill `he-verify-release` enforces the stable invariants; this document carries the details that change per project. Inputs: active plan (`docs/plans/active/<slug>-plan.md` with `## Verify/Release Decision`) and review findings (populated by `he-review`).
+
+## Output
+
+Fill in `## Verify/Release Decision` with:
+
+- decision: `GO` or `NO-GO`
+- date:
+- open findings by priority (if any):
+- evidence: links/paths to test output and E2E artifacts
+- rollback: exact steps or pointers
+- post-release checks: exact checks/queries/URLs
+- owner:
+
+## Verification Ladder (Customize Per Repo)
+
+Define the repo's minimum ladder here. Keep it short and ordered.
+
+1. Fast checks: format/lint/typecheck (if applicable)
+2. Targeted tests for changed area
+3. Full relevant suite (unit/e2e)
+4. Manual/E2E scenario (required for user-visible changes)
+
+Document the exact commands for this repo:
+
+    # From repo root:
+    <command>
+
+## Evidence Requirements
+
+- Prefer evidence that a reviewer can reproduce (commands + short transcripts).
+- For UI changes, include screenshots or a short recording (see `docs/runbooks/record-evidence.md`).
+- For regressions, include a "before vs after" behavior description in plain language.
+
+## Rollback And Recovery
+
+Record the rollback plan for this repo:
+
+- What to revert (commit/flag/config)
+- How to detect failure
+- How to restore service/data (if relevant)
+
+## Post-Release Checks
+
+Record the minimum set of checks to run after merge/release:
+
+- health checks / smoke path
+- key metrics / dashboards (if any)
+- error logs / alerts (if any)
+
+## Escalation
+
+If any of these apply, stop and escalate per `he-verify-release` SKILL.md § Escalation:
+
+- Unclear risk to users/data
+- Flaky or non-deterministic failures
+- Rollback steps are missing or untested
+- Evidence is incomplete but time pressure exists

package/docs/specs/2026-02-16-feat-openclaw-official-submission-spec.md

@@ -0,0 +1,115 @@
+---
+slug: 2026-02-16-feat-openclaw-official-submission
+status: intake-complete
+date: 2026-02-16T17:35:00Z
+owner: sidmohan
+plan_mode: execution
+spike_recommended: no
+priority: high
+---
+
+# Prepare FogClaw for Official OpenClaw Plugin Submission
+
+## Purpose / Big Picture
+FogClaw already has a working PII/custom-entity redaction core; this initiative is to move it from "feature-complete" to "submission-ready" as an official OpenClaw plugin so maintainers can review and install it directly from the plugin ecosystem with reliable tests and repeatable packaging checks.
+
+## Scope
+
+### In Scope
+- Confirm and, if needed, adjust repository structure and metadata to match OpenClaw plugin submission expectations for official listing.
+- Add/standardize verification steps that prove plugin loadability, tool registration, and guardrail hook wiring from a clean checkout.
+- Add PR-facing execution evidence (commands + expected outputs) for submission readiness.
+- Stabilize test/packaging behavior for CI and maintainers (e.g., deterministic output, clear failure diagnostics) without changing detection algorithms.
+- Validate local install path, built artifact correctness, and versioning assumptions used by OpenClaw.
+
+### Boundaries
+- No changes to regex or GLiNER detection logic (entity patterns, model behavior, labels, or thresholds).
+- No new engine integrations, retraining, or additional model support.
+- No changes to core OpenClaw platform behavior outside plugin surface.
+- No new product features beyond what the plugin already exposes (`before_agent_start`, `fogclaw_scan`, `fogclaw_redact`).
+
+## Non-Goals
+- Building an alternate PII engine.
+- Adding user-facing dashboards or external service integrations.
+- Performing a full security audit or formal compliance certification.
+
+## Risks
+- OpenClaw official plugin submission may have stricter manifest/metadata constraints than what is currently in the repo.
+- CI environments used by maintainers may differ from local Node versions and fail model-download or ONNX runtime behaviors unless mocked/guarded appropriately.
+- Test expectations can become unstable if packaging assumes environment-specific paths.
+
+## Rollout
+- Validate locally, then verify against the same commands that CI or reviewers will run.
+- Prepare a PR checklist in the issue/PR description with explicit pass/fail commands and artifact outputs.
+- Submit/refresh PR only after all acceptance criteria in this spec are met and documented in the review thread.
+
+## Validation and Acceptance Signals
+- `npm test` passes 100% with no skipped suites.
+- `npm run build` completes without TypeScript errors and emits the expected `dist/` entry points.
+- Plugin manifest is loadable by OpenClaw with `dist/index.js` as the entry point and valid `openclaw.plugin.json` schema.
+- A reviewer can run a minimal smoke test to confirm: guardrail hook executes, `fogclaw_scan` returns entities, and `fogclaw_redact` redacts at least one sample value.
+- PR includes a reproducible command log proving plugin installation and invocation in a clean environment.
+
+## Requirements
+
+| ID | Priority | Requirement |
+|---|---|---|
+| R1 | critical | Confirm plugin metadata and layout match official OpenClaw plugin expectations, including `openclaw.plugin.json` manifest and plugin export surface from `dist/index.js`.
+| R2 | high | Establish submission-ready verification commands for loadability, guardrail operation, and tool invocation so a reviewer can validate behavior end-to-end.
+| R3 | high | Ensure tests and build are deterministic in CI-like environments, including clear diagnostics when optional GLiNER/ONNX initialization degrades.
+| R4 | medium | Document PR submission checklist and expected outputs (exact commands, pass criteria, and known fallbacks) in repository docs.
+| R5 | medium | Capture release-readiness constraints and owner decisions that affect publication (version, package name, maintainer expectations) as explicit open questions or constraints.
+
+## Chosen Direction (Recommended)
+- Proceed with a submission-readiness initiative (rather than adding any new detection features); focus on packaging, validation, and PR evidence as the primary v1 deliverable. This reduces review risk and directly addresses maintainer blockers for the current PR.
+
+## Alternatives Considered
+- **Address detection logic first** — Rejected because the current engine work appears functionally complete and would delay PR readiness without improving submission eligibility.
+- **Open a broad refactor pass first** — Rejected because this would reduce review clarity and increase the risk of introducing regressions during an already time-sensitive submission.
+
+## Key Decisions
+- Decision: Treat plugin submission hardening as a single, measurable pre-release initiative and keep engine behavior unchanged.
+  Rationale: Maintainers can review functional and packaging concerns independently; this minimizes risk of review churn and keeps the current plugin semantics stable.
+
+## Open Questions
+- **[decision]** Which exact OpenClaw ecosystem target (registry path and expected metadata contract) should be used for the first-party listing?
+- **[research]** Is a dedicated CI workflow/pipeline required by OpenClaw reviewers beyond existing project checks, and if so what exact command matrix is expected?
+- **[planning]** Should we include a semantic release/version-bump policy in this same initiative or defer to a follow-up plan after initial acceptance?
+
+## Success Criteria
+- All current unit tests remain green (`98` tests passing as baseline).
+- A local review command can verify plugin registration and tool availability in one run with no manual code edits.
+- PR description includes reproducible evidence covering: bootstrap state, tests, build, plugin smoke test, and any known degradations.
+- No functional changes to existing scanning/redaction APIs (signatures and outputs remain as currently implemented).
+
+## Constraints
+- Maintain Node.js `>=22.0.0` compatibility and existing TypeScript module format (`type: module`).
+- Keep GLiNER optional and fallback-safe so environments without model assets still pass plugin-level tests via regex-only flow.
+- Preserve current public interfaces in `src/index.ts`, `Scanner`, and redaction utilities.
+- Keep the initiative PR-sized and review-friendly: no broad architectural refactor unless required by submission gates.
+
+## Tech Preferences
+- **Language/runtime**: TypeScript / Node.js 22+.
+- **Framework**: OpenClaw plugin API and existing test stack (`vitest`).
+- **Infrastructure**: NPM scripts and repository-level CI checks only (no external services required for baseline validation).
+- **Rationale**: Minimizes external dependencies and makes the PR reproducible by maintainers.
+
+## Reference Artifacts
+- None provided by user in this session.
+
+## Priority
+- priority: high
+- rationale: This is a prerequisite for official listing, and unresolved submission-readiness blockers prevent release despite working core features.
+
+## Initial Milestone Candidates
+- M1: Submission Readiness Baseline — verify manifest, entrypoint, and smoke tests are documented and passing on clean checkout.
+- M2: PR Evidence Pack — add concise contributor-facing evidence and rollout instructions for PR reviewers.
+- M3: Final Review Gate — cross-check remaining open questions and obtain sign-off to move into `he-plan` and PR merge flow.
+
+## Handoff
+- Owner hands this artifact to `he-plan` for executable planning.
+- `he-plan` should first resolve open questions that block official submission criteria, then sequence changes in small PR-safe milestones.
+- After planning, transition target is `he-implement` unless `[research]` or `[spike]` questions remain, in which case route first to `he-research`/`he-spike`.
+
+## Revision Notes
+- 2026-02-16T17:35:00Z: Initialized spec from existing implementation state and known PR intent. Reason: move from feature-complete code to official OpenClaw submission readiness.

package/docs/specs/2026-02-17-feat-submit-fogclaw-to-openclaw.md

@@ -0,0 +1,125 @@
+---
+slug: 2026-02-17-feat-submit-fogclaw-to-openclaw
+status: intake-complete
+date: 2026-02-17T01:56:00Z
+owner: sidmohan
+plan_mode: execution
+spike_recommended: yes
+priority: high
+---
+
+# Submit FogClaw to OpenClaw official plugin channel
+
+## Purpose / Big Picture
+
+FogClaw is already installable and usable via the `@openclaw/fogclaw` package, and it now has repository-side submission readiness artifacts. This initiative is to prepare and execute the **next submission step**: opening and completing the cross-repository contribution in the OpenClaw ecosystem so the plugin can be discovered through official OpenClaw workflows.
+
+The outcome is observable when a maintainer-facing OpenClaw repo PR is opened with reproducible validation evidence and receives maintainer review status. A user should be able to verify this by checking the new upstream PR and the documented checklist that proves package identity, installability, hook/tool behavior, and testability in a clean environment.
+
+## Scope
+
+### In Scope
+
+- Identify the exact official OpenClaw submission path for plugins and prepare the required contribution artifacts for FogClaw.
+- Create a maintainer-facing submission PR in the OpenClaw repository using the already-merged `DataFog/fogclaw` release state.
+- Include submission evidence mapping between this repository and OpenClaw review expectations (package name/version, manifest, installation command, and reproducible test checks).
+- Add/confirm any minimal metadata or docs updates needed specifically for external submission in this repo (if required after upstream validation).
+- Track and document outcomes, open questions, and blockers in spec/plan artifacts.
+
+### Boundaries
+
+- No changes to detection logic, redaction strategies, or plugin runtime behavior.
+- No implementation changes to OpenClaw platform code.
+- No introduction of new dependencies or CI infrastructure in the plugin repo.
+- No security/privacy model changes; this effort only covers publication workflow and submission evidence.
+
+## Non-Goals
+
+- Reworking plugin internals or adding new plugin features.
+- Re-running full internal feature validation already completed in the plugin merge.
+- Creating a parallel package/brand strategy beyond the existing `@openclaw/fogclaw` identity.
+
+## Risks
+
+- OpenClaw may enforce additional fields, naming constraints, or review expectations that were not covered by the DataFog repo readiness work.
+- Upstream PR template may require evidence format changes from repo-local PR notes.
+- There may be a delay between contribution and maintainer review if expectations remain unclear.
+- Maintainers may request a packaging/metadata adjustment after we submit, requiring a follow-up PR.
+
+## Rollout
+
+- Use the already-merged `main` state of `DataFog/fogclaw` as the submission baseline.
+- Draft and open the OpenClaw submission PR with reproducible commands and exact expected outputs.
+- If OpenClaw maintainers request changes, loop through `respond-to-feedback` and reopen on the same submission branch.
+- Close the initiative once the upstream PR is accepted and merged, or route back to `he-implement` if repository changes are required.
+
+## Validation and Acceptance Signals
+
+- Reproducible local evidence command block exists and matches what is sent in the OpenClaw submission PR.
+- `@openclaw/fogclaw` package identity remains stable and points to the merged `DataFog/fogclaw` release state.
+- OpenClaw upstream PR reaches at least “ready for review” with all requested evidence attachments present.
+- The maintainer-facing PR includes explicit answers for submission criteria and known caveats (for example model/download behavior in constrained environments).
+
+## Requirements
+
+| ID | Priority | Requirement |
+|---|---|---|
+| R1 | high | Prepare a submission PR in the OpenClaw repo that references the `@openclaw/fogclaw` package and the merged DataFog commit history relevant for reviewers.
+| R2 | high | Include a clean check list in the OpenClaw PR body with outputs for `npm test`, `npm run build`, `npm run test:plugin-smoke`, and package manifest verification.
+| R3 | medium | Confirm any OpenClaw-specific metadata expectations (template fields, review checklist, review labels, or required docs) before requesting maintainer action.
+| R4 | medium | Capture and resolve any maintainer feedback by returning to local implementation only when repository edits are required.
+| R5 | low | Record submission status and next action in durable docs (`docs/plans/...` and open questions log).
+
+## Chosen Direction (Recommended)
+
+- Use a single upstream pull request targeting the designated OpenClaw repository path as the primary submission vehicle (recommended) because it minimizes fragmentation and matches standard contributor workflows. The risk is that external process details may require iteration.
+- A second, duplicate submission route should be avoided unless a maintainer explicitly requests it, because duplicate PRs tend to create conflicting discussions and slower review.
+
+## Open Questions
+
+- **[research]** What exact OpenClaw repository/path and PR template must FogClaw target for official plugin publication?
+- **[research]** Does OpenClaw require an additional manifest or catalog file update inside their own repository in addition to package metadata?
+- **[decision]** Should this initiative include one follow-up patch branch for any requested metadata changes, or remain submission-only until maintainer asks?
+- **[planning]** If additional upstream packaging adjustments are required, should those be merged through the current open submission branch or a fresh follow-up branch?
+
+## Success Criteria
+
+- A new OpenClaw-side PR is created with: plugin identity, install command, reproducible tests, and evidence of `src/index.ts` contract behavior.
+- The submission PR body cites the merged plugin-merge commit from `DataFog/fogclaw` as canonical source-of-truth.
+- Maintainers can reproduce the core checks from the PR body without guessing or adding setup instructions.
+- Any blocking submission questions are answered in the PR thread or captured in plan artifacts before proceeding to final merge.
+
+## Constraints
+
+- Only proceed with outward-facing submission work while preserving plugin behavior unchanged.
+- Keep all package names and registry scope aligned to `@openclaw/fogclaw` unless OpenClaw maintainer instruction requires a temporary exception.
+- Do not assume access to external OpenClaw maintainer accounts beyond normal GitHub contributor permissions.
+- Avoid changing internal plugin code until submission blockers are confirmed as code-level.
+
+## Tech Preferences
+
+- **Language/runtime**: TypeScript / Node.js (repository remains unchanged).
+- **Framework/API**: OpenClaw plugin API and GitHub PR process for upstream submission.
+- **Infrastructure**: GitHub CLI and repository PR workflow.
+- **Rationale**: Keeps this initiative low-risk and focused on process and reviewability rather than implementation.
+
+## Handoff
+
+- This spec should transition to `he-plan` once the exact OpenClaw target path and submission requirements are clear.
+- `he-plan` should define submission mechanics and maintainer-proof evidence formatting as separate milestones.
+- If significant process uncertainty remains after planning, first route to `he-research` for missing process facts.
+
+## Priority
+
+- priority: high
+- rationale: This is the final official publication step and required for wider ecosystem discoverability.
+
+## Initial Milestone Candidates
+
+- M1: Confirm official OpenClaw submission target and required review template/evidence format.
+- M2: Draft and open the upstream OpenClaw PR with reproducible checks, package identity, and maintainer-facing rationale.
+- M3: Respond to initial feedback loop and either land metadata fixes or close with explicit blocker notes.
+
+## Revision Notes
+
+- 2026-02-17T01:56:00Z: Initialized spec to formalize the cross-repo OpenClaw submission step after plugin readiness merge landed on `DataFog/fogclaw` main.

package/docs/specs/README.md

@@ -0,0 +1,5 @@
+# Specs
+
+Store initiative specs here using one file per slug.
+Each spec must start with YAML frontmatter and set `plan_mode: lightweight|execution`.
+Store spike findings separately in `docs/spikes/`.

package/docs/specs/index.md

@@ -0,0 +1,8 @@
+# Specs Index
+
+Use this index to track initiative specs in `docs/specs/`.
+
+## Active Specs
+
+- `<slug>`: `docs/specs/<slug>-spec.md`
+

package/docs/spikes/README.md

@@ -0,0 +1,8 @@
+# Spikes
+
+Time-boxed investigations for uncertain/risky initiatives.
+Use the pattern `docs/spikes/<slug>-spike.md`.
+
+Spike docs should start with YAML frontmatter (see `docs/PLANS.md` for the artifact contract).
+
+Recommended sections: `Context`, `Validation Goal`, `Approach`, `Findings`, `Decisions`, `Recommendation`, `Impact on Upstream Docs`, `Spike Code`, `Remaining Unknowns`, `Time Spent`, and append-only `Revision Notes`.

package/fogclaw.config.example.json

@@ -0,0 +1,15 @@
+{
+  "enabled": true,
+  "guardrail_mode": "redact",
+  "redactStrategy": "token",
+  "model": "onnx-community/gliner_large-v2.1",
+  "confidence_threshold": 0.5,
+  "custom_entities": ["project codename", "internal tool name"],
+  "entityActions": {
+    "SSN": "block",
+    "CREDIT_CARD": "block",
+    "EMAIL": "redact",
+    "PHONE": "redact",
+    "PERSON": "warn"
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,45 @@
+{
+  "id": "fogclaw",
+  "name": "FogClaw",
+  "version": "0.1.0",
+  "description": "PII detection & custom entity redaction powered by DataFog",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "enabled": { "type": "boolean", "default": true },
+      "guardrail_mode": {
+        "type": "string",
+        "enum": ["redact", "block", "warn"],
+        "default": "redact"
+      },
+      "redactStrategy": {
+        "type": "string",
+        "enum": ["token", "mask", "hash"],
+        "default": "token"
+      },
+      "model": {
+        "type": "string",
+        "default": "onnx-community/gliner_large-v2.1"
+      },
+      "confidence_threshold": {
+        "type": "number",
+        "default": 0.5,
+        "minimum": 0,
+        "maximum": 1
+      },
+      "custom_entities": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": []
+      },
+      "entityActions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string",
+          "enum": ["redact", "block", "warn"]
+        },
+        "default": {}
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@datafog/fogclaw",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for PII detection & custom entity redaction powered by DataFog",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:plugin-smoke": "vitest run tests/plugin-smoke.test.ts",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "gliner": "^0.0.19",
+    "onnxruntime-node": "1.19.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/datafog/fogclaw"
+  }
+}

package/scripts/ci/he-docs-config.json

@@ -0,0 +1,123 @@
+{
+  "required_docs": [
+    "AGENTS.md",
+    "docs/PLANS.md",
+    "docs/DOMAIN_DOCS.md"
+  ],
+  "expected_runbooks": [
+    "docs/runbooks/update-agents-md.md",
+    "docs/runbooks/update-domain-docs.md",
+    "docs/runbooks/code-review.md",
+    "docs/runbooks/review-findings.md",
+    "docs/runbooks/address-review-findings.md",
+    "docs/runbooks/validate-current-state.md",
+    "docs/runbooks/reproduce-bug.md",
+    "docs/runbooks/pull-request.md",
+    "docs/runbooks/respond-to-feedback.md",
+    "docs/runbooks/verify-release.md",
+    "docs/runbooks/record-evidence.md",
+    "docs/runbooks/ci-failures.md",
+    "docs/runbooks/merge-change.md"
+  ],
+  "domain_docs": [
+    "docs/DESIGN.md",
+    "docs/DATA.md",
+    "docs/FRONTEND.md",
+    "docs/PRODUCT_SENSE.md",
+    "docs/RELIABILITY.md",
+    "docs/SECURITY.md",
+    "docs/OBSERVABILITY.md",
+    "docs/design-docs/core-beliefs.md"
+  ],
+  "required_headings": {
+    "docs/SECURITY.md": [
+      "## Threat Model",
+      "## Auth Model",
+      "## Data Sensitivity",
+      "## Compliance",
+      "## Controls"
+    ],
+    "docs/RELIABILITY.md": [
+      "## Reliability Goals",
+      "## Failure Modes",
+      "## Monitoring",
+      "## Operational Guardrails"
+    ],
+    "docs/FRONTEND.md": [
+      "## Stack",
+      "## Conventions",
+      "## Component Architecture",
+      "## Performance",
+      "## Accessibility"
+    ],
+    "docs/DESIGN.md": [
+      "## Design Principles",
+      "## Visual Direction",
+      "## Interaction Standards"
+    ],
+    "docs/PRODUCT_SENSE.md": [
+      "## Target Users",
+      "## Key Outcomes",
+      "## Decision Heuristics",
+      "## Quality Criteria"
+    ],
+    "docs/DATA.md": [
+      "## Data Model",
+      "## Migrations",
+      "## Backfills And Data Fixes",
+      "## Integrity And Consistency",
+      "## Sensitive Data Notes"
+    ],
+    "docs/OBSERVABILITY.md": [
+      "## Logging Strategy",
+      "## Metrics",
+      "## Traces",
+      "## Health Checks",
+      "## Agent Access"
+    ]
+  },
+  "artifact_placeholder_patterns": [
+    "<slug>",
+    "<YYYY-",
+    "<title>"
+  ],
+  "lint_completed_plans": true,
+  "required_spec_frontmatter_keys": [
+    "slug",
+    "status",
+    "date",
+    "owner",
+    "plan_mode",
+    "spike_recommended",
+    "priority"
+  ],
+  "required_plan_frontmatter_keys": [
+    "slug",
+    "status",
+    "phase",
+    "plan_mode",
+    "priority",
+    "owner"
+  ],
+  "required_spike_frontmatter_keys": [
+    "slug",
+    "status",
+    "date",
+    "owner",
+    "timebox"
+  ],
+  "drift_rules": [
+    {
+      "regex": "(^auth/|/auth/|^middleware/|/middleware/|(^|/)security/|(^|/)permissions/)",
+      "doc": "docs/SECURITY.md"
+    },
+    {
+      "regex": "(^infra/|^ops/|^deploy/|^terraform/|^k8s/|^helm/|(^|/)monitoring/|(^|/)alerts/)",
+      "doc": "docs/RELIABILITY.md"
+    },
+    {
+      "regex": "(^package\\\\.json$|^pnpm-lock\\\\.yaml$|^yarn\\\\.lock$|^bun\\\\.lockb$|^tsconfig\\\\.json$|^vite\\\\.config\\\\.|^next\\\\.config\\\\.)",
+      "doc": "docs/FRONTEND.md"
+    }
+  ]
+}

package/scripts/ci/he-docs-drift.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DEFAULT_CONFIG_PATH="scripts/ci/he-docs-config.json"
+
+config_path="${HARNESS_DOCS_CONFIG:-$DEFAULT_CONFIG_PATH}"
+config_file="${REPO_ROOT}/${config_path}"
+
+if [[ ! -f "$config_file" ]]; then
+  echo "Error: he-docs-drift missing/invalid config: Missing config '${config_path}'. Fix: create it (bootstrap should do this) or set HARNESS_DOCS_CONFIG." >&2
+  exit 2
+fi
+
+cfg="$(cat "$config_file")"
+if ! echo "$cfg" | jq -e 'type == "object"' >/dev/null 2>&1; then
+  echo "Error: he-docs-drift missing/invalid config: Config must be a JSON object." >&2
+  exit 2
+fi
+
+base_ref="${GITHUB_BASE_REF:-}"
+head_ref="${GITHUB_HEAD_REF:-}"
+
+if [[ -n "$base_ref" ]]; then
+  diff_range="origin/${base_ref}...HEAD"
+else
+  if git -C "$REPO_ROOT" rev-parse -q --verify HEAD~1 >/dev/null 2>&1; then
+    diff_range="HEAD~1...HEAD"
+  else
+    diff_range=""
+  fi
+fi
+
+echo "he-docs-drift: starting" >&2
+echo "Repro: bash scripts/ci/he-docs-drift.sh" >&2
+if [[ -n "$base_ref" ]]; then
+  echo "PR context: base_ref='${base_ref}' head_ref='${head_ref}' diff='${diff_range}'" >&2
+else
+  echo "Local context: diff='${diff_range}'" >&2
+fi
+
+if [[ -n "$diff_range" ]]; then
+  changed="$(git -C "$REPO_ROOT" diff --name-only "$diff_range" 2>/dev/null || true)"
+else
+  changed="$(git -C "$REPO_ROOT" diff-tree --no-commit-id --name-only -r HEAD 2>/dev/null || true)"
+fi
+
+# Trim empty lines
+changed="$(echo "$changed" | sed '/^[[:space:]]*$/d')"
+
+if [[ -z "$changed" ]]; then
+  echo "he-docs-drift: no changes detected"
+  exit 0
+fi
+
+# Build list of changed docs (files starting with docs/)
+changed_docs="$(echo "$changed" | grep '^docs/' || true)"
+
+# Extract drift_rules array; default to empty array if missing or wrong type
+drift_rules="$(echo "$cfg" | jq -c '.drift_rules // [] | if type == "array" then . else [] end')"
+rule_count="$(echo "$drift_rules" | jq 'length')"
+
+missing=0
+
+for ((i = 0; i < rule_count; i++)); do
+  rule="$(echo "$drift_rules" | jq -c ".[$i]")"
+
+  # Skip non-object entries
+  if ! echo "$rule" | jq -e 'type == "object"' >/dev/null 2>&1; then
+    continue
+  fi
+
+  regex="$(echo "$rule" | jq -r '.regex // empty')"
+  doc="$(echo "$rule" | jq -r '.doc // empty')"
+
+  if [[ -z "$regex" || -z "$doc" ]]; then
+    continue
+  fi
+
+  # Validate regex by testing it
+  if ! echo "" | grep -qE "$regex" 2>/dev/null && [[ $? -eq 2 ]]; then
+    echo "Error: invalid drift rule regex: ${regex}" >&2
+    missing=1
+    continue
+  fi
+
+  # Find changed files matching the regex
+  matching="$(echo "$changed" | grep -E "$regex" || true)"
+
+  if [[ -z "$matching" ]]; then
+    continue
+  fi
+
+  # Check if the required doc is in the changed docs list
+  if ! echo "$changed_docs" | grep -qxF "$doc" 2>/dev/null; then
+    sample="$(echo "$matching" | head -n 10 | sed 's/^/- /')"
+    echo "::error file=${doc},title=Docs drift gate::Missing required doc update '${doc}' when files match /${regex}/ (see job logs for matching files)."
+    echo "Missing doc update: '${doc}' should change when files match /${regex}/." >&2
+    echo "Matching files (up to 10):" >&2
+    echo "$sample" >&2
+    echo "Fix: update '${doc}' in this PR, or edit drift_rules in '${DEFAULT_CONFIG_PATH}' (or HARNESS_DOCS_CONFIG) if this mapping is wrong." >&2
+    missing=1
+  fi
+done
+
+if [[ "$missing" -ne 0 ]]; then
+  echo "Error: docs drift gate failed (see missing doc updates above)" >&2
+  exit 1
+fi
+
+echo "he-docs-drift: OK"
+exit 0