@kya-os/checkpoint-rules

This is the source of truth for Checkpoint detection rules. Do not maintain rule tables outside this package.

What this package is

The structural fence preventing duplicate rule tables from regrowing across the KYA-OS monorepo. Per ADR-001 — Engine-Centric Consolidation and the Phase 1 architect review (Q5, split-first-then-subtract), this package lands before any subtraction work in the wrapper layer (E-1, E-2, E-3) so downstream consumers can target the SSOT explicitly. Without the fence on npm, wrapper refactors have nowhere to point their rule consumption and duplicate rule tables regrow inside whichever wrapper gets touched first — the exact pathology ADR-001 was written to eliminate.

What this package is NOT

• Not a runtime — no matching logic, no detection, no policy evaluation. Those live in @kya-os/agentshield (legacy) and kya-os-engine (the Rust engine; D-design issue #2484 / D-impl issue #2485).
• Not a host wrapper — those are the agentshield-express, agentshield-nextjs, etc. packages.
• Not the only place rules will ever live during the transition — Phase 1.1 work migrates the existing YAML rule files from packages/agentshield-shared/src/data/ into this package and collapses the parallel sources. Until then, this package is the declared SSOT and agentshield-shared is the in-flight legacy source.

Current state — Phase 1 week 1

Empty package skeleton. The only export is a VERSION constant for smoke-testing and a RULES_SCHEMA_VERSION constant matching the kyaos.rulesSchemaVersion field in package.json. The CI publish pipeline is live. The architectural firewall takes effect on publish, not on Phase 1.1 completion — any PR that adds a rule table outside this package after the fence lands is a contract violation.

Roadmap

| Phase | Work | Issue | | ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | Phase 1 week 1 (this PR) | Publish empty fence package; declare SSOT contract; wire CI publish | Pkg-1 #2481 | | Phase 1 week 2 | Migrate the 14 YAML rule files from agentshield-shared/src/data/ into this package | Codegen-1 (TBD) | | Phase 1 week 2-3 | Single-writer YAML compile gate; CI fails if pnpm compile-rules produces a diff | Codegen-1 (TBD) | | Phase 1 week 4 | Rust ⇄ JS matcher equivalence test consumes the golden corpus from this package | Equivalence-1 (TBD) |

Architectural rule

If you find yourself about to add a new YAML rule file, a new patterns.ts constant, a new regex table, or any other detection-rule source outside this package, stop. The rule belongs here.

When in doubt see CONTRIBUTING.md § "Rules SSOT" at the repo root.

Stability

This package is published at 0.1.0 and follows semver. The kyaos.rulesSchemaVersion field in package.json versions the rules schema independently of the npm package version: schema changes follow ADR-001's additive-forever policy (locked-decisions table row 10), so rulesSchemaVersion bumps are major only when a field is renamed or removed, never for additions.

License

MIT OR Apache-2.0.