thefrontside / thefrontside/effectionx
Make each policy independently executable through XMD
Nobody has claimed this yet.
- 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/lintrule 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.mdhas a runnable#Validateentrypoint. - Running a lint-backed policy executes its exact
@effectionx/lintrule 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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