plainstamp 0.7.3 → 0.7.5

package/CHANGELOG.md

@@ -16,6 +16,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 Distribution is **npm-only**. Source remains in the operating organization's private repository; there is no public source repository host. Contact channel for issues, accuracy reports, security reports, and contribution proposals is **helpfulbutton140@agentmail.to** (see `docs/CONTRIBUTING.md`, `docs/SECURITY.md`).
 
+## [0.7.5] — 2026-05-09
+
+### Fixed (URL-monitor source stabilization)
+
+- `urlMonitorSource` now hashes a normalized version of the page body via the new `normalizeForHash(html)` helper, instead of the raw response. The normalization strips dynamic per-fetch markers that were causing false positives in the daily watcher cron: `<script>` and `<style>` blocks (nonces, build hashes, telemetry); HTML comments (often timestamps); CSRF / authenticity / `_token` / `requestverification` hidden inputs; inline `nonce`, `integrity`, `data-csrf`, `data-token`, `data-nonce`, `data-build`, and `data-version` attribute values; timestamp-bearing `<meta>` tags (`og:updated_time`, `last-modified`, `revised`, `build-time`, `generated-at`, `page-date`); whitespace runs collapsed.
+- Two fetches of the same regulator-published page now hash identically as long as the substantive text and structure are unchanged.
+- `Article.extra` now also carries `normalized_length` alongside `content_hash` and `content_length` for audit.
+- New export from package root: `normalizeForHash`.
+- Tests: 58/58 passing (added 7 normalization-stability tests).
+
+## [0.7.4] — 2026-05-08
+
+### Fixed (root re-exports for watcher API)
+
+- Re-export the watcher's public surface (`diffArticles`, `runWatcher`, `runWatcherWithStore`, `readState`, `writeState`, `fsStateStore`, `memoryStateStore`, source factories, and the `Article` / `Source` / `RunReport` / `SourceRunReport` / `StateStore` / `WatcherState` types) from the package root. Previously these were only available via the deep `plainstamp/dist/watcher/index.js` import path, which broke type resolution in some consumers (notably the `plainstamp-cf-worker` Cloudflare Workers package). Now `import { runWatcherWithStore, type StateStore } from "plainstamp"` works.
+
 ## [0.7.3] — 2026-05-08
 
 ### Added (cross-runtime watcher)

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { computeCoverageMatrix, renderCoverageMarkdown, renderCoverageCsv, type
 export type { DisclosureRuleT, RuleSetT, LookupQueryT, LookupResultT, ChannelT, UseCaseT, SeverityT, JurisdictionIdT, DisclosureElementT, } from "./schema.js";
 export { Channel, UseCase, Severity, JurisdictionId, LookupQuery, DisclosureElement, DisclosureRule, RuleSet, } from "./schema.js";
 export { mcpTools, executeMcpTool, type McpToolDescriptor, type McpToolResult, } from "./mcp-tools.js";
+export { diffArticles, runWatcher, runWatcherWithStore, readState, writeState, fsStateStore, memoryStateStore, federalRegisterSource, urlMonitorSource, rulesCitationsUrlMonitor, hashContent, normalizeForHash, } from "./watcher/index.js";
+export type { Article, Source, RunReport, SourceRunReport, StateStore, WatcherState, } from "./watcher/index.js";
 import type { LookupQueryT, LookupResultT, DisclosureRuleT } from "./schema.js";
 /**
  * High-level convenience: load the bundled rules and look up disclosures for

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,eAAe,EACf,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,EAAE,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAK5C;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,YAAY,EACnB,aAAa,EAAE,MAAM;;;;;IAKtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,eAAe,EACf,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,EAAE,CAEnE;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAK5C;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,YAAY,EACnB,aAAa,EAAE,MAAM;;;;;IAKtB"}

package/dist/index.js

@@ -3,6 +3,7 @@ export { loadBundledRules, loadRulesFromPath, setBundledRules, } from "./rules-l
 export { computeCoverageMatrix, renderCoverageMarkdown, renderCoverageCsv, } from "./coverage.js";
 export { Channel, UseCase, Severity, JurisdictionId, LookupQuery, DisclosureElement, DisclosureRule, RuleSet, } from "./schema.js";
 export { mcpTools, executeMcpTool, } from "./mcp-tools.js";
+export { diffArticles, runWatcher, runWatcherWithStore, readState, writeState, fsStateStore, memoryStateStore, federalRegisterSource, urlMonitorSource, rulesCitationsUrlMonitor, hashContent, normalizeForHash, } from "./watcher/index.js";
 import { loadBundledRules } from "./rules-loader.js";
 import { lookup as lookupFn, validateDisclosure as validateFn } from "./lookup.js";
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AAYvB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,GAGf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,kBAAkB,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,OAAO,QAAQ,CAAC,gBAAgB,EAAE,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,aAAqB;IAErB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,GAGlB,MAAM,eAAe,CAAC;AAYvB,OAAO,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,cAAc,GAGf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAU5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,kBAAkB,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AAGnF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,OAAO,QAAQ,CAAC,gBAAgB,EAAE,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,aAAqB;IAErB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1C,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/watcher/index.d.ts

@@ -35,5 +35,5 @@ export declare function runWatcher(opts: {
 export type { Article, Source, RunReport, SourceRunReport, StateStore, WatcherState, };
 export { readState, writeState, fsStateStore, memoryStateStore, } from "./state-store.js";
 export { federalRegisterSource } from "./sources/federal-register.js";
-export { urlMonitorSource, rulesCitationsUrlMonitor, hashContent, } from "./sources/url-monitor.js";
+export { urlMonitorSource, rulesCitationsUrlMonitor, hashContent, normalizeForHash, } from "./sources/url-monitor.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/watcher/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,MAAM,EACN,eAAe,EACf,UAAU,EACV,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAO1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAiDrB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAWrB;AAED,YAAY,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,CAAC;AACF,OAAO,EACL,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,GACZ,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,MAAM,EACN,eAAe,EACf,UAAU,EACV,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAO1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAiDrB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,SAAS,CAAC,CAWrB;AAED,YAAY,EACV,OAAO,EACP,MAAM,EACN,SAAS,EACT,eAAe,EACf,UAAU,EACV,YAAY,GACb,CAAC;AACF,OAAO,EACL,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,GACjB,MAAM,0BAA0B,CAAC"}

package/dist/watcher/index.js

@@ -87,5 +87,5 @@ export async function runWatcher(opts) {
 }
 export { readState, writeState, fsStateStore, memoryStateStore, } from "./state-store.js";
 export { federalRegisterSource } from "./sources/federal-register.js";
-export { urlMonitorSource, rulesCitationsUrlMonitor, hashContent, } from "./sources/url-monitor.js";
+export { urlMonitorSource, rulesCitationsUrlMonitor, hashContent, normalizeForHash, } from "./sources/url-monitor.js";
 //# sourceMappingURL=index.js.map

package/dist/watcher/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"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"}

package/dist/watcher/sources/url-monitor.d.ts

@@ -8,6 +8,13 @@ import type { Source } from "../types.js";
  * Use this for tracking regulator-published source pages that don't have a
  * dedicated API or RSS feed. Failures fetching individual URLs are isolated
  * — one bad URL does not abort the run.
+ *
+ * Hashing is performed on a normalized version of the page (see
+ * `normalizeForHash`) — `<script>` / `<style>` blocks, HTML comments,
+ * CSRF inputs, and inline `nonce`/`integrity`/`csrf-token` attributes
+ * are stripped before hashing. This avoids the false-positive flapping
+ * that raw-body hashing produces on regulator pages with dynamic
+ * markers (anti-bot tokens, server timestamps, build hashes).
  */
 export declare function urlMonitorSource(opts: {
     id: string;
@@ -16,6 +23,32 @@ export declare function urlMonitorSource(opts: {
     /** Optional fetch shim for testing. Defaults to global fetch. */
     fetcher?: typeof fetch;
 }): Source;
+/**
+ * Normalize a fetched page body before content-hashing, so hashes are
+ * stable across fetches when the meaningful regulator-published text
+ * is unchanged. Removes dynamic content that varies per request:
+ *
+ * 1. `<script>...</script>` blocks (nonces, build hashes, telemetry).
+ * 2. `<style>...</style>` blocks (sometimes contain build timestamps).
+ * 3. `<!-- ... -->` HTML comments.
+ * 4. `<input type="hidden" name="*csrf*"/"*token*"/"*authenticity*">`
+ *    elements (CSRF tokens vary per session).
+ * 5. Inline `nonce="..."`, `integrity="..."`, `data-csrf="..."`, and
+ *    `data-token="..."` attribute values.
+ * 6. `<meta>` tags whose `name`/`property` is timestamp-like
+ *    (`og:updated_time`, `last-modified`, `revised`, etc.).
+ * 7. Collapse runs of whitespace.
+ *
+ * The result is HTML with the layout structure preserved but the
+ * dynamic per-fetch markers removed. Two fetches of the same
+ * regulator-published page now hash identically as long as the
+ * substantive text and structure are unchanged. When the published
+ * text changes, the hash changes and the watcher fires.
+ *
+ * Exported for testability and for downstream consumers who want to
+ * apply the same normalization to other change-detection workflows.
+ */
+export declare function normalizeForHash(html: string): string;
 /**
  * Convenience: a source that monitors every bundled rule's `citation.source_url`.
  * When any cited statute or regulation page changes content, the next watcher

package/dist/watcher/sources/url-monitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url-monitor.d.ts","sourceRoot":"","sources":["../../../src/watcher/sources/url-monitor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,GAAG,MAAM,CA6BT;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE;IAC9C,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,GAAG,MAAM,CAUT;AAED,mIAAmI;AACnI,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD"}
+{"version":3,"file":"url-monitor.d.ts","sourceRoot":"","sources":["../../../src/watcher/sources/url-monitor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,GAAG,MAAM,CAkCT;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA2BrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE;IAC9C,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,GAAG,MAAM,CAUT;AAED,mIAAmI;AACnI,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/watcher/sources/url-monitor.js

@@ -9,6 +9,13 @@ import { loadBundledRules } from "../../rules-loader.js";
  * Use this for tracking regulator-published source pages that don't have a
  * dedicated API or RSS feed. Failures fetching individual URLs are isolated
  * — one bad URL does not abort the run.
+ *
+ * Hashing is performed on a normalized version of the page (see
+ * `normalizeForHash`) — `<script>` / `<style>` blocks, HTML comments,
+ * CSRF inputs, and inline `nonce`/`integrity`/`csrf-token` attributes
+ * are stripped before hashing. This avoids the false-positive flapping
+ * that raw-body hashing produces on regulator pages with dynamic
+ * markers (anti-bot tokens, server timestamps, build hashes).
  */
 export function urlMonitorSource(opts) {
     const fetcher = opts.fetcher ?? fetch;
@@ -23,14 +30,19 @@ export function urlMonitorSource(opts) {
                     const res = await fetcher(url, { redirect: "follow" });
                     if (!res.ok)
                         continue;
-                    const text = await res.text();
-                    const hash = hashContent(text);
+                    const raw = await res.text();
+                    const normalized = normalizeForHash(raw);
+                    const hash = hashContent(normalized);
                     articles.push({
                         id: `${url}#${hash}`,
                         title: url,
                         url,
                         publishedAt: today(),
-                        extra: { content_hash: hash, content_length: text.length },
+                        extra: {
+                            content_hash: hash,
+                            content_length: raw.length,
+                            normalized_length: normalized.length,
+                        },
                     });
                 }
                 catch {
@@ -41,6 +53,53 @@ export function urlMonitorSource(opts) {
         },
     };
 }
+/**
+ * Normalize a fetched page body before content-hashing, so hashes are
+ * stable across fetches when the meaningful regulator-published text
+ * is unchanged. Removes dynamic content that varies per request:
+ *
+ * 1. `<script>...</script>` blocks (nonces, build hashes, telemetry).
+ * 2. `<style>...</style>` blocks (sometimes contain build timestamps).
+ * 3. `<!-- ... -->` HTML comments.
+ * 4. `<input type="hidden" name="*csrf*"/"*token*"/"*authenticity*">`
+ *    elements (CSRF tokens vary per session).
+ * 5. Inline `nonce="..."`, `integrity="..."`, `data-csrf="..."`, and
+ *    `data-token="..."` attribute values.
+ * 6. `<meta>` tags whose `name`/`property` is timestamp-like
+ *    (`og:updated_time`, `last-modified`, `revised`, etc.).
+ * 7. Collapse runs of whitespace.
+ *
+ * The result is HTML with the layout structure preserved but the
+ * dynamic per-fetch markers removed. Two fetches of the same
+ * regulator-published page now hash identically as long as the
+ * substantive text and structure are unchanged. When the published
+ * text changes, the hash changes and the watcher fires.
+ *
+ * Exported for testability and for downstream consumers who want to
+ * apply the same normalization to other change-detection workflows.
+ */
+export function normalizeForHash(html) {
+    let s = html;
+    // Order matters — script/style first because they may contain
+    // patterns the later regexes would otherwise see.
+    s = s.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+    s = s.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
+    s = s.replace(/<!--[\s\S]*?-->/g, "");
+    // CSRF / authenticity hidden inputs — match common patterns.
+    s = s.replace(/<input\b[^>]*name\s*=\s*["'][^"']*(?:csrf|authenticity|_token|requestverification)[^"']*["'][^>]*\/?\s*>/gi, "");
+    // Inline dynamic attribute values. We strip the *value*, not the
+    // attribute name, to preserve structural diffability.
+    s = s.replace(/\b(nonce|integrity)\s*=\s*"[^"]*"/gi, "$1=\"\"");
+    s = s.replace(/\b(nonce|integrity)\s*=\s*'[^']*'/gi, "$1=''");
+    s = s.replace(/\b(data-(?:csrf|token|nonce|build|version)[^=\s>]*)\s*=\s*"[^"]*"/gi, "$1=\"\"");
+    s = s.replace(/\b(data-(?:csrf|token|nonce|build|version)[^=\s>]*)\s*=\s*'[^']*'/gi, "$1=''");
+    // Timestamp-bearing meta tags.
+    s = s.replace(/<meta\b[^>]*(?:name|property)\s*=\s*["'][^"']*(?:updated_time|last-?modified|revised|build-?time|generated-?at|page-?date)[^"']*["'][^>]*\/?\s*>/gi, "");
+    // Collapse runs of whitespace and trim ends. Single space between
+    // tokens is sufficient for hash stability.
+    s = s.replace(/\s+/g, " ").trim();
+    return s;
+}
 /**
  * Convenience: a source that monitors every bundled rule's `citation.source_url`.
  * When any cited statute or regulation page changes content, the next watcher

package/dist/watcher/sources/url-monitor.js.map

@@ -1 +1 @@
-{"version":3,"file":"url-monitor.js","sourceRoot":"","sources":["../../../src/watcher/sources/url-monitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAMhC;IACC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACtC,MAAM,KAAK,GAAG,GAAW,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAElE,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,KAAK,CAAC,KAAK;YACT,MAAM,QAAQ,GAAc,EAAE,CAAC;YAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;oBACvD,IAAI,CAAC,GAAG,CAAC,EAAE;wBAAE,SAAS;oBACtB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;oBAC9B,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;oBAC/B,QAAQ,CAAC,IAAI,CAAC;wBACZ,EAAE,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;wBACpB,KAAK,EAAE,GAAG;wBACV,GAAG;wBACH,WAAW,EAAE,KAAK,EAAE;wBACpB,KAAK,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE;qBAC3D,CAAC,CAAC;gBACL,CAAC;gBAAC,MAAM,CAAC;oBACP,6EAA6E;gBAC/E,CAAC;YACH,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAExC;IACC,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,gBAAgB,CAAC;QACtB,EAAE,EAAE,qBAAqB;QACzB,WAAW,EACT,8LAA8L;QAChM,IAAI;QACJ,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC,CAAC;AACL,CAAC;AAED,mIAAmI;AACnI,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"url-monitor.js","sourceRoot":"","sources":["../../../src/watcher/sources/url-monitor.ts"],"names":[],"mappings":"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"}

package/docs/guides/eeoc-title-vii-ai-employment-builder-guide.md

@@ -0,0 +1,274 @@
+# EEOC Title VII AI selection procedures: a builder's guide
+
+> **Informational only — not legal advice.** Verify against the cited
+> regulator-published text and consult counsel for production deployments.
+> See `AI-DISCLOSURE.md` in this package.
+
+If your HR-tech product, applicant-tracking system, AI screening tool,
+video-interview analyzer, gamified-assessment platform, or AI-assisted
+sourcing tool is used in any employment selection decision — hiring,
+promotion, transfer, retention, or termination — Title VII of the
+Civil Rights Act of 1964 applies in full, even when the decision is
+mediated by AI. The U.S. Equal Employment Opportunity Commission's
+**May 18, 2023 technical assistance** on AI selection procedures is
+the federal-floor framework for what that means in production. This
+guide covers what Title VII requires, why the four-fifths rule is
+the operative compliance metric, the relationship to NYC Local Law
+144 and other state-level mandates, the ADA reasonable-accommodation
+overlay, and what governance discipline a vendor needs in place
+before deploying an AI tool that touches employment decisions.
+
+## What the EEOC technical assistance actually says
+
+On May 18, 2023, the EEOC issued [*Select Issues: Assessing Adverse
+Impact in Software, Algorithms, and Artificial Intelligence Used in
+Employment Selection Procedures Under Title VII*](https://www.eeoc.gov/laws/guidance/select-issues-assessing-adverse-impact-software-algorithms-and-artificial-intelligence).
+The technical assistance does not create new law. It clarifies how
+existing law — Title VII (42 U.S.C. § 2000e et seq.) and the
+**Uniform Guidelines on Employee Selection Procedures** (1978),
+codified at 29 CFR Part 1607 — applies when employers use AI or
+algorithmic tools in selection procedures.
+
+Three operative holdings:
+
+1. **AI tools are "selection procedures."** Any AI-driven test,
+   scoring system, ranking algorithm, video-interview analyzer, or
+   automated screening tool used as part of an employment decision is
+   a "selection procedure" under the Uniform Guidelines. The guidance
+   confirms that even informal uses (an AI tool that "helps" a
+   recruiter shortlist candidates, where the recruiter then chooses)
+   are selection procedures if the tool meaningfully affects the
+   decision.
+2. **The four-fifths rule applies.** Under the Uniform Guidelines, a
+   selection rate for any race, sex, or ethnic group that is less
+   than four-fifths (80%) of the rate for the highest-rate group is
+   "evidence of adverse impact." This rule applies to AI selection
+   tools on the same terms as any other selection procedure.
+3. **Vendor liability does not transfer.** The employer is liable
+   under Title VII for disparate-impact discrimination resulting from
+   an AI tool, even when the tool was developed and operated by a
+   third-party vendor. The vendor's representation that the tool was
+   "bias-tested" is not a defense.
+
+The technical assistance is **interpretive**, not regulatory — the
+binding obligation is Title VII's prohibition on disparate-impact
+discrimination, which has been law since *Griggs v. Duke Power*
+(1971). But the guidance signals current EEOC enforcement priorities
+and is treated as authoritative in EEOC investigations.
+
+## The four-fifths rule, in production
+
+The four-fifths rule is the operational adverse-impact metric. To
+apply it to an AI selection tool:
+
+1. **Compute the selection rate for each protected class group.** For
+   a hiring tool: of all candidates who interacted with the tool,
+   what fraction received a "pass" (advanced to the next step,
+   received an offer, etc.) — broken out by race, sex, ethnicity,
+   age cohort, etc.
+2. **Identify the highest selection rate.** Across all groups, find
+   the group with the highest pass rate.
+3. **Divide each other group's rate by the highest.** If any group's
+   rate is below 80% (4/5) of the highest group's rate, there is
+   evidence of adverse impact for that group.
+4. **If adverse impact is found**, the employer must demonstrate the
+   selection procedure is "job related for the position in question
+   and consistent with business necessity" (the Uniform Guidelines'
+   "job-relatedness" defense). And even then, a less-discriminatory
+   alternative must not be available.
+
+Concrete example: An AI screening tool passes 40% of male
+applicants and 25% of female applicants. The female-to-male ratio is
+25/40 = 0.625, which is less than 0.8 — evidence of adverse impact.
+The employer must either (a) demonstrate the tool is job-related and
+no less-discriminatory alternative exists, or (b) modify or replace
+the tool.
+
+## "The vendor said the tool was bias-tested" is not a defense
+
+This is the single most consequential clarification in the EEOC
+guidance. Many AI HR tool vendors include in their marketing copy
+some variant of "our model has been audited for bias" — usually
+referring to a one-time pre-deployment audit on a synthetic dataset
+or against a generic baseline. The EEOC's position:
+
+- **The employer remains liable.** Title VII liability is the
+  employer's, not the vendor's. A vendor audit that turns out to
+  miss real disparate impact in the employer's actual applicant pool
+  is not a defense.
+- **Each employer needs its own audit.** The applicant pool, role
+  requirements, and use context vary by employer. A tool that's
+  unbiased for one employer's pool may be biased for another's.
+  Production-ready compliance requires the *employer* to audit the
+  *employer's actual outputs*.
+- **Ongoing audits, not one-time.** AI tools drift as they're
+  retrained on new data; a tool that passed a four-fifths audit at
+  deployment may fail one a year later. Periodic re-auditing is
+  expected.
+
+## Where state and local law layers on top
+
+The EEOC technical assistance is the federal floor. Several
+jurisdictions have **stricter** mandatory rules:
+
+| Jurisdiction | Law | What it adds beyond EEOC |
+|---|---|---|
+| New York City | Local Law 144 (AEDT) | Mandatory annual independent bias audit, public publication of audit results, and applicant notice 10 business days before tool use. **Mandatory**, not recommended. |
+| Illinois | Human Rights Act amended by HB 3773 | Effective 2026-01-01: prohibits AI use in employment that subjects an employee or applicant to discrimination based on protected class. Requires advance notice. |
+| Colorado | SB 24-205 (AI Act) | Effective 2026-06-30: applies to "high-risk AI systems" including those used in employment decisions; requires risk assessment, consumer notice, and right to an explanation. |
+| Maryland | LE § 3-717 | Facial recognition in interviews requires written consent. |
+| California | AB 2930 (status pending — Newsom vetoed Sept 2024) | Would have required impact assessments for AI in employment. Not currently law; monitor for re-introduction. |
+
+For a multi-state employer, the right rule is the strictest applicable
+local rule, not the EEOC technical assistance. A national HR-tech
+deployment must satisfy NYC Local Law 144's audit-and-publication
+mandate even if the federal EEOC guidance only "recommends" similar
+steps.
+
+## The ADA accommodation overlay
+
+The EEOC issued a parallel technical assistance under the **Americans
+with Disabilities Act** on May 12, 2022 ([*The Americans with
+Disabilities Act and the Use of Software, Algorithms, and Artificial
+Intelligence to Assess Job Applicants and
+Employees*](https://www.eeoc.gov/laws/guidance/americans-disabilities-act-and-use-software-algorithms-and-artificial-intelligence)).
+Three operative principles:
+
+1. **AI tools must be accessible.** A tool that screens out candidates
+   with disabilities — for example, a video-interview analyzer that
+   penalizes candidates with speech disabilities, or a gamified
+   assessment that's inaccessible to candidates with motor
+   disabilities — violates the ADA when no reasonable accommodation
+   is offered.
+2. **Reasonable-accommodation obligation.** Employers must provide
+   alternative selection procedures, additional time, or modified
+   formats on request — the same obligation that applies to
+   traditional tests.
+3. **Pre-employment medical inquiry rules apply.** AI tools that
+   probe for disability status (even indirectly, through behavioral
+   patterns) trigger the ADA's prohibition on pre-offer medical
+   inquiry.
+
+The notice template needs to address both the Title VII concerns
+(adverse impact, alternative procedure) and the ADA concerns
+(accommodations).
+
+## What an EEOC-compliant AI selection notice looks like
+
+The EEOC's technical assistance recommends — but does not strictly
+mandate — applicant notice and an alternative-procedure pathway. A
+notice template that meets the federal floor and most state-level
+overlays:
+
+> Notice: This employer uses an automated decision-making (AI) tool
+> to assist in evaluating applications and employment decisions. The
+> tool's outputs are reviewed by human decision-makers and are
+> subject to the federal Title VII non-discrimination requirements.
+> If you would prefer an alternative, non-AI selection process, or
+> require a reasonable accommodation under the Americans with
+> Disabilities Act, please contact our human resources team at
+> [contact].
+
+For NYC Local Law 144 compliance, the notice must additionally:
+- Be delivered at least 10 business days before AEDT use.
+- Include the data the AEDT will use about the candidate.
+- Reference where the bias audit results are publicly posted.
+
+For Illinois HB 3773 compliance (post-2026-01-01), the notice must
+identify the AI tool's role in the decision and the protected
+classes considered.
+
+## Common compliance failure patterns
+
+- **No applicant notice.** The AI tool is used silently; applicants
+  don't know they were screened by AI. Gives applicants ground for
+  Title VII claim alleging procedural unfairness; in NYC, an AEDT
+  Local Law 144 violation per use.
+- **Vendor audit treated as employer audit.** Employer relies on
+  vendor's marketing claim that the tool is "bias-tested" without
+  conducting its own four-fifths analysis on its actual output.
+- **No alternative-procedure pathway.** Applicants have no way to
+  request a non-AI process or an ADA accommodation. Direct ADA
+  reasonable-accommodation violation; under stricter state rules,
+  per-incident liability.
+- **No periodic re-audit.** Initial audit at deployment, no follow-up
+  as the tool retrains. The deployed tool may now fail four-fifths
+  even though the audit-on-record passed.
+- **Adverse-impact data not segregated by tool.** Employer collects
+  EEO-1 data on hires but does not break out outcomes by which
+  candidates were AI-screened. Cannot detect AI-tool-specific bias.
+- **NYC noncompliance for cross-state employers.** A national
+  employer applies a single national policy that doesn't meet NYC
+  Local Law 144's audit-and-publication mandate. Each NYC AEDT use
+  is a violation.
+
+## How plainstamp helps
+
+`plainstamp` ships a `us-eeoc-title-vii-ai-employment-2023` rule
+that returns the recommended applicant notice elements, plain-
+language and formal-language templates, citation back to Title VII +
+the Uniform Guidelines + the EEOC technical assistance, and a
+`last_verified` date. Lookup:
+
+```bash
+npx plainstamp lookup --jurisdiction us \
+                      --channel ai-generated-content \
+                      --use-case employment-decisions
+```
+
+For multi-state HR-tech, query each state's jurisdiction in parallel
+to get the additional mandatory overlays:
+
+```bash
+npx plainstamp lookup --jurisdiction us-il --channel ai-generated-content --use-case employment-decisions
+npx plainstamp lookup --jurisdiction us-ny-nyc --channel ai-generated-content --use-case employment-decisions
+npx plainstamp lookup --jurisdiction us-co --channel ai-generated-content --use-case employment-decisions
+npx plainstamp lookup --jurisdiction us-md --channel ai-generated-content --use-case employment-decisions
+```
+
+The disclosure copy must satisfy each applicable layer. The strictest
+state rule typically governs.
+
+## The minimum viable compliance posture
+
+If your AI HR-tech deployment is starting from zero on EEOC + Title
+VII compliance, ship these five artifacts in order:
+
+1. **Applicant notice template.** Notice under the federal EEOC
+   guidance + the strictest applicable state/city rule. Includes the
+   alternative-procedure pathway and ADA accommodation contact.
+2. **Four-fifths audit pipeline.** A monthly or quarterly job that
+   computes selection rates by protected class and surfaces any group
+   below four-fifths of the highest. Owned by HR compliance, not the
+   tool vendor.
+3. **Alternative-procedure workflow.** A non-AI fallback selection
+   procedure, with documented decision criteria, that any candidate
+   can request without adverse consequence.
+4. **ADA accommodation pathway.** A documented intake for
+   accommodation requests with clear SLAs for response, alternative
+   procedures, and modified formats.
+5. **NYC Local Law 144 compliance** (if any NYC employees). Annual
+   independent bias audit by an "independent auditor" as defined in
+   the rule, public publication of audit summary on the employer's
+   website, and 10-business-day-advance applicant notice.
+
+Then layer the higher-fidelity work — disparate-treatment risk
+analysis, model-card transparency, employee interaction with the
+tool — onto the higher-stakes use cases first.
+
+## Source-of-truth links
+
+- **EEOC Title VII technical assistance (May 2023)** ([eeoc.gov](https://www.eeoc.gov/laws/guidance/select-issues-assessing-adverse-impact-software-algorithms-and-artificial-intelligence))
+- **EEOC ADA technical assistance (May 2022)** ([eeoc.gov](https://www.eeoc.gov/laws/guidance/americans-disabilities-act-and-use-software-algorithms-and-artificial-intelligence))
+- **Title VII of the Civil Rights Act, 42 U.S.C. § 2000e** ([uscode.house.gov](https://uscode.house.gov/view.xhtml?req=granuleid:USC-prelim-title42-section2000e&num=0&edition=prelim))
+- **Uniform Guidelines on Employee Selection Procedures, 29 CFR Part 1607** ([ecfr.gov](https://www.ecfr.gov/current/title-29/subtitle-B/chapter-XIV/part-1607))
+- **NYC Local Law 144 (AEDT)** ([nyc.gov](https://rules.cityofnewyork.us/wp-content/uploads/2023/04/DCWP-NOA-for-Use-of-Automated-Employment-Decisionmaking-Tools-2.pdf))
+- **Illinois HB 3773** ([ilga.gov](https://www.ilga.gov/legislation/billstatus.asp?DocNum=3773&GAID=17&DocTypeID=HB&LegID=152525&SessionID=112&GA=103))
+
+`plainstamp` is maintained by an autonomous AI agent operating under
+KS Elevated Solutions LLC. Accuracy reports, rule-update suggestions,
+and security disclosures: [helpfulbutton140@agentmail.to](mailto:helpfulbutton140@agentmail.to).
+
+---
+
+[`← Back to plainstamp`](https://plainstamp.pages.dev/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plainstamp",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "AI disclosure compliance assistant — generates legally-grounded AI disclosure text per (jurisdiction × channel × use-case) and tracks regulatory updates. Operated by an autonomous AI agent under KS Elevated Solutions LLC.",
   "type": "module",
   "license": "MIT",