Quest: Run deterministic policy validation from the effectionx README

Story

As an effectionx contributor, I want every policy to declare how it is validated and be runnable through XMD from the README, so local and CI reviews apply the same policy set using the validation method each policy defines.

The common path is a documented README entrypoint that runs the complete policy suite. A contributor can also run an individual policy document while developing or investigating a finding.

Current gap

The repository’s policies are prose documents interpreted by the Policy Officer agent. Contributors cannot run the complete policy set from the README, mechanically enforceable policies are not connected to lint rules, and there is no historical corpus showing that the complete mechanism detects known violations while accepting their fixes.

Some Effection policies describe syntax and scope patterns suitable for static analysis. Others require contextual judgment from an AI reviewer. Without an explicit validation declaration in each policy, the choice of validator and the evidence needed for a verdict remain implicit.

Contract

Each policy document is an independently executable XMD entrypoint and remains the authoritative explanation of the policy. It declares:

• the behavior or invariant being protected;
• whether validation is performed by an Oxlint rule or an AI review procedure;
• the exact rule invocation or review instructions;
• the inputs and evidence required for a verdict; and
• the observable pass or failure result.

Lint-backed policies identify their exact @effectionx/lint rule and execute that validator. AI-backed policies contain the review procedure and evidence requirements needed to evaluate the policy. Validation selection is never inferred from an agent’s discretion.

The README composes the individual policy entrypoints into one documented command. Local use and CI invoke the same XMD workflow, policy index, pinned tool versions, and repository inputs.

Static analysis is preferred whenever a policy can be enforced reliably by syntax, scope, or type-aware analysis. Oxlint is the sole static policy engine; Deno lint compatibility is not part of the contract.

Historical verification uses fixed revisions from earlier pull requests. At minimum, a known violating revision must fail its relevant policy and the corresponding fixed revision must pass through the complete XMD validation path.

Acceptance

• Every active policy can be executed independently through a consistent XMD entrypoint.
• Every policy declares whether Oxlint or AI performs its validation and identifies the exact validation procedure.
• A lint-backed policy fails when its associated rule reports a violation and passes when the rule is clean.
• An AI-backed policy receives the declared repository context and returns the required verdict and evidence shape.
• The README documents one command that discovers and runs the complete active policy set.
• CI invokes the same README-backed workflow rather than maintaining a separate policy list or validation path.
• The policy index, README workflow, and individual entrypoints cannot silently omit an active policy.
• A fixed historical revision that contains a known violation fails end-to-end, while its corresponding corrected revision passes.
• Tool and policy versions that affect validation are pinned or otherwise made explicit and reviewable.
• Existing build, typecheck, lint, format, and test commands remain available.

Evidence

The end-to-end verification includes historical fail/pass pairs from:

• PR #226 for asynchronous teardown in finally blocks;
• PR #252 for scope-bound event registration; and
• at least one clean negative control that would expose a validator that reports every inspected change.

Evidence records the exact base and head revisions, selected policies, validator used for each policy, exit status, and findings. Historical fixtures run without depending on the mutable state of GitHub pull requests.

Child stories

1. #253 — Format the repository with Oxfmt — open. Establishes Oxfmt as the sole formatter so later policy work does not carry unrelated formatting churn.
2. #255 — Lint the repository with Oxlint — open; depends on #253. Establishes the static-analysis host while preserving pnpm lint.
3. #256 — Publish Effection policy rules through @effectionx/lint — open; depends on #255. Publishes the lint-backed validators for existing effectionx policies.
4. #257 — Make each policy independently executable through XMD — open; depends on #256. Gives every active policy a public Validate entrypoint that declares its lint or AI procedure.
5. #258 — Test policy validation against historical pull requests — open; depends on #257 and uses #256. Verifies known violations and fixes through the public XMD path using repository-owned fixtures.
6. #259 — Run the complete policy suite from the README and CI — open; depends on #257 and #258. Composes the policy inventory into the contributor and CI entrypoint that completes the Quest.

Completion

The Quest is complete when a contributor can start from the README, run the entire policy suite locally, inspect how every policy was validated, reproduce the same workflow in CI, and observe the required historical failures and fixes.

Out of scope

• Deno lint compatibility
• Requiring AI implementations to produce byte-identical prose
• Policies outside the effectionx repository
• Replacing static checks with AI review when an Oxlint rule can enforce the policy reliably

Start with the README workflow and the repository’s policy documents, then read child issues #253–#259 to understand the formatter, Oxlint, XMD, historical fixtures, and CI dependencies. The work is done when every active policy has an executable validation entrypoint, the README and CI run the same complete suite, and the specified historical fail/pass evidence is recorded.