# EPURE — Complete Documentation Corpus (EN + FR + Glossary) Source: https://giskard-ai.github.io/epure/ Repository: https://github.com/Giskard-AI/epure --- ## [EN] Introduction & Naming (L'Épure) URL: https://giskard-ai.github.io/epure/introduction # Introduction & The Meaning of EPURE **EPURE** (`Giskard-AI/epure`) is a GitHub-first, specification-driven software engineering framework that combines **structured human architectural governance** with **autonomous multi-agent TDD implementation and code review**. **EPURE** brings a deterministic specification lock (`spec_sha`), a single declarative repository configuration (`.github/agents.yml`), and a reproducible issue-to-release workflow to AI-assisted software engineering. --- ## Why the Name "EPURE"? The name **EPURE** carries a dual meaning rooted in French architectural heritage and modern software engineering: ### 1. The Architectural Blueprint (*L'Épure d'Architecte*) In classical French architecture, stonecutting (*stéréotomie*), and naval carpentry, **une épure** is the full-scale geometrical working drawing traced on a workshop wall or floor before a single block of stone is cut or a beam is shaped. In software engineering with AI agents, the most common failure mode is **premature coding**: letting an LLM guess product requirements, invent domain vocabulary, or silently choose trade-offs inside a pull request. EPURE enforces the exact opposite discipline: 1. **Draw the blueprint first**: On a GitHub tracking issue, the maintainer and the agent clarify every ambiguity through a structured interview (**Grill**). 2. **Version the domain and specification**: Before any application code is written, EPURE commits the ubiquitous language (`GLOSSARY.md`), Architectural Decision Records (`docs/adr/`), the functional & technical specification (`docs/specs/.md`), and—when a user interface is involved—the visual design contract (`DESIGN.md`) onto a dedicated `plan/-` branch. 3. **Machine the parts under a locked mandate**: Only after a human maintainer signs the blueprint with `/epure approve` (locking the exact `spec_sha` in `refs/epure/state/`) do agents execute the dependency-ordered ticket DAG (`task/* -> feature/*`). ### 2. The Bilingual Acronym **EPURE** also stands for the four pillars of its execution engine: | Letter | English Acronym | French Acronym | Engineering Role | | --- | --- | --- | --- | | **E** | **Engineered** | **Élaboration** | Structured design interview (`/epure plan` & Grill) that surfaces trade-offs before coding. | | **P** | **Planning** | **Plans** | Versioned `GLOSSARY.md`, ADRs, `DESIGN.md`, Specification, and dependency-ordered ticket DAG (`blocked_by`). | | **U** | **Unified** | **Usinage** | Secretless TDD implementation loop (`npm test`, `npm run build`, contract checks) on isolated `task/*` branches. | | **R** | **Review** | **Revue** | Multi-agent specialist code review loaded from trusted `dev`, Impeccable WCAG AA UI gate, and AI semantic squash. | | **E** | **Execution** | **Exécution** | Governed integration (`feature/* -> dev` human merge) and fast-forward release promotion (`dev -> main`). | --- ## The Three-Tier Step Taxonomy (Q101) A core principle of EPURE is transparency about **who decides** and **what runs automatically**. Every step in an EPURE workflow belongs to one of three formal categories: ### 1. Mandatory Human Validation Gates (4) No agent can ever bypass these four decision points. They require an explicit action from a repository contributor with `write` or `admin` permission: 1. **Gate 1 — Initiate & Answer the Grill (`/epure plan`)**: A maintainer triggers `/epure plan` on a GitHub Issue and answers the clarifying questions until the design frontier is settled. 2. **Gate 2 — Sign the Implementation Mandate (`/epure approve`)**: After reviewing the generated spec and ticket DAG on `plan/-`, a maintainer comments `/epure approve`. This directly integrates the `plan/*` artifacts into `feature/-` (with additive `GLOSSARY.md` merging and monotonic ADR renumbering, without an intermediate `plan/* -> dev` PR per ADR-0031), locks `spec_sha` in `refs/epure/state/`, and begins executing the ticket DAG. 3. **Gate 3 — Human Integration Merge (`feature/* -> dev`)**: Once all tickets in the DAG are implemented, reviewed, and squashed into `feature/*` (and verified by `EpicConvergenceAudit`), EPURE opens the final synthesis PR `feature/* -> dev`. The `epure-dev-governance` ruleset **blocks** the Agent App from merging application code into `dev`: a human maintainer must click **Squash and merge**. 4. **Gate 4 — Human Release Promotion (`dev -> main`)**: Promoting `dev` to `main` and publishing a `vX.Y.Z` tag requires a human to trigger the `release-promote.yml` workflow (`workflow_dispatch`). ### 2. Mandatory Automated Steps Once a human gate is crossed, EPURE executes these steps deterministically on every feature: - **Blueprint, Goldfish Spec Audit & Ticket DAG Generation**: Runs the zero-context Goldfish specification audit (`runGoldfishSpecAudit`), commits `GLOSSARY.md`, `docs/adr/`, and `docs/specs/.md` (with `EpicGoalContract`) on `plan/-`, and creates GitHub Issues for each atomic task with native `sub_issues` and `blocked_by` dependencies and the `ready-for-agent` label. - **Secretless Kernel Sandbox TDD Loop**: For each unblocked ticket, applies incremental mutations (`write_repo_file`, `patch_repo_file`, `delete_repo_file`) and runs Stage 1 verification inside an isolated 2-phase Linux kernel sandbox (`landrun` / `bubblewrap`) stripped of `LLM_API_KEY` and GitHub App private keys. - **Event-Driven External CI, Trusted `dev` Multi-Agent Review & AI Semantic Squash**: Exits immediately while external CI runs (`waiting_ticket_ci`), resumes on `check_suite.completed` / `workflow_run.completed`, runs up to 4 domain-specialized reviewers (loaded strictly from `dev`) plus `spec-parity-reviewer`, and squash-merges `task/* -> feature/*` with a synthesized Conventional Commit title/body (`Refs #`). - **Zero-Context `EpicConvergenceAudit` & Final Synthesis PR Review**: Runs `runEpicConvergenceAudit` on `feature/*` to ensure all `required_entrypoints` are wired and no `forbidden_stubs` remain (spawning Phase 2 convergence tickets if needed), then opens and audits the consolidated synthesis PR `feature/* -> dev` with `Closes #` and `Closes #` trailer links. ### 3. Optional or Conditional Steps These steps run only when triggered by the nature of the change or by an explicit maintainer command: - **Conditional UI & Impeccable Gate (automatic when UI exists)**: When the feature or diff touches frontend/UI files (`.vue`, `.tsx`, `.jsx`, `.css`, `.html`), EPURE automatically generates `DESIGN.md`, runs `user-advocate` in `design-gate` mode before `/epure approve`, and enforces `user-advocate` (`implementation-review`) + `impeccable-gate` as blocking checks on every PR. Pure backend/CLI changes skip these steps automatically. - **Optional Exploratory Prototype (`/prototype` & Isolated Pages Preview)**: When a layout or state interaction cannot be settled in prose during the Grill, a maintainer can request a throwaway prototype on `prototype/*`. Static GitHub Pages preview is **disabled by default** (`enable_pages_preview: false`) and requires explicit opt-in. - **Optional Granular Slash Commands**: - `/epure to-spec`: Validate the Grill frontier (or force early transition) to generate the specification on `plan/*`. - `/epure to-tickets`: Validate the specification on `plan/*` and generate the native GitHub ticket DAG (`sub_issues` + `blocked_by`). - `/epure continue`: Resume orchestration after a `needs-human` pause, manual fix, or external CI completion (`waiting_ticket_ci` / `waiting_feature_ci`). - `/epure sync` (alias `/epure rebase`): Synchronize `dev -> feature/*` (and `feature/* -> task/*`) with 3-way conflict resolution and Stage 1 sandbox verification. - `/epure status`: Refresh and post the current orchestration state and ticket table. - `/epure cancel` (alias `/epure stop`): Immediately halt orchestration and mark the mandate `cancelled` in `refs/epure/state/`. - **Conditional Human Escalation (`needs-human`)**: Triggered automatically if a `task/*` branch touches sensitive paths (`.github/workflows/**`, `.github/agents.yml`, the reviewer roster directory `reviewers_dir/**` (default `.agents/reviewers/**`), `CODEOWNERS`) without an approved exception, or if a ticket still fails after `max_code_fix_attempts = 3` remediation rounds. --- ## Upstream Ecosystem & Credits (ADR-0018) EPURE builds upon and integrates verified, SHA-pinned upstream repositories, agent skills, design systems, and security tools (full attributions in [`NOTICE`](https://github.com/Giskard-AI/epure/blob/dev/NOTICE) and [`skills-lock.json`](https://github.com/Giskard-AI/epure/blob/dev/skills-lock.json)): | Upstream Project | License | Role in EPURE | | --- | --- | --- | | **[Matt Pocock Agent Skills (`mattpocock/skills`)](https://github.com/mattpocock/skills)** | MIT | Core specification-driven agent skills (`grill-with-docs`, `to-spec`, `to-tickets`, `domain-modeling`, `tdd`, `code-review`, `prototype`, `wizard`, `pr` with credit to [Dex Horthy / HumanLayer](https://github.com/humanlayer/humanlayer)). | | **[Impeccable (`pbakaus/impeccable`)](https://github.com/pbakaus/impeccable)** | Apache-2.0 | UX/UI design system workflow (`shape`, `DESIGN.md`, `.impeccable/surfaces/*.md`) and deterministic WCAG 2.1 AA / design token quality gate (`actions/impeccable`, `impeccable-gate`). | | **[Archify (`tt-a1i/archify`)](https://github.com/tt-a1i/archify)** | MIT | Interactive showcase architecture diagram IR & HTML renderer embedded in `scripts/archify/` (`npm run docs:diagrams`). | | **[iFixAi (`ifixai-ai/iFixAi`)](https://github.com/ifixai-ai/iFixAi)** | Apache-2.0 | Deterministic authorization trajectory and privilege boundary auditing (`actions/ifixai`). | | **[zizmor (`woodruffw/zizmor`)](https://github.com/woodruffw/zizmor)** | MIT | Static security analysis for GitHub Actions workflows (`actions/zizmor-audit`). | | **[Renovate (`renovatebot/renovate`)](https://github.com/renovatebot/renovate)** | AGPL-3.0 (Tool) | Automated updates of SHA-pinned workflows and dependencies with optional assisted migration (`auto_migrate`). | --- ## [EN] Installation & /setup-repo Skill URL: https://giskard-ai.github.io/epure/installation # Installation & Bootstrap The recommended way to initialize or reconfigure a repository with EPURE is to invoke the **`/setup-repo` agent skill** (`.agents/skills/setup-repo/SKILL.md`) directly inside your Skills-compatible coding agent. The `/setup-repo` skill orchestrates the entire bootstrap end-to-end: it inspects your repository's actual architecture, walks you through the interactive wizard (`setup-github-apps-wizard.sh`) to register your two GitHub Apps and isolated GitHub Environments (`` and `release`), runs the deterministic CLI (`dist/cli/setup-repo.mjs`) in `--dry-run` simulation mode before `--apply`, and **dynamically designs your multi-agent reviewer roster (`reviewers_dir`, default `.agents/reviewers/*.md`)**. --- ## System Requirements Before bootstrapping a repository with EPURE, ensure your local environment has: - **A Skills-compatible coding agent** (any IDE or CLI agent that can load `.agents/skills/setup-repo/SKILL.md`) - **Node.js 24 LTS** (`>=24.0.0`) - **GitHub CLI (`gh`)** authenticated against your target GitHub account or organization (`gh auth status`) - **Git** (`>=2.38`) - **An LLM API Key** (`LLM_API_KEY` or custom provider key configured in `.github/agents.yml`) --- ## Recommended Way: Bootstrap via the `/setup-repo` Skill Open your target repository in your coding agent and invoke the **`/setup-repo`** skill: ```text /setup-repo my-org/craft-calculator ``` The agent executes a guided **4-step workflow** with explicit human confirmation before any sensitive action: ### Step 1: Agent Inspection of Stack & Domain Elements Before writing any file, the agent inspects the target repository (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `src/` directory layout, UI presence, existing `GLOSSARY.md`) to determine: - The language and build stack to configure `.github/workflows/ci.yml`, `verification.targets`, `renovate.json`, `.github/zizmor.yml`, and `standards-reviewer.md`. - Whether the repository includes a frontend/UI surface (which determines whether the **Impeccable** gate and `frontend-reviewer`, `accessibility-reviewer`, and `design-reviewer` are included). - Which domain subsystems warrant creating **custom specialist reviewers** in `.agents/reviewers/-reviewer.md` (or your configured `reviewers_dir`). ### Step 2: Provision the Two GitHub Apps & Environment-Scoped Secrets (Wizard) To enforce strict privilege separation (Q82, Q91) and Zizmor-compliant zero secret exposure to unprivileged PR workflows, EPURE never uses a single all-powerful Personal Access Token or global repository secrets. Instead, every repository uses **two distinct GitHub Apps** and **two isolated GitHub Environments** (`` and `release`): 1. **Agent App (`-epure-agent`)**: Used by the orchestrator for day-to-day automation (`plan/*`, `task/*`, `feature/*`, Issues, PRs, and Check Runs). It is **never** a Bypass Actor on `dev` or `main`. 2. **Release App (`-epure-release`)**: Used exclusively by the release workflow (your `.github/workflows/release.yml`, which calls EPURE's reusable `release-promote.yml`) when a human dispatches a fast-forward release from `dev` to `main` with `semver_tag` and `expected_dev_sha`. It is the **sole Bypass Actor** on `epure-release-immutability` (`main` and `v*` tags). See [Promote a Release](./guides/how-to-release.md) for the one-time environment protection (required reviewer, `dev`-only deployment branch policy). Launch the interactive wizard, which supports **Approach 2** (1-click local GitHub App Manifest Flow) with automatic **Fallback Approach 1** (manual step-by-step guided registration) and injects secrets into their dedicated GitHub Environments via `gh secret set --env` without ever exposing PEM private keys to the LLM: ```bash bash scripts/wizards/setup-github-apps-wizard.sh \ --repo my-org/craft-calculator \ --llm-env ``` > **Configurable & LLM-Agnostic ``**: The agent environment name (``) defaults to `epure-agent` and can be chosen freely (other examples: `llm`, `openai`, `anthropic`, or `gemini`; pass the same value to `setup-repo --llm-env`) and matches `environment: ` on the `orchestrate-command` job in `.github/workflows/epure-issue-command.yml`. | Secret Name | GitHub Environment Scope | Purpose | | --- | --- | --- | | `LLM_API_KEY` | `--env ` | API key for the LLM client / proxy sidecar (kept out of `authorize-command` and the code execution sandbox). | | `EPURE_AGENT_APP_ID` | `--env ` | Numeric App ID of `-epure-agent`. | | `EPURE_AGENT_APP_PRIVATE_KEY` | `--env ` | PEM private key of `-epure-agent` (used to mint short-lived installation tokens). | | `EPURE_RELEASE_APP_ID` | `--env release` | Numeric App ID of `-epure-release` (bound to the human-approved `release` environment). | | `EPURE_RELEASE_APP_PRIVATE_KEY` | `--env release` | PEM private key of `-epure-release` (passed by `release.yml` to `release-promote.yml` only). | Verify the environment-scoped secrets with `gh`: ```bash gh secret list -R my-org/craft-calculator --env gh secret list -R my-org/craft-calculator --env release ``` ### Step 3: Non-Destructive Simulation (`--dry-run`) The `/setup-repo` skill first runs the underlying CLI in `--dry-run` mode and presents the complete file, branch, label, and ruleset plan for your approval: ```bash node dist/cli/setup-repo.mjs \ --repo my-org/craft-calculator \ --target-dir /path/to/craft-calculator \ --agent-app-id 123456 \ --release-app-id 654321 \ --dry-run ``` ### Step 4: Guided Application (`--apply`) & Custom Reviewer Roster Design Once you confirm the dry-run report, the `/setup-repo` skill applies the repository governance via `--apply --apply-github-settings`, and then creates and tailors the reviewer prompts in `.agents/reviewers/*.md` (or the directory chosen with `--reviewers-dir`) specific to your repository: ```bash node dist/cli/setup-repo.mjs \ --repo my-org/craft-calculator \ --target-dir /path/to/craft-calculator \ --agent-app-id 123456 \ --release-app-id 654321 \ --apply \ --apply-github-settings ``` Then commit and push the generated files (`.github/`, `.agents/reviewers/`, and `renovate.json`) to `dev`: ```bash git add .github/ .agents/reviewers/ renovate.json git commit -m "chore(epure): bootstrap repository governance and workflows" git push origin dev ``` --- ## What the `/setup-repo` Skill Configures 1. **Branch Topology (`main` & `dev`)**: - Ensures both `main` (immutable release line) and `dev` (active integration branch) exist. - Sets **`dev` as the default branch** of the repository so Pull Requests target `dev` by default and `Closes #` trailers resolve automatically when landing on `dev`. 2. **Canonical Triage Labels**: - Creates or updates the 5 canonical labels (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`) plus orchestration labels (`needs-human`, `approved-sensitive-change`). 3. **Declarative Configuration, Hardened Supply-Chain & Thin Caller Workflows**: - Generates `.github/agents.yml` (flat canonical schema with auto-discovered `verification.targets`), `.github/zizmor.yml` (static workflow security configuration), and `renovate.json` (with 3-to-14-day quarantine cooldowns). - Installs `.github/workflows/epure-issue-command.yml`, `.github/workflows/epure-check.yml`, `.github/workflows/pr-title.yml`, `.github/workflows/ci.yml` (tailored to the detected stack), and `.github/workflows/release.yml`, all pinned to the 40-character commit SHA of `Giskard-AI/epure`. 4. **Dynamic Multi-Agent Reviewer Roster (`reviewers_dir`, default `.agents/reviewers/*.md`)**: - The agent running `/setup-repo` **creates, designs, and adds the appropriate `/-reviewer.md` files as needed** based on the repository's actual elements (further refined during `/epure plan`): - **Always-On Core (Cross-Cutting & Persona)**: `architecture-reviewer`, `security-reviewer`, `spec-parity-reviewer`, `standards-reviewer` (adapted to the detected language: TypeScript, Python, Rust, or Go), and `user-advocate`. - **Agent-Designed Stack, Domain & UI Specialists**: `domain-backend-reviewer`, `infra-reviewer`, any custom domain specialists designed by the agent for your subsystems (e.g. `realtime-reviewer.md`, `combat-engine-reviewer.md`, `sql-migration-reviewer.md` with YAML frontmatter `paths:` routing), and — only when the project includes a UI — the frontend/Impeccable trio (`frontend-reviewer`, `accessibility-reviewer`, `design-reviewer`). - *Illustrative example on `craft-calculator` (TypeScript + React web app)*: the agent composes a 10-reviewer roster combining the always-on core, `domain-backend-reviewer`, `infra-reviewer`, and the 3 UI/Impeccable reviewers. 5. **Squash-Only Merge Governance & 3 Repository Rulesets**: - Configures the repository to allow **Squash merge only** (`allow_squash_merge: true`, `allow_merge_commit: false`, `allow_rebase_merge: false`, `delete_branch_on_merge: true`). - Installs the 3 GitHub Repository Rulesets: - `epure-feature-governance` (`refs/heads/feature/*`): `Agent App` in PR bypass for autonomous `task/* -> feature/*` squash-merges once checks pass. - `epure-dev-governance` (`refs/heads/dev`): No `Agent App` bypass (`required_approving_review_count: 0` by default for solo-maintainer compatibility; configurable via `--require-pr-approvals `). - `epure-release-immutability` (`refs/heads/main`, `refs/tags/v*`): `Release App` as sole Bypass Actor. --- ## [EN] Basic Usage (Case Study: craft-calculator) URL: https://giskard-ai.github.io/epure/basic-usage # Basic Usage (Real-World Case Study: `craft-calculator`) To understand how EPURE works in practice, this guide walks through a complete, anonymized real-world feature lifecycle on a TypeScript/React web application called **`my-org/craft-calculator`** (a probability and cost optimizer for an incremental crafting system). We will follow **Issue #16** from its initial 3-line description all the way to the **`v1.0.0`** production release on `main`. --- ## Your End-to-End User Journey at a Glance At every step of driving an issue, EPURE separates **what you do**, **what runs automatically behind the scenes**, **when EPURE pauses for your next action**, and **how autofix loops, Git conflicts, and recovery work**: | Stage | 1. What Do I Do? | 2. What Happens Behind the Scenes? | 3. When Do I Act Again & 4. How Do I Steer? | | --- | --- | --- | --- | | **1. Grill & Framing** | Open the GitHub Issue, post `/epure plan`, and reply to Grill questions in plain text. | Inspects the codebase, initializes `refs/epure/state/`, and posts targeted Grill rounds until the design frontier is settled. | **Act again** after each Grill round (reply in plain text without slash commands), or run `/epure to-spec` when settled. | | **2. Blueprint & Spec** | Comment `/epure to-spec` (and optionally post plain-text adjustments). | Creates `plan/-`, runs the zero-context **Goldfish Specification Audit**, and commits `GLOSSARY.md`, ADRs, `DESIGN.md` (if UI), and `docs/specs/.md`. | **Act again** once the spec draft is committed: reply in plain text to revise the spec, or comment `/epure to-tickets` when satisfied. | | **3. Ticket DAG & Mandate** | Comment `/epure to-tickets`, review the sub-issues, then comment `/epure approve`. | Wires native GitHub `sub_issues` and `blocked_by` links, merges `plan/* -> feature/*` directly, and locks `spec_sha` in `refs/epure/state/`. | **No action required** once `/epure approve` is posted—EPURE immediately starts executing the ticket DAG. | | **4. Autonomous Ticket Loop** | Nothing during normal execution (optional `/epure status` or `/epure sync`). | For each ticket (`task/* -> feature/*`): **Stage 1** 2-phase kernel sandbox TDD (`bwrap`/`landrun` + `rtk`) -> **Stage 2** zero-cost async CI wait (`waiting_ticket_ci`) -> **Stage 3** trusted `dev` multi-agent review + AI Semantic Squash. | **Autofix 1..3** automatically fixes Stage 1, CI, or review failures. Comment `/epure sync` for 3-way Git conflicts, or `/epure continue` if paused in `needs-human`. | | **5. Convergence & Final Merge** | Review the final `feature/* -> dev` PR and click **Squash and merge** (plus optional `release.yml` for `dev -> main`). | Runs zero-context **`EpicConvergenceAudit`** (spawning Phase 2 tickets automatically if incomplete), opens `feature/* -> dev`, and runs final synthesis CI & review. | **Act again** when the synthesis PR `feature/* -> dev` is green to perform the human Squash & Merge into `dev`. | --- ## Visual State Machine of the Issue Throughout this walkthrough, EPURE persists the orchestration state outside standard branches inside the atomic Git reference `refs/epure/state/16`: --- ## Step 1: Open the Issue & Start the Grill Mandatory Human Gate 1 A maintainer opens **Issue #16** (*"Add exact Markov-chain crafting simulator and responsive web dashboard"*) and posts a comment: ```text /epure plan ``` ### What EPURE Does Automatically 1. **Permission Gate**: Verifies that the commenter has `write` or `admin` access to `my-org/craft-calculator`. 2. **State Initialization**: Creates `refs/epure/state/16` in phase `grilling` and adds the `EPURE Status Dashboard` at the top of Issue #16. 3. **Structured Grill Round 1**: Inspects the repository and posts 4 targeted architectural questions on Issue #16: - *Q1: Should expected cost be computed via Monte Carlo simulation or exact absorbing Markov chains (`45 x 45` transition matrix)?* - *Q2: How should irreversible corruption states be modeled in the state space?* - *Q3: What is the persistence model for user price presets (backend DB vs. versioned `localStorage`)?* - *Q4: Does the web calculator require WCAG 2.1 AA contrast and mobile responsive layout (`320px`–`1440px`)?* ### Replying to the Grill (Implicit Continuity — Q84) Because Issue #16 is in the `grilling` phase, **you do not need to type another slash command**. Simply reply in a normal GitHub comment: ```text 1. Exact absorbing Markov chain solver (Gaussian elimination, zero Monte Carlo variance). 2. Model corruption as an absorbing failure state that triggers item replacement cost. 3. Pure client-side SPA deployed on GitHub Pages with versioned localStorage. 4. Yes, enforce WCAG 2.1 AA and mobile-first responsive layout via Impeccable. ``` > **Batch Comment Cursor (`last_processed_comment_id`, Q75)**: If you post two or three follow-up comments in a row while the runner is queued, EPURE reads all unprocessed comments in strict chronological order on startup—no comment is ever lost. --- ## Step 2: Blueprint, Goldfish Spec Audit & Native Ticket Graph (`/epure to-spec` & `/epure to-tickets`) Mandatory Automated Step + Conditional UI Gate Once your reply settles all open questions on the design frontier, EPURE posts a **Settled Decisions Summary** and pauses in `grilling` (`awaiting_human_approval`). 1. **Generate & Audit the Specification (`/epure to-spec`)**: - Creates branch **`plan/16-markov-craft-calculator`** from `dev`. - Runs a zero-context **Goldfish Specification Audit** (`runGoldfishSpecAudit`) to verify self-containment, YAGNI discipline, and implementation readiness without Grill conversation bias, automatically amending any gaps. - Commits the domain and specification artifacts onto `plan/16-markov-craft-calculator`: - `GLOSSARY.md` (defining *Transition Matrix*, *Absorbing State*, *Expected Craft Cost*). - `docs/adr/0001-exact-markov-solver-and-spa.md`. - `DESIGN.md` (automatically generated because Issue #16 includes a UI surface, defining dark/light tokens, WCAG AA contrast, and responsive breakpoints). - `docs/specs/16-markov-craft-calculator.md` (complete specification including the `EpicGoalContract` entrypoints and `user-advocate` **`design-gate`** persona UX acceptance criteria). - Pauses in phase `spec` (`awaiting_human_approval`) so you can review or revise the spec via plain-text comments on `plan/16-markov-craft-calculator` (no intermediate `plan/* -> dev` PR is opened). 2. **Generate the Native GitHub Ticket DAG (`/epure to-tickets`)**: - Decomposes the validated specification into an acyclic dependency-ordered Ticket DAG on GitHub and wires native GitHub **`sub_issues`** and **`dependencies/blocked_by`** links: - **Issue #25**: *Core absorbing Markov solver & unit tests* (`ready-for-agent`, `blocked_by: []`) - **Issue #26**: *Preset price editor & versioned localStorage hook* (`ready-for-agent`, `blocked_by: [#25]`) - **Issue #27**: *Responsive simulator UI & Impeccable accessibility verification* (`ready-for-agent`, `blocked_by: [#25, #26]`) - Pauses in phase `tickets` (`awaiting_human_approval`) awaiting `/epure approve`. --- ## Step 3: Sign the Mandate (`/epure approve`) Mandatory Human Gate 2 After reviewing the specification on `plan/16-markov-craft-calculator` and the ticket breakdown, the maintainer comments on Issue #16: ```text /epure approve ``` ### What `/epure approve` Locks In (ADR-0031, ADR-0032) - Creates the integration branch **`feature/16-markov-craft-calculator`** from `dev` and **directly integrates the `plan/16-markov-craft-calculator` artifacts** into `feature/16-markov-craft-calculator` (with additive `GLOSSARY.md` merging and monotonic ADR renumbering if `dev` advanced, without opening a `plan/* -> dev` PR). - Records the signed mandate in `refs/epure/state/16` (`spec_sha`, `approved_by`, `approved_at`, `status: "active"`). --- ## Step 4: Incremental Tools, 3-Stage Verification & Event-Driven CI (`task/* -> feature/*`) Mandatory Automated Step + Conditional UI Gate EPURE now executes the ticket DAG in topological order (`#25`, then `#26`, then `#27`): 1. **Incremental File Mutation & Stage 1 Kernel Sandbox**: - Creates `task/25-markov-solver` from `feature/16-markov-craft-calculator`. - Applies code and test changes via incremental workspace tools (`write_repo_file`, `patch_repo_file`, `delete_repo_file`) staged inside `StagedTicketImplementationBuffer` and verified by `validateTicketIntegrityGuard`. - Runs **Stage 1 Verification** inside the 2-phase Ubuntu 26.04 Linux kernel sandbox (`landrun` `https_only` install, offline `bwrap --unshare-net` typecheck/lint/test/build with stateless `rtk` output condensation, completely stripped of `LLM_API_KEY` and GitHub App private keys). - Opens **PR #28** (`task/25-markov-solver -> feature/16-markov-craft-calculator`). 2. **Stage 2 Event-Driven External CI (`waiting_ticket_ci`)**: - Persists `subphase: "waiting_ticket_ci"` in `refs/epure/state/16` and exits `0` immediately so no runner sits idle while GitHub Actions runs external CI on PR #28. - Automatically wakes up when `check_suite.completed` / `workflow_run.completed` fires on `task/25-markov-solver`. 3. **Stage 3 Multi-Agent Review (from trusted `dev`) & AI Semantic Squash**: - Loads the reviewer prompts (`/*.md`, default `.agents/reviewers/*.md`) strictly from `dev` (never from `task/25-*`). - Selects up to 4 relevant reviewers (e.g., `domain-backend-reviewer`, `standards-reviewer`, `security-reviewer`) plus `spec-parity-reviewer`. - For **Ticket #27** (which touches `.tsx` and `.css` files), automatically includes `frontend-reviewer`, `accessibility-reviewer`, `design-reviewer`, `user-advocate` (`implementation-review`), and the **`impeccable-gate`** check. - If external CI or a reviewer emits a `must_fix`, EPURE runs a targeted remediation round (up to `max_code_fix_attempts = 3`). - Once green, EPURE synthesizes a Conventional Commit title and body (`feat(solver): implement exact absorbing Markov chain solver (#28)` with `Refs #25`) and performs an autonomous squash-merge via the `epure-feature-governance` ruleset. --- ## Step 5: Zero-Context `EpicConvergenceAudit`, Final Synthesis PR & Human Merge into `dev` Mandatory Automated Step -> Mandatory Human Gate 3 Once tickets `#25`, `#26`, and `#27` are merged into `feature/16-markov-craft-calculator`: 1. **Zero-Context `EpicConvergenceAudit` (`runEpicConvergenceAudit`)**: Before opening the final PR, an isolated Goldfish session audits `feature/16-markov-craft-calculator` against the specification's `EpicGoalContract` to verify that all `required_entrypoints` are wired end-to-end and no `forbidden_stubs` remain (automatically spawning Phase 2 convergence tickets if any entrypoint was left unwired). 2. EPURE opens the final synthesis **PR #47** (`feature/16-markov-craft-calculator -> dev`) with `Closes #16`, `Closes #25`, `Closes #26`, `Closes #27`. 3. Runs the full synthesis multi-agent review, `impeccable-gate`, and event-driven external CI (`waiting_feature_ci`) on the consolidated diff, updating the PR title and body with a synthesized Conventional Commit summary. 4. **Human Gate 3**: Because `epure-dev-governance` forbids the Agent App from merging code into `dev`, the human maintainer reviews PR #47 and clicks **Squash and merge**. GitHub automatically closes Issues `#16`, `#25`, `#26`, and `#27`. --- ## Step 6: Promote Release `dev -> main` (`v1.0.0`) Mandatory Human Gate 4 When ready to cut a production release, the maintainer dispatches **`EPURE Controlled Release (dev -> main)`** (`.github/workflows/release.yml`) from `dev` with the tag and the reviewed `dev` head SHA, then approves the `release` environment deployment: ```bash DEV_SHA="$(gh api repos/my-org/craft-calculator/branches/dev --jq .commit.sha)" gh workflow run release.yml -R my-org/craft-calculator --ref dev \ -f semver_tag=v1.0.0 -f expected_dev_sha="$DEV_SHA" ``` `release.yml` calls EPURE's reusable `release-promote.yml`. It checks that `expected_dev_sha` is still the `dev` head, that `CI` is green on it, that `v1.0.0` does not exist and that `main` is an ancestor of it; then, with a short-lived **Release App** (`-epure-release`) token, it fast-forwards `main` and pushes the annotated tag `v1.0.0` in one atomic push, publishes the GitHub Release with generated notes, and revokes the token. See [Promote a Release](./guides/how-to-release.md). --- ## [EN] Commands Reference (/epure & /setup-repo) URL: https://giskard-ai.github.io/epure/commands # Commands Reference (`/epure`, `/setup-repo` Skill & CLI) EPURE is operated through two complementary surfaces: 1. **The local `/setup-repo` agent skill** (`.agents/skills/setup-repo/SKILL.md` — the **preferred way** to bootstrap or reconfigure a repository, its Rulesets, and its dynamic reviewer roster in `reviewers_dir`, default `.agents/reviewers/*.md`). 2. **GitHub Issue slash commands (`/epure ...`)** to drive the feature lifecycle day-to-day directly from GitHub Issues. --- ## 1. GitHub Issue Slash Commands (`/epure`) All `/epure` commands are posted as comments on a GitHub Issue. Every command is guarded by a **Fail-Closed Permission Gate**: the commenter must hold `write` or `admin` repository permissions. | Command | Category (Q101) | Target Phase | Description | | --- | --- | --- | --- | | `/epure plan` | Mandatory Human Gate 1 | `grilling` | Initializes `refs/epure/state/`, inspects the repository via read-only exploration tools (`list_repo_files`, `read_repo_file`, `search_in_repo_file`), and starts the structured architectural Grill interview. | | *(Any human comment during Grill)* | Mandatory Human Gate 1 | `grilling` | Implicit Grill continuity (Q84): processes human answers via the batch cursor (`last_processed_comment_id`). If follow-up questions remain (`frontier_resolved: false`), posts the next Grill round. Once all ambiguities are settled (`frontier_resolved: true`), posts a **Settled Decisions Summary** and pauses in `grilling` (`awaiting_human_approval`) so the human validates the decision frontier before `/epure to-spec`. | | `/epure to-spec` | Human Frontier Validation | `spec` | Validates the Grill decision frontier (or forces an early transition), runs the zero-context **Goldfish Specification Audit** (`runGoldfishSpecAudit`), and generates `GLOSSARY.md`, ADRs, `DESIGN.md`, and `docs/specs/.md` (including `EpicGoalContract`) on `plan/*`, then pauses in `spec` (`awaiting_human_approval`) for human review. Free-form comments during `spec` revise the specification on `plan/*`. | | `/epure to-tickets` | Human Spec Validation | `tickets` | Validates the specification on `plan/*` and decomposes it into an acyclic dependency-ordered GitHub Issue DAG (`blocked_by`, `ready-for-agent`), wiring native GitHub relational graph links (`sub_issues` + `dependencies/blocked_by`) and pausing in `tickets` (`awaiting_human_approval`) before `/epure approve`. | | `/epure approve` | Mandatory Human Gate 2 | `implementation` | Integrates the approved `plan/*` artifacts (`GLOSSARY.md` additive merge, monotonic & semantic ADR collision reconciliation, `docs/specs/.md`, `DESIGN.md`) directly into `feature/-` without an intermediate `plan/* -> dev` PR (ADR-0031, ADR-0032), locks the signed `spec_sha` mandate in `refs/epure/state/`, and executes the ticket DAG (`task/* -> feature/*`). | | `/epure continue` | Lifecycle Continuation | `implementation` | Resumes orchestration after a `needs-human` suspension, after resolving a 3-way conflict, or after external CI (`waiting_ticket_ci` / `waiting_feature_ci`) completes (ADR-0031). | | `/epure sync` (alias `/epure rebase`) | Git Branch Sync | `implementation` | Synchronizes `dev -> feature/-` (and cascades `feature/* -> active_task_branch`) with additive `GLOSSARY.md` merging, monotonic ADR reconciliation, 3-way LLM conflict resolution, and **Stage 1 Sandbox** verification before committing (ADR-0031, ADR-0032). | | `/epure status` | Optional Override | *(Read-only)* | Reads `refs/epure/state/` and posts a fresh summary of the current phase, locked `spec_sha`, and per-ticket progress without mutating code. | | `/epure cancel` (alias `/epure stop`) | Optional Override | `cancelled` | Marks the mandate as `cancelled` in `refs/epure/state/`, stops any new ticket execution, and preserves existing branches and audit logs. | > **Contextual `/epure` Command Cheat-Sheet Spoiler (`
`)**: Every issue comment, sub-issue body, and pull request description posted by EPURE automatically includes a collapsible `
` block at the bottom (`⌨️ Commandes /epure disponibles`) summarizing the available slash commands and highlighting the recommended next action for the current lifecycle phase (`grilling`, `spec`, `tickets`, `implementation`, `suspended`, `cancelled`, or `completed`). --- ## 2. End-to-End GitHub Actions & Custom Actions Pipeline (`epure-ci-actions-flow`) ### How Commands & CI Events Flow Through `epure-issue-command.yml` 1. **Job 1 — Secretless Authorization Gate (`authorize-command` using `actions/authorize-command`)**: - Triggered on `issue_comment.created` using only `GITHUB_TOKEN` (`contents: read`, `issues: write`) and **zero agent or LLM secrets**. - Verifies that the commenter is a human with effective `write` or `admin` permission via `GET /repos/{owner}/{repo}/collaborators/{username}/permission`. - With `allow_implicit_planning_reply: "true"`, free-text human comments without a slash prefix are automatically routed as `reply` commands whenever the issue is in the `grilling` or `spec` phase. 2. **Job 2 — Isolated Agent Orchestration (`orchestrate-command` using `actions/orchestrate-issue`)**: - Runs on `ubuntu-26.04` inside the dedicated GitHub Environment (`environment: `, default `epure-agent`; other examples: `llm`, `openai`, `anthropic`, or `gemini`) **only after** `authorize-command` succeeds (or upon an authorized CI continuation event). - Receives the environment-scoped secrets (`EPURE_AGENT_APP_ID`, `EPURE_AGENT_APP_PRIVATE_KEY`, and `LLM_API_KEY` or provider key) and provisions the kernel sandbox tools (`bubblewrap`, `landrun`, `rtk`). - On `/epure to-tickets`, creates the child GitHub Issues and wires native GitHub relational graph links (`sub_issues` parent-child hierarchy + `dependencies/blocked_by` task edges). 3. **Automatic Event-Driven CI Continuation (`check_suite.completed` / `workflow_run.completed`)**: - When `async_ci_continuation: "true"` is enabled, opening a `task/* -> feature/*` PR (`waiting_ticket_ci`) or `feature/* -> dev` PR (`waiting_feature_ci`) records the active PR/SHA in `refs/epure/state/` and immediately exits `0` to free the GitHub Actions runner. - When external CI finishes on `task/*` or `feature/*`, the `check_suite.completed` or `workflow_run.completed` event wakes `orchestrate-command` with `command: "continue"`, `trigger_head_sha`, and `trigger_branch` to run Stage 3 multi-agent review, AI semantic squash, or unified auto-remediation. 4. **Pull Request Gates & Controlled Release Promotion**: - On `pull_request` events (`dev`, `main`, `feature/**`), `epure-check.yml` (`actions/epure-contract`), `pr-title.yml`, and `ci.yml` execute with `contents: read` and zero privileged secrets. - On human `workflow_dispatch` (`semver_tag`, `expected_dev_sha`), `release.yml` calls EPURE's reusable `release-promote.yml`, which runs inside the protected `environment: release` (`EPURE_RELEASE_APP_ID`, `EPURE_RELEASE_APP_PRIVATE_KEY`), checks the role boundary with `actions/verify-app-role`, fast-forwards `dev -> main`, tags, and publishes the GitHub Release. --- ## 3. Repository Bootstrap Agent Skill (`/setup-repo` — Recommended) The **`.agents/skills/setup-repo/SKILL.md`** skill is the **preferred way** to onboard or reconfigure an EPURE consumer repository from any Skills-compatible coding agent: ```text /setup-repo / ``` ### What the `/setup-repo` Skill Does 1. **Project Discovery**: Inspects the repository stack (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`), `src/` module layout, and whether a user interface is present. 2. **Dry-Run Simulation (`--dry-run`)**: Runs `dist/cli/setup-repo.mjs --dry-run` and presents the full plan to the human maintainer before writing anything. 3. **Dynamic Reviewer Roster Design (`reviewers_dir`, default `.agents/reviewers/*.md`)**: Creates, designs, and tailors specialist reviewers according to the project's actual elements (always-on core `architecture-reviewer`, `security-reviewer`, `spec-parity-reviewer`, `standards-reviewer`, `user-advocate` + tailored domain/UI specialists with `paths:` routing). 4. **Idempotent Application (`--apply --apply-github-settings`)**: Writes `.github/agents.yml`, `.github/zizmor.yml`, `renovate.json`, SHA-pinned caller workflows, configures squash-only merges, and provisions the 3 Repository Rulesets. --- ## 4. Underlying Bootstrap CLI (`dist/cli/setup-repo.mjs`) Invoked automatically by the `/setup-repo` skill (or runnable directly from a terminal): ```bash node dist/cli/setup-repo.mjs \ --repo / \ --target-dir \ [--pinned-sha <40-char-sha>] \ [--dry-run | --apply] \ [--apply-github-settings] \ [--no-frontend-reviewers] \ [--domain-reviewers ] \ [--reviewers-dir ] \ [--llm-env ] \ [--model ] \ [--planning-model ] \ [--implementation-model ] \ [--review-model ] \ [--agent-app-id ] \ [--release-app-id ] \ [--require-pr-approvals ] \ [--json] ``` | Flag | Default | Description | | --- | --- | --- | | `--repo ` | *(Required)* | Target GitHub repository slug (e.g., `my-org/craft-calculator`). | | `--target-dir ` (aliases `--dir`, `--repo-root`) | Current directory | Local checkout path where `.github/agents.yml`, `.github/zizmor.yml`, `renovate.json`, workflows, and the reviewer prompts (`/*.md`) are written. | | `--pinned-sha ` | Latest EPURE SHA | Immutable 40-character Git commit SHA of `Giskard-AI/epure` used to pin generated caller workflows. | | `--dry-run` | `true` (if `--apply` omitted) | Prints the complete bootstrap plan without modifying local files or calling write APIs. | | `--apply` | `false` | Writes configuration files (`.github/agents.yml`, `.github/zizmor.yml`, `renovate.json`), caller workflows, and base reviewer prompts (`/*.md`, default `.agents/reviewers/*.md`). | | `--apply-github-settings` | `false` | Applies squash-only repository settings and the 3 Repository Rulesets via the GitHub REST API. | | `--no-frontend-reviewers` | `false` | Omits `frontend-reviewer`, `accessibility-reviewer`, and `design-reviewer` for headless repositories. | | `--domain-reviewers ` | None | Scaffolds additional `/-reviewer.md` specialist files for domain subsystems. | | `--reviewers-dir ` | `.agents/reviewers` | Reviewer roster directory written to `.github/agents.yml` (`reviewers_dir`) and read by the orchestrator from `dev` (e.g. `--reviewers-dir .cursor/agents` for a team that wants Cursor to load the reviewers as subagents). Absolute paths, `.`/`..` segments, and paths under `src/` fail closed with `SECURITY_INVARIANT_VIOLATION`. | | `--llm-env ` | `epure-agent` | GitHub Environment name (`[A-Za-z0-9._-]`) written to `.github/agents.yml` (`llm_environment`) and used by the `orchestrate-command` job of `.github/workflows/epure-issue-command.yml`. Must match the wizard's `--llm-env`. | | `--model ` | — | Sets `models.planning`, `models.implementation`, and `models.review` at once. | | `--planning-model ` | `anthropic/claude-sonnet-4-20250514` | Sets `models.planning`. | | `--implementation-model ` | `anthropic/claude-sonnet-4-20250514` | Sets `models.implementation`. | | `--review-model ` | `openai/gpt-4.1` | Sets `models.review`. | | `--agent-app-id ` | Optional | Numeric GitHub App ID of `-epure-agent` added as PR Bypass Actor on `epure-feature-governance` (`feature/*`). | | `--release-app-id ` | Optional | Numeric GitHub App ID of `-epure-release` added as sole Bypass Actor on `epure-release-immutability` (`main` and `v*`). | | `--require-pr-approvals ` | `0` | Number of human PR review approvals required on `dev` (`0` for solo-maintainer compatibility; `>=1` for teams). | | `--json` | `false` | Emits the full structured `SetupRepoResult` JSON payload to stdout instead of the Markdown summary. | --- ## 5. Interactive GitHub Apps Wizard (`setup-github-apps-wizard.sh`) ```bash bash scripts/wizards/setup-github-apps-wizard.sh \ --repo / \ --llm-env ``` Guides a human maintainer through registering the two GitHub Apps (`-epure-agent` and `-epure-release`) via **Approach 2** (1-click local GitHub App Manifest flow) or **Fallback Approach 1** (manual step-by-step guided registration), creates the isolated GitHub Environments (`` — configurable and LLM-agnostic, default `epure-agent`; other examples: `llm`, `openai`, `anthropic`, `gemini` — and `release`), and uploads the 5 secrets to their respective environments (`EPURE_AGENT_APP_ID`, `EPURE_AGENT_APP_PRIVATE_KEY`, and `LLM_API_KEY` in `--env `; `EPURE_RELEASE_APP_ID` and `EPURE_RELEASE_APP_PRIVATE_KEY` in `--env release`). --- ## [EN] Configuration (.github/agents.yml & renovate.json) URL: https://giskard-ai.github.io/epure/configuration # Configuration Reference (`.github/agents.yml`) EPURE centralizes all orchestration, LLM routing, polyglot verification, web exploration, and non-weakenable security invariants in a single versioned declarative file: **`.github/agents.yml`**. --- ## Complete Canonical Flat Schema (`serializeAgentsConfigYaml` / `parseAgentsYaml`) Below is the canonical flat `.github/agents.yml` file generated by `setup-repo` (`src/bootstrap/setup-repo.ts`) with all supported keys and their defaults (Q78, Q91–Q96, ADR-0028–ADR-0033): ```yaml # EPURE Consumer Repository Configuration (.github/agents.yml) # Generated by setup-repo — security boundaries are enforced by shared workflows (ADR-0010, ADR-0023). harness: pi models: planning: anthropic/claude-sonnet-4-20250514 implementation: anthropic/claude-sonnet-4-20250514 review: openai/gpt-4.1 providers: azure-prod: provider: azure api_key: os.environ/AZURE_OPENAI_API_KEY base_url: os.environ/AZURE_OPENAI_ENDPOINT api_version: 2024-10-21 foundry-deepseek: provider: azure_ai api_key: os.environ/AZURE_AI_API_KEY base_url: https://my-foundry.services.ai.azure.com merge_policy: strict task_auto_merge_enabled: true max_code_fix_attempts: 3 max_epic_phases: 2 max_transient_api_retries: 4 transient_retry_backoff_seconds: [5, 15, 45, 120] llm_request_timeout_seconds: 900 job_timeout_minutes: 60 review_timeout_minutes: 30 max_concurrent_tasks_per_feature: 3 trace_retention_days: 30 preview_retention_days: 14 github_pages_previews: false reviewers_dir: .agents/reviewers llm_environment: epure-agent verification: wait_for_external_ci: true external_ci_timeout_minutes: 15 grace_window_seconds: 45 targets: - name: root working_directory: . kind: node path_patterns: ["**"] install_command: "npm ci --ignore-scripts" typecheck_command: "npm run typecheck" lint_command: "npm run lint" test_command: "npm test" build_command: "npm run build" web_tools: enabled: true phases: ["plan", "spec", "implementation"] max_requests_per_turn: 4 max_requests_per_run: 12 max_bytes_per_response: 16384 max_fetch_bytes: 16384 timeout_ms: 10000 security_invariants: require_write_permission: true sandbox_isolation: true allow_agent_release: false auto_merge_dev: false auto_merge_main: false ``` --- ## Configurable & LLM-Agnostic GitHub Environment (``) In `.github/workflows/epure-issue-command.yml`, the `orchestrate-command` job runs inside a dedicated GitHub Environment (`environment: `) **only after** the secretless `authorize-command` job verifies effective `write` or `admin` permission: - **Free & Provider-Agnostic Naming**: The `` environment name defaults to **`epure-agent`** (`llm_environment` in `.github/agents.yml`) and is completely configurable via `setup-repo --llm-env ` and `setup-github-apps-wizard.sh --llm-env ` (use the same value for both). It is agnostic of the underlying LLM provider (other examples: `llm`, `openai`, `anthropic`, or `gemini`) and must only contain `[A-Za-z0-9._-]`. - **Zizmor-Compliant Secret Isolation**: `EPURE_AGENT_APP_ID`, `EPURE_AGENT_APP_PRIVATE_KEY`, and `LLM_API_KEY` (or custom provider secret referenced via `os.environ/VAR_NAME`) are scoped strictly to `--env `, while `EPURE_RELEASE_APP_ID` and `EPURE_RELEASE_APP_PRIVATE_KEY` are scoped to the human-approved `--env release` environment. Public pull request workflows and `authorize-command` never have access to any secret. --- ## Section-by-Section Reference ### Root Execution, Retry & Governance Keys | Key | Type | Default | Description | | --- | --- | --- | --- | | `harness` | `"pi" \| "codex"` | `"pi"` | Agent execution adapter harness used for sandboxed runs. | | `merge_policy` | `"strict" \| "relaxed"` | `"strict"` | Stale-base policy for `task/* -> feature/*` integration (`strict` requires up-to-date base; `relaxed` allows clean 3-way merge when approved diff is unchanged). | | `task_auto_merge_enabled` | `boolean` | `false` (`true` when CI & branch protections exist) | Enables autonomous squash-merge of validated `task/* -> feature/*` PRs; forced to `false` (`AUTO_MERGE_DISABLED_MISSING_PROTECTIONS`) if required CI or branch protections are missing. | | `max_code_fix_attempts` | `integer` | `3` | Maximum number of automated remediation rounds (Stage 1 sandbox, external CI, or multi-agent review) per ticket before escalating to `needs-human` (Q78). | | `max_epic_phases` | `integer` (`1..3`) | `2` | Maximum number of epic execution phases when `runEpicConvergenceAudit` detects unwired entrypoints (`[Phase 2 - Ticket N]`, ADR-0032). | | `max_transient_api_retries` | `integer` | `4` | Per-HTTP-request retry ceiling for transient LLM errors (`5xx`, `408`, network timeout). `HTTP 429` rate limits honor `Retry-After` (up to 10 waits) without consuming this quota. | | `transient_retry_backoff_seconds` | `[int, int, int, int]` | `[5, 15, 45, 120]` | Exponential backoff schedule in seconds between transient HTTP retries. | | `llm_request_timeout_seconds` | `integer` | `900` | Unitary HTTP request timeout in seconds (`15 minutes`) for each LLM API call. | | `job_timeout_minutes` | `integer` | `60` | Wall-clock timeout in minutes for `orchestrate-command` in `.github/workflows/epure-issue-command.yml` (Q78). | | `review_timeout_minutes` | `integer` | `30` | Timeout in minutes for multi-agent PR review jobs (with up to `max_parallel_reviewers = 4` specialist/transverse reviewers selected per PR diff alongside `spec-parity-reviewer`). | | `max_concurrent_tasks_per_feature` | `integer` | `3` | Maximum number of unblocked `task/*` tickets executed concurrently per `feature/*` branch. | | `trace_retention_days` | `integer` | `30` | Retention period in days for minimized audit trajectories (`iFixAi`). | | `preview_retention_days` | `integer` | `14` | Number of days before hosted `/prototype` previews are automatically purged (Q71). | | `github_pages_previews` | `boolean` | `false` | Opt-in flag (legacy alias `enable_pages_preview: false`) to publish static `/prototype` previews to an isolated GitHub Pages origin; requires `github_pages_human_consent: true` and `preview_separate_origin: true` (Q70, Q73). | | `reviewers_dir` | `string` (relative path) | `".agents/reviewers"` | Reviewer roster directory where `setup-repo` writes and the orchestrator reads reviewer prompt files `.md` (always from the trusted `dev` branch, falling back to EPURE's embedded templates). Configurable via `setup-repo --reviewers-dir ` (for example `.cursor/agents` for a team that wants Cursor to load the reviewers as subagents). Absolute paths, paths with `.` or `..` segments, and paths under `src/` are rejected fail-closed with `SECURITY_INVARIANT_VIOLATION`. | | `llm_environment` | `string` (`[A-Za-z0-9._-]`) | `"epure-agent"` | GitHub Environment name used by the `orchestrate-command` job of the generated `.github/workflows/epure-issue-command.yml` (`environment: `). Configurable via `setup-repo --llm-env `; must match the environment created by `setup-github-apps-wizard.sh --llm-env `. | ### `models` & `providers` (Multi-Provider Routing — ADR-0029) EPURE includes a zero-dependency multi-provider `LLMClient` supporting **Google Gemini** (`google/` or `gemini/`), **OpenAI** (`openai/`), **Azure OpenAI** (`azure/`), **Azure AI Foundry** (`azure_ai/`), and **Anthropic** (`anthropic/`). `models.planning`, `models.implementation`, and `models.review` are **required**: EPURE has no fallback model, consistent with ADR-0012's no-automatic-fallback principle. A non-empty `model` input on the `orchestrate-issue` action overrides all three phases; otherwise each phase uses its `models.` value verbatim. When a command that calls an LLM finds a key missing, it suspends with a `needs-human` escalation (`model_config_missing`) naming the key to set, before any LLM call; commands that make no LLM call (`status`, `cancel`, replies outside grilling/spec, `continue` with nothing waiting) are unaffected. EPURE reads `.github/agents.yml` from `dev` (from `main` only when `dev` has no such file); a file that fails to parse is never ignored or replaced by the `main` copy: commands that call an LLM escalate to `needs-human` with the parser message (`Invalid .github/agents.yml on 'dev': ...`). | Key | Type | Default | Description | | --- | --- | --- | --- | | `models.planning` | `string` | *(Required; `setup-repo` writes `"anthropic/claude-sonnet-4-20250514"`)* | Model used for `/epure plan` Grill interviews, `/epure to-spec` / `/epure to-tickets`, and plan-to-feature ADR reconciliation (`/` or bare model). Override with `setup-repo --planning-model` (or `--model` for all phases). | | `models.implementation` | `string` | *(Required; `setup-repo` writes `"anthropic/claude-sonnet-4-20250514"`)* | Model used for incremental workspace tool loops (`write_repo_file`, `patch_repo_file`), 3-way conflict resolution, `/epure sync` ADR reconciliation, and Stage 1/2/3 auto-remediation. Override with `setup-repo --implementation-model` (or `--model`). | | `models.review` | `string` | *(Required; `setup-repo` writes `"openai/gpt-4.1"`)* | Model used for the multi-agent PR review roster, `runGoldfishSpecAudit`, `runEpicConvergenceAudit`, `user-advocate`, and squash commit synthesis (requested at temperature `0.0`; no temperature is sent to Claude Opus 4.7+ / Claude 5.x+). Override with `setup-repo --review-model` (or `--model`). | | `providers..provider` | `"google" \| "openai" \| "azure" \| "azure_ai" \| "anthropic"` | *(Optional)* | Underlying protocol family for a custom provider alias referenced in `models.*` (`/`). | | `providers..api_key` | `string` | `os.environ/` | Secret-free environment variable reference (`os.environ/VAR_NAME`) resolved at runtime from `process.env`. Never commit literal API keys in `.github/agents.yml`. | | `providers..base_url` | `string` | Provider default | Custom base URL or `os.environ/VAR_NAME`. | | `providers..api_version` | `string` | `"2024-10-21"` | Azure OpenAI deployment API version (`?api-version=...`). | | `providers..default_headers` | `Record` | `{}` | Optional custom HTTP headers attached to every request for this provider alias. | | `providers..effort` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | *(Optional, model default)* | Anthropic only: sent as `output_config.effort` on every request for every model routed through this alias (e.g. `effort: high` for `anthropic/claude-haiku-5-5`). Omitted when unset. Any other value makes `.github/agents.yml` invalid: commands that call an LLM escalate to `needs-human` with the parse error. `temperature` is automatically omitted for Claude Opus 4.7+ and Claude 5.x+ models, which reject sampling parameters. | An Anthropic response with `stop_reason: refusal` raises an `LLMError` with `reasonCode: "REFUSAL"`. It is not retried: the orchestrator suspends with a `needs-human` escalation (`llm_refusal`) without consuming the ticket's `max_code_fix_attempts` budget. ### `verification` & `verification.targets` (Polyglot Stage 1 & Stage 2 CI — ADR-0028, ADR-0030) Always loaded at runtime from the trusted `dev` branch so an untrusted `task/*` branch can never weaken its own test commands: | Key | Type | Default | Description | | --- | --- | --- | --- | | `verification.wait_for_external_ci` | `boolean` | `true` | Enables Stage 2 external CI waiting (`waiting_ticket_ci` / `waiting_feature_ci`) on `task/*` and `feature/*` PRs. | | `verification.external_ci_timeout_minutes` | `integer` | `15` | Maximum external CI wait ceiling in minutes before timeout classification. | | `verification.grace_window_seconds` | `integer` | `45` | Grace window in seconds after PR push to allow GitHub Actions check runs to register before evaluating completion. | | `verification.deferred_external_workflows` | `string[]` | `[]` | Optional workflow names deferred from per-ticket `task/*` blocking and enforced only on `feature/* -> dev`. | | `verification.targets` | `VerificationTargetSpec[]` | Auto-discovered by `setup-repo` | Per-subproject Stage 1 verification targets (`name`, `working_directory`, `kind`: `node \| python \| rust \| go \| make \| custom`, `path_patterns`, `install_command`, `codegen_command`, `typecheck_command`, `lint_command`, `test_command`, `build_command`) executed inside the 2-phase Ubuntu 26.04 kernel sandbox (`landrun` + `bubblewrap`). | ### `web_tools` (Confined Public Web Exploration — ADR-0031) | Key | Type | Default | Description | | --- | --- | --- | --- | | `web_tools.enabled` | `boolean` | `true` | Enables zero-API-key read-only public Web exploration tools (`web_search`, `web_fetch`) constrained to `https://` port `443` with strict Anti-SSRF filtering and `` wrapping. | | `web_tools.phases` | `string[]` | `["plan", "spec", "implementation"]` | Lifecycle phases allowed to invoke `web_search` and `web_fetch` (excluded from `review` by default). | | `web_tools.max_requests_per_turn` | `integer` | `4` | Maximum Web tool requests permitted within a single LLM turn. | | `web_tools.max_requests_per_run` | `integer` | `12` | Maximum Web tool requests permitted across an entire orchestrator run. | | `web_tools.max_bytes_per_response` | `integer` | `16384` | Maximum UTF-8 byte budget returned per tool response. | | `web_tools.max_fetch_bytes` | `integer` | `16384` | Maximum UTF-8 byte budget returned per `web_fetch` call after HTML stripping. | | `web_tools.timeout_ms` | `integer` | `10000` | Per-request HTTP timeout in milliseconds for Web exploration calls. | ### `security_invariants` & Sensitive Paths Any attempt in `.github/agents.yml` to weaken `security_invariants` (`require_write_permission: false`, `sandbox_isolation: false`, `allow_agent_release: true`, `auto_merge_dev: true`, `auto_merge_main: true`) is rejected fail-closed with `SECURITY_INVARIANT_VIOLATION`. Furthermore, any modification to `.github/workflows/**`, `.github/agents.yml`, the reviewer roster directory (the configured `reviewers_dir/**` and the default `.agents/reviewers/**`), or `CODEOWNERS` on a `task/*` branch triggers a **Sensitive Path Escalation** (`needs-human`) unless a maintainer explicitly adds the `approved-sensitive-change` label (Q81, Q93). --- ## Supply-Chain & Renovate Security Policy (`renovate.json` & `.github/zizmor.yml`) Every EPURE repository ships a hardened **`renovate.json`** and **`.github/zizmor.yml`** generated by `/setup-repo` (Q46–Q48): - **Quarantine Cooldown (No Day-1 Merges)**: Enforces `minimumReleaseAge: "3 days"` globally (`"7 days"` for minor updates and GitHub Actions/Docker images, `"14 days"` for major npm updates) coupled with `internalChecksFilter: "strict"` and `prCreation: "not-pending"` so newly published or compromised packages are quarantined before any PR is opened. - **Maximum Safe Automation**: Groups minor, patch, pin, and digest updates into single weekly PRs (`npm-minor-and-patch`, `github-actions`, `docker`), pins exact versions (`rangeStrategy: "pin"`, `helpers:pinGitHubActionDigests`, `docker:pinDigests`), runs monthly `lockFileMaintenance`, and automatically rebases behind `dev` (`rebaseWhen: "behind-base-branch"`). - **Post-Install Script Isolation**: Injects `npmrc: "ignore-scripts=true"` during Renovate lockfile resolution to prevent untrusted lifecycle scripts from executing. - **No Unreviewed Auto-Merge into `dev`**: `automerge: false` and `platformAutomerge: false` are strictly enforced; Renovate PRs target `dev`, run the full CI + multi-agent review pipeline, and optionally trigger the assisted `auto_migrate` agent if a breaking change is detected on a verified Renovate App PR. --- ## [EN] Architecture, Security & Multi-Agent Review URL: https://giskard-ai.github.io/epure/architecture # Architecture, Security & Multi-Agent Review Model EPURE is built from the ground up around **Defense-in-Depth**, **Least Privilege**, and **Out-of-Branch Deterministic State**. Every automation boundary is enforced both by GitHub Repository Rulesets and by local runtime sandboxing. > **Interactive Event & Custom Actions Pipeline Diagram**: See the [`epure-ci-actions-flow` diagram in Commands Reference](./commands#2-end-to-end-github-actions-custom-actions-pipeline-epure-ci-actions-flow) for the complete mapping of GitHub events (`issue_comment`, `check_suite`, `workflow_run`, `pull_request`, `workflow_dispatch`), secretless `authorize-command`, environment-scoped `orchestrate-command` (`environment: `), and `release` promotion. --- ## 1. Security & Trust Boundaries Architecture ### Key Architectural Invariants 1. **Dual GitHub App Separation & Environment-Scoped Secrets (`-epure-agent` vs. `-epure-release`, Q82 & Q91)**: - The **Agent App** mints short-lived RS256 installation tokens scoped to day-to-day orchestration (`plan/*`, `task/*`, `feature/*`). Its credentials (`EPURE_AGENT_APP_ID`, `EPURE_AGENT_APP_PRIVATE_KEY`) and `LLM_API_KEY` are scoped to the dedicated agent GitHub Environment (``) and never exposed to `authorize-command` or public PR workflows. It is a Bypass Actor **only** on `epure-feature-governance` (`refs/heads/feature/*`), allowing autonomous integration of verified atomic tasks while physically blocking it from merging application code into `dev` or pushing to `main`. - The **Release App** is invoked exclusively by `release-promote.yml` / `release.yml` under human `workflow_dispatch` inside the protected `release` GitHub Environment (`EPURE_RELEASE_APP_ID`, `EPURE_RELEASE_APP_PRIVATE_KEY`). It is the sole Bypass Actor on `epure-release-immutability` (`refs/heads/main` and `refs/tags/v*`). 2. **Secretless Sandbox Execution (Q74)**: - When EPURE runs `npm test`, `npm run build`, or `pytest` on a `task/*` branch, the child process environment is scrubbed of `LLM_API_KEY`, `EPURE_AGENT_APP_PRIVATE_KEY`, and `EPURE_RELEASE_APP_PRIVATE_KEY`. - A malicious or compromised test script cannot exfiltrate credentials. If sandbox isolation fails, EPURE aborts **fail-closed**. 3. **Out-of-Branch CAS State (`refs/epure/state/`, Q76)**: - State transitions (`last_processed_comment_id`, signed `spec_sha`, retry counters, ticket status table, and active CI continuation subphases) are stored as JSON blobs inside `refs/epure/state/` updated via atomic `git update-ref` Compare-And-Swap. - `dev` and `main` remain 100% free of machine-state commit noise. --- ## 2. Multi-Agent PR Review, Impeccable Gate & AI Squash Pipeline ### How the Review Pipeline Works (Q92–Q96) 1. **Trusted `dev` Roster Loading & Prompt-Injection Defense (OWASP LLM01)**: - Reviewer prompts (`/*.md`, default `.agents/reviewers/*.md`) are **always** loaded from the trusted `dev` branch (with fallback to EPURE's embedded canonical templates), never from the untrusted `task/*` branch under review. - All PR diffs, commit messages, and issue comments are wrapped inside `` XML delimiters with explicit instructions to ignore any embedded prompt-override directives. 2. **Dynamic Selection (Up to 4 Specialists + `spec-parity-reviewer`)**: - Based on the files touched in the PR diff, EPURE selects up to 4 relevant reviewers from the roster (`domain-backend-reviewer`, `frontend-reviewer`, `infra-reviewer`, `architecture-reviewer`, `security-reviewer`, `standards-reviewer`, `accessibility-reviewer`, `design-reviewer`, `user-advocate`) alongside the mandatory `spec-parity-reviewer`. 3. **Read-Only Codebase Inspection Tools**: - Reviewers are not restricted to a narrow unified diff: they can invoke 4 read-only tools (`list_files`, `read_file`, `read_line_range`, `search_code`) to trace callers, types, and domain invariants across the repository. 4. **Targeted Auto-Remediation (`max_code_fix_attempts = 3`)**: - If any reviewer emits a `must_fix` item, EPURE runs a targeted code fix in the secretless sandbox and re-runs **only** the reviewers that failed in the previous round plus `spec-parity-reviewer`. - On `feature/* -> dev` synthesis PRs, any remediation is routed through a `task/review-fix-*` PR so `epure-feature-governance` is respected. 5. **AI Semantic Squash Synthesis (Q94)**: - Immediately before merging a validated PR, a zero-temperature call synthesizes a clean Conventional Commit title (`type(scope): summary (#PR)`) and bulleted body (`Refs #` on `feature/*`, `Closes #` / `Closes #` on `dev`). 6. **Integrated Upstream Quality & Audit Engines**: - **[Matt Pocock Agent Skills (`mattpocock/skills`)](https://github.com/mattpocock/skills)** — Specification-driven skills (`grill-with-docs`, `to-spec`, `to-tickets`, `tdd`, `code-review`) pinned in `skills-lock.json`. - **[Impeccable (`pbakaus/impeccable`)](https://github.com/pbakaus/impeccable)** — Design system (`DESIGN.md`) and WCAG 2.1 AA frontend quality gate (`actions/impeccable`). - **[iFixAi (`ifixai-ai/iFixAi`)](https://github.com/ifixai-ai/iFixAi)** — Deterministic authorization trajectory auditing (`actions/ifixai`). - **[Archify (`tt-a1i/archify`)](https://github.com/tt-a1i/archify)** — Showcase-validated interactive architecture diagrams (`scripts/archify/`). - **[zizmor (`woodruffw/zizmor`)](https://github.com/woodruffw/zizmor)** — GitHub Actions workflow static security analysis (`actions/zizmor-audit`). - **[Renovate (`renovatebot/renovate`)](https://github.com/renovatebot/renovate)** — Automated updates of SHA-pinned workflows and dependencies (`auto_migrate`). --- ## 3. Multi-Provider `LLMClient`, Native Structured Outputs & Modular Orchestrator (ADR-0029) 1. **Multi-Provider HTTP Router (`src/llm/`)**: - Zero-dependency TypeScript `LLMClient` routing `/` identifiers across **Google Gemini** (`google/`, `gemini/`), **OpenAI** (`openai/`), **Azure OpenAI** (`azure/`), **Azure AI Foundry** (`azure_ai/`), and **Anthropic** (`anthropic/`), with `os.environ/VAR_NAME` lazy resolution from `.github/agents.yml`. - Enforces ADR-0012 fail-fast resilience: HTTP `401`/`403` (`AuthenticationError`) and `402` (`QuotaExhaustedError`) immediately halt without silent fallback, while transient `408`/`429`/`5xx` errors apply bounded exponential backoff. 2. **Native Schema-Enforced Structured Outputs (`ResponseSchemaSpec`) & 2-Phase Gemini Tool Loop**: - All structured LLM calls (`GrillRoundEvaluation`, `GeneratedPlanningBundle`, `GeneratedTicketImplementation`, multi-agent reviewer findings, `user-advocate`, and squash commit synthesis) send formal JSON Schemas (`responseSchema`, `response_format.json_schema` with recursive `additionalProperties: false`, or `output_config.format`) paired with runtime TypeScript validators in `src/orchestrator/prompts/schemas.ts`. - When Google Gemini calls combine repository exploration tools (`list_repo_files`, `search_in_repo_file`, `read_repo_file`) with a `ResponseSchemaSpec`, **Phase 1** executes tool rounds with `functionDeclarations` (preserving Gemini 3 `thoughtSignature` tokens), and **Phase 2** finalizes with `functionCallingConfig.mode = "NONE"` + `responseMimeType: "application/json"` + `responseSchema`. 3. **Modular `src/orchestrator/` Architecture & Wired Safety Guards**: - `src/orchestrator/issue-orchestrator.ts` acts as a clean coordinator delegating to `github/rest-client.ts`, `workspace/repo-tools.ts`, `prompts/schemas.ts`, `formatting/comments.ts`, and the phase modules `phases/grill-and-plan.ts`, `phases/ticket-execution.ts`, and `phases/feature-integration.ts`. - Enforces DAG cycle detection (`validatePlanningArtifactsAndGraph`), proven blocker resolution (`reconcileProvenTicketDependencies`, escalating to `needs-human` on `not_planned` closures), mid-run `/epure cancel` batch cursor checks (`processPendingIssueCommentsBatch`), and commit-SHA review loop guards (`evaluateReviewFeedbackTrigger`). --- ## 4. 3-Stage Verification Pipeline, Ubuntu 26.04 Kernel Sandbox & Event-Driven CI Continuation (ADR-0028, ADR-0030, ADR-0031) 1. **Stage 1 — 2-Phase Linux Kernel Sandbox, Stateless `rtk` Condensation & Per-Ticket Goldfish Isolation**: - Runs on `ubuntu-26.04` (Linux kernel 7.0) inside a persistent local Git clone before any commit is pushed to `task/*`: - **Phase A (`install`, `networkPolicy: "https_only"`)**: Executes dependency installation under `landrun` (Landlock ABI v8), restricting outbound TCP to port `443` and filesystem writes to `workDir`, `/tmp`, and package caches. - **Phase B (`codegen`, `typecheck`, `lint`, `test`, `build`, `networkPolicy: "offline"`)**: Executes completely offline under `bubblewrap` (`bwrap --unshare-net --unshare-pid --unshare-ipc --tmpfs /tmp --die-with-parent`, with automatic fallback to offline `landrun`). - **Stateless `rtk` Output Condensation (`formatAndCondenseStage1CommandOutput`)**: Strips ANSI sequences, progress bars, and noisy test logs in 100% stateless mode (`RTK_TELEMETRY_DISABLED=1`, `RTK_RECALL=0`, `RTK_TEE=0`, no SQLite database) while preserving the raw 4,000-character error tail whenever `exit_code !== 0`. - **3-Way Git Branch Sync (`/epure sync`) & Goldfish Isolation**: Keeps `dev -> feature/* -> task/*` synchronized with 3-way LLM conflict resolution validated by Stage 1, and executes each ticket in a fresh zero-context Goldfish session (`runGoldfishSpecAudit` during `/epure to-spec`). 2. **Stage 2 — Event-Driven External CI Continuation (`waiting_ticket_ci` / `waiting_feature_ci`)**: - Once Stage 1 passes and the `task/* -> feature/*` or `feature/* -> dev` Pull Request is opened alongside the `ai-review` check, EPURE records `subphase: "waiting_ticket_ci"` (or `"waiting_feature_ci"`), `active_pr_number`, and `active_head_sha` in `refs/epure/state/` and immediately exits `0` (`async_ci_continuation: true`). - No runner sits idle polling external workflows. When GitHub emits `check_suite.completed` or `workflow_run.completed` (or a human posts `/epure continue`), EPURE resumes from the exact persisted state. 3. **Stage 3 — Trusted `dev` Multi-Agent Review Roster & AI Semantic Squash**: - Correlates external CI results with the multi-agent specialist review roster loaded from `dev`. If external CI or any reviewer fails, EPURE extracts sanitized failure logs (~12 KB) and executes up to `max_code_fix_attempts = 3` unified remediation rounds before AI semantic squash-merging `task/* -> feature/*`. --- ## 5. Incremental Workspace Mutation Tools, Inter-Ticket Guard & Multi-Phase Epic Convergence (ADR-0032, ADR-0033) 1. **Transactional Incremental Workspace Mutation (`StagedTicketImplementationBuffer`)**: - During ticket implementation and remediation tool loops, the model mutates files incrementally via `write_repo_file`, `patch_repo_file`, and `delete_repo_file` inside an in-memory transactional buffer (`StagedTicketImplementationBuffer`), isolated from `feature/*` until `validateWorkspaceFileOperations`, `validateTicketIntegrityGuard`, and Stage 1 sandbox checks succeed. - **Chunked File-by-File Fallback (`ChunkedTicketImplementationFallback`)**: If a multi-file ticket hits `MAX_TOKENS` output truncation, EPURE automatically decomposes the remaining `filesToTouch` entries into file-by-file sub-calls (preserving already staged mutations in the buffer and rolling back atomically if any sub-call fails). - **Zero-Truncation Context Catalog (`CompactWorkspaceFilesContext`)**: Injects full, untruncated file contents only for files modified by the ticket or listed in `filesToTouch`, and exposes the rest of the repository as a compact `path (N lines)` index inspectable on demand via `read_repo_file` and `search_in_repo_file`. 2. **Native GitHub Relational Graph, Inter-Ticket Integrity Guard & Semantic ADR Reconciliation**: - `/epure to-tickets` wires native GitHub `sub_issues` and `dependencies/blocked_by` relationships alongside the Markdown tasklist on the tracking issue. - `validateTicketIntegrityGuard` blocks any ticket from deleting or emptying pre-existing test files, truncating >30% of lines/exports on out-of-scope files, or downgrading manifest `build`/`test`/`lint`/`typecheck` scripts into no-op commands. - `renumberCollidingAdrs` and `reconcileAdrsWithLlm` deduplicate ADR slugs across concurrent branches, renumber colliding `docs/adr/NNNN-*.md` files monotonically, and align cross-references in specs and `GLOSSARY.md`. 3. **Zero-Context `EpicConvergenceAudit` & Multi-Phase Remediation (`max_epic_phases`)**: - Before opening the final `feature/* -> dev` PR, an isolated zero-context session (`runEpicConvergenceAudit`) verifies the feature branch against the specification's `EpicGoalContract` (`required_entrypoints`, absence of `forbidden_stubs`, and `end_to_end_verification_criteria`). - If unwired modules or stubs are detected (`verdict: "INCOMPLETE"`) and `epic_phase < max_epic_phases` (default `2`), EPURE automatically generates, links, and executes bounded **Phase 2 convergence tickets** (`[Phase 2 - Ticket N]`) before opening the final PR; otherwise it escalates with `epic_convergence_exhausted` (`needs-human`). --- ## [EN] How-To: Onboard a Repository URL: https://giskard-ai.github.io/epure/guides/how-to-onboard-repo # How-To: Onboard a Repository with the `/setup-repo` Skill This guide shows how to take a brand-new or existing GitHub repository (such as `my-org/craft-calculator`) and onboard it by invoking **the `/setup-repo` agent skill** (`.agents/skills/setup-repo/SKILL.md`)—the preferred way to configure EPURE's 2 GitHub Apps, environment-scoped secrets (`` and `release`), `.github/agents.yml`, `.github/zizmor.yml`, `renovate.json`, dynamic reviewer roster (`reviewers_dir`, default `.agents/reviewers/*.md`), and 3 Repository Rulesets. --- ## 1. Create the Two GitHub Apps & Environment-Scoped Secrets EPURE separates day-to-day agent privileges from production release privileges using two GitHub Apps and scopes all secrets to dedicated GitHub Environments (Zizmor-compliant zero global secret exposure): - **`-epure-agent`**: Permissions `contents: write`, `issues: write`, `pull_requests: write`, `checks: write`. - **`-epure-release`**: Permissions `contents: write`, `metadata: read`. Run the interactive wizard (supports **Approach 2** 1-click GitHub App Manifest Flow and **Fallback Approach 1** manual guided mode), specifying your target repository and chosen agent environment name (`--llm-env `, default `epure-agent`; other examples: `llm`, `openai`, `anthropic`, or `gemini`): ```bash bash scripts/wizards/setup-github-apps-wizard.sh \ --repo my-org/craft-calculator \ --llm-env ``` Verify that the secrets are registered in their respective GitHub Environments: ```bash gh secret list -R my-org/craft-calculator --env gh secret list -R my-org/craft-calculator --env release ``` Expected output for `--env `: ```text EPURE_AGENT_APP_ID EPURE_AGENT_APP_PRIVATE_KEY LLM_API_KEY ``` Expected output for `--env release`: ```text EPURE_RELEASE_APP_ID EPURE_RELEASE_APP_PRIVATE_KEY ``` --- ## 2. Invoke the `/setup-repo` Skill (Inspection & `--dry-run` Simulation) Inside your Skills-compatible coding agent, invoke the **`/setup-repo`** skill on the target repository: ```text /setup-repo my-org/craft-calculator ``` The agent inspects the repository's elements (language, build scripts, UI presence, sub-domains in `src/`) and first runs the CLI in `--dry-run` mode: ```bash node dist/cli/setup-repo.mjs \ --repo my-org/craft-calculator \ --target-dir /path/to/craft-calculator \ --agent-app-id 123456 \ --release-app-id 654321 \ --dry-run ``` Check that the dry-run report presented by the agent lists: - Creation of `.github/agents.yml` (flat canonical schema with auto-discovered `verification.targets`), `.github/zizmor.yml`, and `renovate.json`. - Creation of `.github/workflows/epure-issue-command.yml`, `epure-check.yml`, `pr-title.yml`, `ci.yml`, and `release.yml` pinned to the 40-character SHA of `Giskard-AI/epure`. - Dynamic initialization of the reviewer roster in `.agents/reviewers/*.md` (or the `--reviewers-dir` you chose) designed by the agent for your stack and sub-domains (always-on core `architecture-reviewer`, `security-reviewer`, `spec-parity-reviewer`, `standards-reviewer`, `user-advocate` + tailored domain/UI specialists, yielding 10 agents for the `craft-calculator` web app example). - Creation of the 3 Repository Rulesets (`epure-feature-governance`, `epure-dev-governance`, `epure-release-immutability`). --- ## 3. Confirm Application (`--apply`) & Commit to `dev` Once you confirm, the `/setup-repo` skill runs `--apply --apply-github-settings` and tailors the `/-reviewer.md` definitions to your domain modules: ```bash node dist/cli/setup-repo.mjs \ --repo my-org/craft-calculator \ --target-dir /path/to/craft-calculator \ --agent-app-id 123456 \ --release-app-id 654321 \ --apply \ --apply-github-settings ``` Then commit and push the generated files (`.github/`, `.agents/reviewers/`, and `renovate.json`) to `dev`: ```bash cd /path/to/craft-calculator git checkout dev git add .github/ .agents/reviewers/ renovate.json git commit -m "chore(epure): bootstrap repository governance and workflows" git push origin dev ``` --- ## 4. Solo Maintainer vs. Team Mode (`--require-pr-approvals`) - **Solo Maintainer (Default `--require-pr-approvals 0`)**: GitHub does not allow a user to approve their own Pull Request. Setting `required_approving_review_count: 0` on `epure-dev-governance` ensures you can click **Squash and merge** on `feature/* -> dev` PRs opened by EPURE while still blocking the `Agent App` from self-merging. - **Multi-Maintainer Team (`--require-pr-approvals 1` or higher)**: Require at least one peer human approval in addition to green `verify-contract` and `ai-review` checks before merging into `dev`. --- ## [EN] How-To: Drive an Issue End-to-End URL: https://giskard-ai.github.io/epure/guides/how-to-drive-an-issue # How-To: Drive an Issue End-to-End This guide provides a practical checklist for steering a feature or complex bugfix from an initial GitHub Issue to a ready-to-merge `feature/* -> dev` Pull Request, including optional overrides and failure recovery. --- ## 1. Launching the Plan (`/epure plan`) 1. Open a GitHub Issue describing the goal, user problem, or feature scope. 2. Post `/epure plan` in a comment. 3. Wait for the `epure-issue-command` workflow to post **Grill Round 1**. ### Tips for Answering the Grill - **Reply in plain Markdown**: You do not need to prefix your answers with `/epure` while the issue is in phase `grilling`. - **Multiple comments are safe**: Thanks to the batch cursor (`last_processed_comment_id`), if you add a second comment with an extra constraint while a run is queued, EPURE will process both comments in order. - **Short-circuiting the Grill (Optional)**: If you feel the questions are already answered and want to jump straight to specification generation, comment `/epure to-spec`. --- ## 2. Generating & Reviewing the Specification (`/epure to-spec` & `/epure to-tickets`) Once the Grill decision frontier is resolved (`frontier_resolved: true`), EPURE posts a **Settled Decisions Summary** and pauses in `grilling` (`awaiting_human_approval`). 1. **Generate the Specification (`/epure to-spec`)**: Comment `/epure to-spec` to run the zero-context **Goldfish Specification Audit** (`runGoldfishSpecAudit`) and commit `GLOSSARY.md`, `docs/adr/NNNN-*.md`, `DESIGN.md` (if UI is involved), and `docs/specs/.md` (including `EpicGoalContract`) onto `plan/-`. The issue transitions to `spec` (`awaiting_human_approval`). 2. **Revise or Validate the Specification**: - Inspect `GLOSSARY.md`, `docs/adr/`, and `docs/specs/.md` on `plan/-`. - To request adjustments to the specification before creating tickets, **reply directly in a comment** (without a slash command). 3. **Generate the Ticket DAG (`/epure to-tickets`)**: Once the specification is approved, comment `/epure to-tickets`. EPURE decomposes the spec into an acyclic dependency-ordered GitHub Issue DAG (`blocked_by`, `ready-for-agent`), wires native GitHub `sub_issues` and `dependencies/blocked_by` graph links, and pauses in `tickets` (`awaiting_human_approval`) awaiting `/epure approve`. --- ## 3. Approving, Event-Driven CI Continuation & Branch Sync (`/epure approve`, `/epure status` & `/epure sync`) Post `/epure approve` on the tracking issue to directly integrate the `plan/*` artifacts into `feature/-`, lock `spec_sha`, and start executing the ticket DAG. - **Event-Driven External CI Waiting (`waiting_ticket_ci` / `waiting_feature_ci`)**: - Whenever EPURE opens a `task/* -> feature/*` PR (`waiting_ticket_ci`) or the final `feature/* -> dev` PR (`waiting_feature_ci`), the orchestrator records the active PR and `head_sha` in `refs/epure/state/` and immediately exits `0` to release the GitHub Actions runner (`async_ci_continuation: true`). - As soon as external CI workflows complete (`check_suite.completed` or `workflow_run.completed`), EPURE automatically wakes up to run Stage 3 multi-agent review, AI semantic squash, or unified auto-remediation. You can also manually nudge continuation at any time by commenting **`/epure continue`**. - **Synchronizing with `dev` (`/epure sync` / `/epure rebase`)**: - If other PRs land on `dev` while your feature is in progress, comment **`/epure sync`** (or `/epure rebase`). EPURE merges `dev -> feature/-` (and cascades `feature/* -> active_task_branch`) with additive `GLOSSARY.md` merging, monotonic ADR renumbering, 3-way LLM conflict resolution, and mandatory **Stage 1 Kernel Sandbox** verification before committing. - **Inspecting Live Progress (`/epure status`)**: - Comment `/epure status` or check the **EPURE Status Dashboard** pinned at the top of the issue body. - Inside the GitHub Actions run logs, expand the structured `::group::` sections to inspect Stage 1 kernel sandbox test/build output, read-only reviewer tool calls (`read_file`, `search_code`), and per-reviewer verdicts (`approved` vs. `changes_requested`). --- ## 4. Handling `needs-human` Escalations, `/epure continue` & Phase 2 Convergence Tickets EPURE pauses and applies the `needs-human` label (`status: "suspended"`) when human judgment is required: 1. **Sensitive Path Modification**: A `task/*` branch modified `.github/workflows/**`, `.github/agents.yml`, the reviewer roster directory (`/**`, default `.agents/reviewers/**`), or `CODEOWNERS`. - *Resolution*: Inspect the diff. If legitimate, add the `approved-sensitive-change` label to the PR and comment **`/epure continue`** (or `/epure approve`) on the tracking issue. 2. **Remediation Cap Reached (`max_code_fix_attempts = 3`)**: A ticket failed Stage 1 tests, external CI, or reviewer `must_fix` checks 3 times in a row. - *Resolution*: Push a manual fix commit to the `task/*` or `feature/*` branch (or post a clarifying comment), then comment **`/epure continue`** on the tracking issue. EPURE removes `needs-human`, restores `status: "active"`, skips all already-closed tickets, and resumes from the current milestone. 3. **Zero-Context `EpicConvergenceAudit` & Automatic Phase 2 Tickets (`max_epic_phases`)**: - After all Phase 1 tickets are squashed into `feature/*`, EPURE runs a zero-context **`EpicConvergenceAudit`** (`runEpicConvergenceAudit`) against the specification's `EpicGoalContract`. - If the audit finds unwired `required_entrypoints` or lingering `forbidden_stubs` (`verdict: "INCOMPLETE"`) and `epic_phase < max_epic_phases` (default `2`), EPURE automatically creates, links, and executes bounded **`[Phase 2 - Ticket N]`** convergence tickets before opening the final `feature/* -> dev` PR. If gaps still remain after `max_epic_phases`, EPURE escalates to `needs-human` (`epic_convergence_exhausted`), where you can push a fix and comment **`/epure continue`**. 4. **Missing Model Configuration or Invalid `.github/agents.yml`**: A command that calls an LLM found neither the action `model` input nor one of `models.planning`, `models.implementation`, or `models.review` (`model_config_missing`, the comment names the missing keys), or `.github/agents.yml` on `dev` fails to parse (`internal_error`, the comment quotes the parser message). EPURE has no fallback model. - *Resolution*: Fix or complete `.github/agents.yml` on `dev` (or re-run `setup-repo`, which fills in missing `models.*` keys), then re-post the original `/epure` command; `/epure continue` only resumes implementation-phase runs. --- ## [EN] How-To: Customize Reviewers & Impeccable Gate URL: https://giskard-ai.github.io/epure/guides/how-to-customize-reviewers # How-To: Customize the Multi-Agent Reviewer Roster & Impeccable Gate When you invoke the **`/setup-repo`** skill (and subsequently during `/epure plan`), EPURE dynamically composes and adapts the reviewer roster in the reviewer roster directory (`reviewers_dir` in `.github/agents.yml`, default `.agents/reviewers/*.md`, configurable via `setup-repo --reviewers-dir `) along with the **[Impeccable (`pbakaus/impeccable`)](https://github.com/pbakaus/impeccable)** UI quality gate (`DESIGN.md` + `impeccable-gate`), building on the specification and review workflows from **[Matt Pocock's `mattpocock/skills`](https://github.com/mattpocock/skills)**. This guide explains how the roster is assembled for your project and how to tailor it while preserving prompt-injection immunity. --- ## 1. Always-On Core vs. Dynamic Specialists in `reviewers_dir` The roster generated by `/setup-repo` is not static: it combines an **always-on cross-cutting core** with **conditional specialists** tailored to your stack and sub-domains (such as the 10-agent example generated for the `craft-calculator` React web app, or custom specialists added via `--domain-reviewers realtime,game-systems` and `--no-frontend-reviewers` for headless repositories): | Reviewer File | Category | Generation & Selection Condition | | --- | --- | --- | | `architecture-reviewer.md` | Always-On Cross-Cutting | Checks deep module boundaries, ADR compliance, and `GLOSSARY.md` ubiquity. | | `security-reviewer.md` | Always-On Cross-Cutting | Audits secret hygiene, injection surfaces, and privilege boundaries. | | `spec-parity-reviewer.md` | Always-On Cross-Cutting | Runs on **every** PR (`task/* -> feature/*` and `feature/* -> dev`) to verify 1-to-1 parity with the approved spec. | | `standards-reviewer.md` | Always-On Cross-Cutting (Stack-Aware) | Adapted to the detected stack (TypeScript `it.each`, Python `pytest.mark.parametrize`, Rust, or Go). | | `user-advocate.md` | Always-On Persona Gate | Operates in **`design-gate`** mode (on `plan/*` before `/epure approve`) and **`implementation-review`** mode (on PRs). | | `domain-backend-reviewer.md` (`+ -reviewer.md`) | Dynamic Domain Specialist | Tailored to the repo's domain (and extendable via `--domain-reviewers `); selected when domain logic or APIs change. | | `infra-reviewer.md` | Dynamic Infra Specialist | Selected when CI workflows, build scripts, or dependency manifests change. | | `frontend-reviewer.md` | Conditional UI Specialist | Generated when the repo includes a UI; selected when `.vue`, `.tsx`, `.jsx`, or client state hooks are modified. | | `accessibility-reviewer.md` | Conditional UI / Impeccable | Generated when the repo includes a UI; audits WCAG 2.1 AA contrast, semantic HTML, ARIA attributes, and `:focus-visible`. | | `design-reviewer.md` | Conditional UI / Impeccable | Generated when the repo includes a UI; verifies adherence to `DESIGN.md` tokens, responsive layout, and interaction states. | --- ## 2. How the Agent Creates & Customizes Reviewer Prompts Safely Because the reviewer roster directory (`/**`, default `.agents/reviewers/**`) is a **trusted sensitive path** (Q92): 1. **Tailored Reviewer Creation during `/setup-repo` (and manual additions on `dev`)**: During initial setup, the agent inspects your codebase and can design new specialist files in `/-reviewer.md` with a `paths:` attribute in the YAML frontmatter (e.g., `paths: src/realtime, src/ws`). Whenever a PR touches a file matching `paths:` (or ``), `selectReviewersForDiff` automatically selects that specialist. 2. **Always commit changes to `dev`**: At runtime, the EPURE orchestrator loads `/*.md` exclusively from the trusted `dev` branch (falling back to EPURE's embedded templates)—never from an unmerged `task/*` branch. 3. **Automatic Domain Enrichment during `/epure plan`**: When `/epure plan` runs on a new feature, EPURE enriches the domain reviewers and `/user-advocate.md` on the `plan/-` branch with new domain invariants and personas. When you run `/epure approve`, those updates merge into `dev` before any `task/*` ticket starts. --- ## 3. Dogfooding & Customizing `DESIGN.md` (Impeccable Gate) Whenever a repository or PR includes frontend files (`.vue`, `.tsx`, `.jsx`, `.css`, `.html`), the **`impeccable-gate`** check (`evaluateImpeccableFrontendPr`) validates the diff against `DESIGN.md`. ### Blocking vs. Non-Blocking Findings `impeccable-gate` blocks a PR **only** on objective, verifiable violations: - **Accessibility (`accessibility`)**: Missing `title` on `