thefrontside / thefrontside/effectionx

Make each policy independently executable through XMD

Open
#257 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
12
Forks
4
Avg merge
3h 17m
Merged PRs (30d)
1

Description

Parent Quest: #254

Story

As an effectionx contributor, I want to run any policy document through XMD and see how it reached its verdict, so policy validation is explicit, inspectable, and independently reproducible.

The common path for one policy is:

xmd run .policies/<policy>.md#Validate

Current gap

Policy documents currently explain requirements to the Policy Officer agent but do not expose executable validation entrypoints. They also do not state whether a lint rule or AI procedure is authoritative, leaving validator selection and required evidence implicit.

Contract

Every active policy listed by .policies/index.md provides a standard XMD Validate entrypoint while remaining useful as human-readable documentation.

Each policy declares:

  • the invariant it protects and the files or changes to which it applies;
  • whether validation delegates to an @effectionx/lint rule or performs an AI review;
  • the exact lint rule invocation or AI instructions;
  • the repository context and comparison inputs required;
  • the evidence that supports the verdict; and
  • a consistent pass or failure result consumable by a parent XMD workflow.

A lint-backed policy executes its named Oxlint rule rather than asking an agent to reinterpret the same syntax. An AI-backed policy contains the contextual review procedure in the document and may not rely on an undisclosed agent prompt or validator-selection heuristic.

Running one policy does not require the README aggregator. The policy index remains the authoritative inventory used to discover active policies.

Acceptance

  • Every policy in .policies/index.md has a runnable #Validate entrypoint.
  • Running a lint-backed policy executes its exact @effectionx/lint rule and propagates the rule’s exit status and diagnostics.
  • Running an AI-backed policy supplies the declared context and returns its required verdict and evidence shape.
  • A policy with missing inputs or unavailable validation prerequisites fails visibly instead of being silently skipped.
  • Repeated runs use the same declared validator, inputs, and output contract.
  • Adding a policy to the active index without a valid entrypoint causes a repository check to fail.
  • Existing policy explanations and links remain readable outside XMD.

Evidence

Verification runs every active policy independently and includes:

  • a lint-backed violation and compliant control;
  • an AI-backed relevant change and irrelevant control; and
  • a policy-index entry with a missing validator as the negative discovery case.

Dependencies

  • Depends on #256 for lint-backed policy rules.
  • Blocks historical end-to-end verification and README composition in #254.

Out of scope

  • The README aggregate entrypoint
  • CI policy execution
  • Deno lint compatibility
  • Policies outside the effectionx repository
  • Requiring byte-identical prose from AI validators

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with .policies/index.md and inspect each active policy's current human-readable content and available XMD structure. Run the documented xmd run .policies/.md#Validate path against a policy, then compare lint-backed and AI-backed behavior with the stated acceptance and evidence cases. Done means every indexed policy has a reproducible Validate entrypoint and missing prerequisites fail visibly.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, testing, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.