@cassiomc1/forgeloop 0.1.0

package/.cursor/rules/project-loop.mdc

@@ -0,0 +1,18 @@
+---
+description: Universal verified project loop
+alwaysApply: true
+---
+
+# Cursor — Universal Project Loop
+
+1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) before planning or editing.
+2. Confirm [`PROJECT_PROFILE.md`](../../PROJECT_PROFILE.md) from real sources; initialize it in target projects when it remains in `template` mode.
+3. Use [`GUIDE_ROUTER.md`](../../GUIDE_ROUTER.md) to activate all relevant guides and only those guides.
+4. Report the selected guide IDs.
+5. Respect higher-level and local instructions and the latest request.
+6. Make the minimum change, run a specific check, and then run proportional regression checks.
+7. Diagnose failures before fixing them and do not repeat an attempt without new evidence.
+8. Request authority for unrelated external or destructive actions, installations, and publications. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
+9. Report only demonstrated results and checks.
+
+The loop and router are canonical sources; do not duplicate domain rules.

package/.forgeloop/.gitignore

@@ -0,0 +1,2 @@
+# Local resumable task state is untrusted, target-specific data.
+work-state.json

package/.github/copilot-instructions.md

@@ -0,0 +1,16 @@
+# GitHub Copilot — Universal Project Loop
+
+Use these instructions across the repository while preserving more specific
+directory or file rules.
+
+- Read [`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md) before implementing.
+- Confirm [`PROJECT_PROFILE.md`](../PROJECT_PROFILE.md) from evidence. Initialize it in a target project when it remains in `template` mode.
+- Select context with [`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md); use all applicable guides and only those guides.
+- Report the activated guide IDs.
+- Respect the latest request, scope, and higher-level instructions.
+- Make the smallest coherent change and validate it with a specific check followed by proportional regression checks.
+- Diagnose the cause before fixing a failure; do not make random attempts.
+- Do not install unrelated software, publish, delete, migrate, or alter external state without authority. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
+- Report the result, checks actually run, limitations, and publication state.
+
+The loop and router are canonical; do not replicate domain rules here.

package/AGENTS.md

@@ -0,0 +1,16 @@
+# Universal Project Loop Instructions
+
+These instructions apply to the entire repository unless a closer, more
+specific rule overrides them.
+
+1. Follow platform rules, the user's latest request, and applicable local instructions first.
+2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) before planning or changing files.
+3. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md). Confirm facts from their sources; initialize the profile in a target project when it is still in `template` mode.
+4. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select all relevant guides and only those guides.
+5. Briefly report the activated guide IDs.
+6. Make the smallest coherent change, run specific checks, and then run proportional regression checks.
+7. Diagnose a failure before fixing it; do not repeat the same attempt without new evidence.
+8. Do not install unrelated software, publish, delete, migrate data, or change external systems without applicable authority. For a task-scoped missing Qwen-MM-Plugins capability, follow the discovery protocol in `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
+9. Finish with the result, checks actually run, limitations, and publication state.
+
+The guides provide technical defaults; explicit requirements and project evidence prevail.

package/AGENT_COMPATIBILITY.md

@@ -0,0 +1,147 @@
+# Agent Compatibility
+
+`@cassiomc1/forgeloop` installs one canonical engineering loop and the smallest
+native entry point required by each supported agent. The package does not
+install an agent, configure a provider, or run a live model session.
+
+## Optional capability extensions
+
+The installed loop can direct the active agent to inspect its native model and
+harness capabilities. When a task requires a missing multimodal capability,
+the agent may install the smallest task-scoped `Qwen-MM-Plugins` capability
+through the harness's native mechanism or the official upstream installer,
+then verify that the skill/MCP tool is callable before using it. This does not
+turn the package into a model runtime or provider configuration tool: API keys,
+system dependencies, and unrelated environment changes remain separately
+gated. Live model sessions and external plugin installation are outside the
+reproducible `npm test` boundary.
+
+## Support matrix
+
+| Agent | Support | Reads in the installed project | Official documentation |
+| --- | --- | --- | --- |
+| Codex | Direct adapter | `AGENTS.md` | [OpenAI — Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) |
+| Claude Code | Direct adapter | `CLAUDE.md` | [Anthropic — How Claude remembers your project](https://code.claude.com/docs/en/memory) |
+| Cursor | Direct adapter | `AGENTS.md`, `.cursor/rules/project-loop.mdc` | [Cursor — Rules](https://cursor.com/docs/rules) |
+| GitHub Copilot | Direct adapter | `.github/copilot-instructions.md` | [GitHub — Repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions-in-your-ide/add-repository-instructions-in-your-ide) |
+| Antigravity | `AGENTS.md` compatibility | `AGENTS.md` | [Antigravity — CLI best practices](https://antigravity.google/docs/cli/best-practices) |
+| OpenCode | `AGENTS.md` compatibility | `AGENTS.md` | [OpenCode — Rules](https://opencode.ai/docs/rules/) |
+| Hermes | `AGENTS.md` compatibility | `AGENTS.md` | [Hermes — Context files](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/context-files.md) |
+| Pi | `AGENTS.md` compatibility | `AGENTS.md` | [Pi — Coding-agent SDK and context files](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/sdk.md) |
+| Command Code | `AGENTS.md` compatibility | `AGENTS.md` | [Command Code — Memory](https://commandcode.ai/docs/core-concepts/memory) |
+| Freebuff | `AGENTS.md` compatibility | `AGENTS.md` | [Freebuff — Knowledge file names](https://github.com/CodebuffAI/freebuff/blob/main/common/src/constants/knowledge.ts) |
+
+## What direct and compatibility mean
+
+Direct adapters are files with a format or location specifically documented
+by the agent. Compatibility entries use the same root `AGENTS.md`; no second
+copy of the loop is needed because the agent officially recognizes that file.
+
+Claude Code is the important exception: it reads `CLAUDE.md`, not `AGENTS.md`.
+The package therefore installs both files, with the Claude-specific adapter
+pointing to the same canonical loop documents.
+
+Codex, Cursor, and GitHub Copilot may also discover `AGENTS.md` on some
+surfaces. The dedicated files remain useful because they make the behavior
+explicit and cover each product's native entry point.
+
+## Harness capability and bootstrap boundary
+
+An adapter proves that the package installed a supported instruction or context
+entry point. It is not proof of a callable optional tool, isolation feature,
+review primitive, or bootstrap hook in the active harness, even when the
+canonical loop can use one when available.
+
+When a harness supports native context bootstrap or startup verification, prefer
+an explicit unique marker to confirm that the expected instruction path is
+active. When that proof is unavailable, treat the adapter file and repository
+checks as installation evidence only.
+
+Optional capability gaps use the loop fallback rules instead of invented
+commands or assumed integrations. Agents should never invent a tool call to
+simulate missing harness support. Global configuration, provider credentials,
+system packages, and other machine-level setup remain outside the installed
+package boundary.
+
+## Precedence and existing instructions
+
+`forgeloop init` never overwrites an existing instruction file. If the target
+already contains a more specific or higher-priority file, that agent may use
+it instead of the installed entry point:
+
+- Codex can use `AGENTS.override.md` before `AGENTS.md`.
+- Claude Code combines `CLAUDE.md` and closer `CLAUDE.local.md` files.
+- Cursor may combine project rules with user rules and nested rules.
+- Antigravity can add workspace rules under `.agents/rules/`.
+- Hermes gives `.hermes.md`/`HERMES.md` priority over `AGENTS.md`.
+- OpenCode can add instructions through `opencode.json` and uses
+  `CLAUDE.md` as a fallback when `AGENTS.md` is absent.
+- Freebuff recognizes `knowledge.md`, `AGENTS.md`, and `CLAUDE.md`; an existing
+  higher-priority knowledge file can affect which project context is loaded.
+
+When a target already has local rules, keep them and merge only the relevant
+loop reference manually. Run `doctor --path /path/to/project` after resolving
+the merge so missing files and managed drift are visible.
+
+## Deterministic verification boundary
+
+The repository verifies package contents, adapter paths, installation into a
+selected target directory, and the official instruction-file contracts. It
+does not launch Codex, Claude Code, or another provider during `npm test`; live
+sessions require external authentication and are intentionally outside the
+reproducible package test suite.
+
+## Protocol-support commands and degraded mode
+
+The CLI can deterministically evaluate declared routing signals, inspect target
+health, validate local receipts and work state, and report resumable status. It
+does not call an LLM, schedule agents, execute commands from
+`PROJECT_PROFILE.md`, or provide `forgeloop run`/orchestration commands.
+
+If a harness has no subagents, worktrees, web access, MCP, persistent state, or
+Git checkout, the compatible agent continues inline and reports the missing
+capability as a limitation. Inline execution is not independent review, a
+non-Git target cannot provide branch/HEAD drift evidence, and a missing remote
+service is a blocker rather than a simulated success.
+
+The degraded-mode contract is explicit:
+
+| Missing capability | Required behavior |
+| --- | --- |
+| Subagents | Execute the same brief inline; do not claim delegation or independent review. |
+| Worktrees or isolation | Keep ownership boundaries in the brief and serialize conflicting work. |
+| Web or MCP | Use a local equivalent only when it provides compatible evidence; otherwise mark the check not verified or blocked. |
+| Persistent state | Keep the handoff in the current session and report that resume across sessions is unavailable. |
+| Git checkout | Continue with local file evidence, but report that branch/HEAD drift cannot be verified. |
+
+These are limitations of the active harness, not reasons to invent a command,
+provider, remote service, or successful check.
+
+## Installed files
+
+Every initialized project receives this guide plus the canonical documents:
+
+```text
+AGENTS.md
+CLAUDE.md
+AGENT_COMPATIBILITY.md
+LOOP_ENGINEERING.md
+GUIDE_ROUTER.md
+PROJECT_PROFILE.md
+LOOP_SYSTEM_DESIGN.md
+QUALITY_SCORECARD.md
+TERMINOLOGY.md
+EXECUTION_STATE.md
+DELEGATION_PROTOCOL.md
+ORCHESTRATOR_INTEGRATION.md
+THIRD_PARTY_NOTICES.md
+LICENSE
+LICENSE-DOCS.md
+.cursor/rules/project-loop.mdc
+.github/copilot-instructions.md
+ENG/
+schemas/
+```
+
+See the main [README](https://github.com/cassiomc1/mdfiles#readme) for the complete `npx` installation,
+diagnostic, first-run, and update workflow.

package/CLAUDE.md

@@ -0,0 +1,14 @@
+# Claude Code — Universal Project Loop
+
+When working in this repository:
+
+1. Follow higher-level instructions, the user's latest request, and the closest rules for the file in scope.
+2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) before planning or editing.
+3. Verify [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) against real sources. Initialize it in a target project when it remains in `template` mode.
+4. Consult [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md), select all relevant guides and only those guides, and announce their IDs.
+5. Make small changes, run a specific check, and then run proportional regression checks.
+6. Investigate the root cause of a failure before fixing it.
+7. Request authority for unrelated installation, publication, deletion, migration, or another external or destructive action. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
+8. Report current evidence, limitations, and publication state without claiming checks that were not run.
+
+Do not duplicate guide rules here; treat the loop and router as canonical sources.

package/CONTRACT_COVERAGE.md

@@ -0,0 +1,27 @@
+# Protocol contract coverage map
+
+Every critical contract maps to an implementation and executable positive and
+negative evidence. A row is not complete when it has only structural schema
+coverage.
+
+| Contract | Implementation | Positive test | Negative test |
+| --- | --- | --- | --- |
+| Routing work types and primary guides | `src/core/router.js` | `tests/routing-invariants.test.js` and `tests/fixtures/routes/` | unknown work type in `tests/router.test.js` |
+| Routing platform semantics | `src/core/router.js`, `GUIDE_ROUTER.md` | mobile/desktop/server/CI cases in `tests/routing-invariants.test.js` | platform-only no-guide case |
+| Routing exclusions and invariants | `assertRouteInvariants` | route fixture loop | overlap, missing reason, and primary checks |
+| State transitions | `src/core/protocol.js` | `tests/protocol-transitions.test.js` | terminal regression and same-phase cases |
+| Contract and repository freshness | `src/core/work-state.js`, `classifyLoadedWorkState` | `tests/checkpoint-freshness.test.js`, `tests/validate-protocol-cli.test.js` | changed contract/HEAD, omitted contract, and missing comparison |
+| Required artifact freshness | `readRequiredArtifactFingerprints`, `classifyLoadedWorkState` | `tests/checkpoint-freshness.test.js`, `tests/validate-protocol-cli.test.js` | matching hash, missing, and changed artifact cases |
+| Schema health | `inspectSchemaHealth` | `tests/schema-health.test.js` | missing, invalid, and unsupported-version schemas |
+| Evidence vocabulary | `src/core/evidence.js` | `tests/evidence.test.js` | unknown kind and incomplete record |
+| Receipt semantics | `src/core/receipt.js` | `tests/receipt-semantics.test.js` | unsupported publication, review, check, and completion claims |
+| Cross-artifact conformance | `src/core/conformance.js`, `src/commands/validate-protocol.js` | `tests/conformance.test.js`, `tests/validate-protocol-cli.test.js` | `stateClassification`, derived stale details, precedence, mismatch, incomplete, and incompatible fixtures |
+| Delegation conflicts | `src/core/delegation.js` | `tests/delegation-set.test.js` | WRITE/WRITE, WRITE/READ, unknown dependency, and cycle cases |
+| Safe path boundary | `src/core/filesystem.js` | `tests/core.test.js`, `tests/portability.test.js` | traversal, drive escape, and symlink fixtures |
+| Untrusted JSON limits | `src/core/json-safety.js` | `tests/security-limits.test.js` | depth, array, string, and byte limits |
+| Artifact content boundary | `src/core/receipt.js`, `scripts/scan_secrets.py` | `tests/security-limits.test.js`, `tests/test_scan_secrets.py` | nested marker values and scanner fixtures |
+| Deterministic CLI JSON | CLI command modules | route, inspect, status, doctor, state, receipt, and protocol tests | malformed artifact and path-boundary cases |
+
+The map is maintained with the protocol and is intentionally explicit about
+negative evidence. Remote checks, provider calls, publication, and deployment
+remain outside the local contract.

package/DELEGATION_PROTOCOL.md

@@ -0,0 +1,91 @@
+# Delegation protocol
+
+`ForgeLoop` defines coordination contracts but does not schedule agents or
+provide a multi-agent runtime. A compatible harness may execute a validated
+brief through native subagents; a harness without that capability executes the
+same brief inline and reports the degraded mode.
+
+## Task brief
+
+A delegated task is self-contained and versioned:
+
+```json
+{
+  "schemaVersion": 1,
+  "protocolVersion": 1,
+  "taskId": "child-1",
+  "parentTaskId": "parent-1",
+  "objective": "One independently verifiable objective.",
+  "allowedPaths": ["src/feature.js"],
+  "readOnlyPaths": ["README.md"],
+  "dependencies": [],
+  "constraints": [],
+  "requiredGuides": ["clean", "test"],
+  "verification": ["npm test"],
+  "authority": ["write only allowed paths"],
+  "deliverables": ["code and test result"],
+  "executionMode": "delegated"
+}
+```
+
+`allowedPaths` are write ownership. `readOnlyPaths` may be inspected but not
+changed. Absolute paths, traversal, duplicate paths, and allowed/read-only
+overlap are invalid. Two briefs with exact or parent/child write overlap must
+be serialized or assigned to one integration owner. Dependencies are explicit
+and cycles are rejected.
+
+Resource access is classified explicitly:
+
+```text
+WRITE / WRITE → conflict
+WRITE / READ  → SERIAL_REQUIRED
+READ  / READ  → safe
+```
+
+The parent task owns integration. `validateDelegationSet` rejects duplicate
+task IDs, self-dependencies, unknown dependency references, cycles, invalid
+guide/path boundaries, missing verification, missing authority, and secret
+material. It returns `PARALLEL_SAFE`, `SERIAL_REQUIRED`, or `INVALID` with
+stable conflict/error records.
+
+Parallel work is eligible only when shared files, shared state, ordering
+dependencies, and external resources have been checked. A database migration
+and code that depends on its new shape are not independent tasks.
+
+## Result normalization
+
+Every delegated result uses:
+
+```text
+STATUS
+CHANGES
+VERIFICATION
+OPEN FINDINGS
+LIMITATIONS
+```
+
+Valid statuses are `complete`, `complete-with-concerns`, `needs-context`, and
+`blocked`. Results are serializable, secret-free, and validated against
+`schemas/delegated-result.schema.json`.
+Complete results also require structured observed or inferred verification
+evidence.
+
+## Review and integration
+
+An independent reviewer receives the approved brief, resulting diff,
+verification evidence, and known risks. A review is independent only when the
+reviewer identity differs from the implementer and the result explicitly uses
+`reviewType: "independent"`; a second pass by the same identity is self-review.
+
+The parent agent integrates in dependency order:
+
+1. validate each result against its brief;
+2. detect overlapping changes and unresolved findings;
+3. integrate non-overlapping results in dependency order;
+4. run targeted checks and combined regression;
+5. perform final specification and quality review.
+
+If subagents, worktrees, or parallel tools are unavailable, use
+`executionMode: "inline"`. This preserves the task contract but cannot claim
+parallelism or independent review. Missing capabilities are limitations, not
+silent successes.

package/ENG/accessibility-eng.md

@@ -0,0 +1,155 @@
+---
+name: accessibility-eng
+language: en
+description: "Practical WCAG 2.2-oriented accessibility protocol for web, mobile, and desktop."
+version: "2026.09"
+last-reviewed: "2026-08-10"
+---
+
+# Accessibility as a Baseline (A11Y)
+
+> Accessibility instructions adapted from the [A11Y.md](https://github.com/fecarrico/A11Y.md) project (Felipe A. Carriço, MIT license) — a validation protocol and persistent context system for building accessible software from the very first line of code, informed by **WCAG 2.2** and **ISO 9241-171**. It can support evidence for applicable **ADA** or **EAA** obligations, but does not itself determine legal compliance.
+> **Related documents**: for visual/UX direction (palettes, typography, motion), see [`design-code-eng.md`](./design-code-eng.md). For automated testing tools (axe-core, Lighthouse, visual regression), see [`test-code-eng.md`](./test-code-eng.md). For code quality/structure, see [`clean-code-eng.md`](./clean-code-eng.md). For HTML-based video and motion, also see [HyperFrames](https://hyperframes.heygen.com). This file is the canonical reference for **accessibility rules** (WCAG, ARIA, keyboard, focus, screen readers) — it does not repeat the content of the others.
+> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence. Ask for authorization before installing a tool or changing the environment. If no safe equivalent exists, record the required check as blocked and never claim that it passed. Do not install merely optional resources.
+
+## 0. Principle Zero: accessibility as a pre-condition
+
+- Accessibility is not a feature or an incremental improvement; it is a **pre-condition for use**.
+- If a user cannot complete a task due to an accessibility barrier, the feature is considered **technically broken**.
+- **Task completion** success is our primary quality metric.
+
+## 0.1. Compliance profiles
+
+This document's default implementation target is **Standard (AA)**. It supports WCAG-oriented implementation; it does not certify a product or establish automatic legal compliance. Certification and legal obligations depend on an assessment with defined scope, evidence, and the applicable jurisdiction. When generating or reviewing interface code, the agent **MUST ask** the user which profile to apply if not already specified:
+
+| Profile | Target | Contrast (text / UI) | Min font† | Min target | Use case |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **🛡️ Shield (AAA)** | WCAG AAA | 7:1 / 3:1 (SC 1.4.6, 1.4.11) | 14px† | 44×44px (SC 2.5.5) · 48×48px† advised | Regulated industries, healthcare, gov |
+| **⚖️ Standard (AA)** | WCAG AA | 4.5:1 / 3:1 (SC 1.4.3, 1.4.11) | 12px† | 24×24px (SC 2.5.8) · 44×44px† advised | Default. Production apps, public web |
+| **🚀 Launchpad (A)** | WCAG A | 3:1† (house floor) | 10px† | 24×24px† | MVPs, internal tools, prototypes |
+
+*† = **House Rule**, non-normative: this standard's ergonomic policy where WCAG requires less — or nothing — at that level. WCAG defines no minimum font size at any level; Level A defines no contrast or target-size criteria; 44–48px targets come from Apple HIG / Material Design. Skipping a **WCAG SC** at your target level MUST be logged in `EXCEPTIONS.md`; relaxing a **House Rule** is a product decision — record it in `A11Y-DECISIONS.md`.*
+
+*The Launchpad profile additionally requires explicit `EXCEPTIONS.md` documentation for each criterion relaxed below AA.*
+
+> ⚠️ The **Launchpad (A)** profile does NOT relax CRITICAL rules (Section 1). Keyboard operability remains a Level A WCAG requirement; semantic HTML and focus management remain mandatory baseline requirements of this guide at every profile.
+
+## 1. Severity and impact model
+
+Evaluate the impact of any design or implementation decision following these levels:
+
+- 🔴 **CRITICAL:** **operation** failures. Blocks task completion or renders the function unusable (e.g., broken keyboard navigation, click on `div`/`span`, modal without focus management). **MUST FIX.**
+- 🟠 **HIGH:** **perception and readability** failures. Significantly increases the error or abandonment rate (e.g., insufficient contrast, fonts < 12px in critical text, lack of dynamic feedback). **MUST FIX.**
+- 🟡 **MEDIUM:** reduces **efficiency and satisfaction** (e.g., lack of optional keyboard shortcuts, lack of redundant labels). **SHOULD FIX.**
+- 🔵 **LOW:** **cosmetic or polish** impact (e.g., micro-interactions without `aria-label`, improvements to focus indicators that are already visible). **MAY FIX.**
+
+## 2. AI agent behavior contract
+
+To ensure technical integrity, any AI interacting with the project **MUST**:
+
+- **No inference:** never infer accessibility without direct evidence in the code or specification.
+- **Reference APG:** prioritize patterns from the [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/).
+- **Protocol for ambiguity:** follow the *Complex Component Protocol* (Section 5) in case of uncertainty.
+- **Explain trade-offs:** explain impacts on Accessibility vs UX vs Business when suggesting changes.
+- **UI component interrogation:** before adding `onClick` to non-semantic elements, **propose replacing them** with native elements or full ARIA patterns.
+- **Framework adaptation:** examples use React/TSX syntax. On **web** frameworks, transpose patterns to the active project's framework while preserving semantic equivalence.
+- **Platform awareness:** identify the target platform **before** applying any technical reference. The normative layer (Principle Zero, POUR, profiles, severity, governance) is platform-agnostic; the technical references are web-first. On native platforms (iOS, Android, React Native, Flutter), read web references as **semantic intent to translate — never implementation to copy**: no ARIA attributes or CSS pixels outside the web.
+- **Component reuse:** before generating any interactive component, check for an existing implementation in the project or its design system and extend it. Generating a parallel implementation of an existing pattern is a violation.
+- **Decision memory:** choices between equally conformant alternatives (e.g., `alertdialog` vs `dialog` for a destructive confirmation) MUST be recorded in `A11Y-DECISIONS.md` — indexed by pattern, never by screen — and reused in later turns.
+- **Mode awareness:** when generating new code, apply all rules proactively. When reviewing existing code, identify violations, classify by severity (Section 1), and suggest targeted fixes — do not propose full rewrites unless the structural damage is CRITICAL. If an `EXCEPTIONS.md` exists, consult it: an entry there is a legitimate dispensation, but an entry past its expiry date MUST be flagged as 🟠 HIGH technical debt.
+
+## 3. Technical standards (POUR framework)
+
+### Perceivable
+
+- **Contrast (SC 1.4.3, 1.4.11):** text **MUST** have 4.5:1; UI components and meaningful graphics **MUST** have 3:1. Prioritize real **luminance difference** (light vs dark) beyond hue.
+- **Alt text (SC 1.1.1):** informative images **MUST** have a functional description in `alt`; decorative images use `alt=""` or `aria-hidden="true"`.
+- **Channels beyond color (SC 1.4.1):** **MUST NOT** convey state, action, response, or information with color alone. Choose the additional channel appropriate to the meaning — visible text, icon, pattern, or programmatic semantics — without imposing the same visual redundancy in every case.
+- **Visual patterns:** when differentiation in charts or dashboards depends on color, patterns, labels, textures, or distinct line styles **MUST** enable users to distinguish series without color.
+
+### Operable
+
+- **Keyboard (SC 2.1.1):** all functionality **MUST** be operable without a mouse. Where the function depends on the path of movement rather than only its endpoints, document why the WCAG exception applies and provide a practical alternative when possible. Avoid purely pointer-based listeners without keyboard event equivalents (`onKeyDown`).
+- **Focus (SC 2.4.7, 2.4.11):** focus **MUST** be visible, never entirely obscured by author content (e.g., sticky headers/footers), persistent, and never suppressed via CSS (`outline: none` without fallback is forbidden).
+- **SPA routing:** after client-side routing changes, focus **MUST** be managed and properly reset (e.g., sending focus to the top or an `h1`). Avoid lost focus on the screen.
+- **Targets (SC 2.5.8):** interactive elements MUST have a minimum size of **24×24 CSS pixels** — the WCAG 2.2 AA floor — except when an equivalent larger target exists, sufficient spacing prevents accidental activation, or the target sits inline in text.
+  **House Rule†:** design to **44×44px** (48×48 under Shield), the ergonomic floor shared by Apple HIG and Material Design. Under Shield, 44×44 is normative (SC 2.5.5 AAA).
+- **Dragging (SC 2.5.7, AA):** all functionality operated by dragging MUST have a simple pointer alternative that does not require dragging, unless dragging is essential or the behavior is provided by the user agent and has not been modified by the author. The alternative cannot rely only on a path-based gesture.
+- **Motion (SC 2.3.3 AAA — enforced as a House Rule† at every profile):** on the web, **MUST** respect `@media (prefers-reduced-motion)`; on native platforms, honor the equivalent system setting or provide a control to reduce non-essential interaction-triggered motion. Avoid heavy state animations during crucial transitions when that preference is active.
+
+### Understandable
+
+- **Labels (SC 1.3.1, 3.3.2):** forms **MUST** have explicit labels connected via `id`/`for`, or via tag wrapping. Avoid reinventions that break native browser events.
+- **Predictability:** navigation behavior **MUST** be consistent and interactions must not cause unannounced sudden structural changes.
+- **Consistent help (SC 3.2.6, A):** if a help mechanism — human contact, self-help, or automated contact — is repeated on multiple pages within a set, it MUST occur in the same order relative to the other content, unless the user initiated a change. The criterion does not require providing help.
+- **Redundant entry (SC 3.3.7, A):** information previously entered by or provided to the user in the same process and required again MUST be auto-populated or available for selection, unless re-entry is essential, necessary for content security, or the information is no longer valid.
+- **Accessible authentication — minimum (SC 3.3.8, AA):** do not require a cognitive function test to complete any authentication step without an alternative that does not use one or a mechanism that helps complete it. Supporting password managers and paste reduces memory and transcription burdens; treat only object recognition or user-provided non-text personal content as the listed exceptions.
+- **Dynamic feedback (SC 4.1.3):** place the announcement region in the DOM before updating its message. Use `role="status"` or `aria-live="polite"` for non-urgent information and reserve `role="alert"` for urgent errors; test announcements in supported browser and assistive-technology combinations.
+
+### Robust
+
+- **Semantic HTML:** **MUST** prefer native (HTML5) elements over custom ones.
+- **Interoperability:** the code **MUST** be compatible with current assistive technologies (ISO 9241-171).
+
+## 4. Visual directives (strict UI criteria)
+
+These directives combine WCAG requirements where identified and this guide's ergonomic recommendations. They support implementation but do not assure certification or legal compliance.
+
+- **Focus indicator (SC 2.4.13, AAA):** when this criterion is applied, the visible indicator area MUST be at least equivalent to a 2 CSS pixel thick perimeter of the unfocused component or sub-component and have at least 3:1 contrast between the same pixels in focused and unfocused states. Applicable non-text contrast (SC 1.4.11) remains required. A solid 2px outline is a simple way to meet the area requirement, not the only one. (The AA floor is focus visible — SC 2.4.7 — and not entirely obscured by author content — SC 2.4.11.)
+- **Typography (House Rule† — WCAG defines no minimum font size at any level):** text **MUST NOT** be smaller than the minimum font size of the active compliance profile (Section 0.1); 12px under the default Standard (AA).
+  - *Density exception:* in complex dashboards or secondary metadata (badges), **min 10px** is allowed, provided the contrast is raised to **7:1** as mitigation — a trade-off defined by this standard's policy, not by WCAG — and the relaxation is documented in `EXCEPTIONS.md`.
+- **Target spacing and hit area:** see *Section 3 — Targets* for the minimum size rule and exceptions. In dense UIs (e.g., tables), if the visual size is smaller than 44px, the **hit area** (invisible clickable area) **MUST** be expanded via CSS/padding. Adjacent targets **SHOULD** have 8px of spacing.
+
+## 5. Complex component protocol
+
+When identifying an unmapped or highly complex component (e.g., charts, dynamic grids):
+
+1. **Identify:** look for a similar pattern in the [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/).
+2. **Validate:** request human validation with a screen reader — the AI **MUST NOT** claim this test was performed, nor fabricate its results.
+3. **Document:** document the expected behavior (keyboard and announcements).
+4. **Scale:** record the resolved pattern in `A11Y-DECISIONS.md` so future components reuse it instead of re-deriving it.
+
+## 6. Anti-patterns (Do NOT do this)
+
+- **Actions that are buttons:** use `<button>` for actions unless a documented technical impossibility prevents it. In that case, implement the complete APG button pattern: accessible role and name, appropriate `disabled` state, `aria-pressed` for a toggle when applicable, Enter and Space activation, focus management after activation, and manual assistive-technology testing in supported combinations.
+- **Leaked focus traps:** **MUST NOT** create modals without managing focus. When a modal is open:
+  - focus MUST move into the modal;
+  - focus MUST be trapped within the modal;
+  - focus MUST return to the triggering element when closed;
+  - background content MUST NOT be interactive or reachable via keyboard.
+- **Placeholder labels:** **MUST NOT** use `placeholder` as the sole form of label. Crucial instructions (like date formats) **MUST** be visible outside the field to prevent disappearance during filling.
+- **ARIA soup:** **MUST NOT** add ARIA where native HTML already provides the semantics — no ARIA is better than bad ARIA. Forbidden by default: redundant roles (`role="button"` on a `<button>`), `aria-label` duplicating visible text (harmless today, but it drifts into an SC 2.5.3 failure when the text changes), and static ARIA states that are never updated (hardcoded `aria-expanded` — an SC 4.1.2 failure). ARIA is the fallback for gaps in native semantics ([First Rule of ARIA Use](https://www.w3.org/TR/using-aria/#rule1)), not a seasoning. The number of ARIA attributes is not evidence of accessibility; validate behavior, semantics, and assistive-technology support.
+- **Decoration without an accessible role:** **MUST NOT** add `aria-label` to purely decorative content without an accessible role. Expose an accessible name only for a control, informative image, or other semantics that genuinely need to be announced.
+- **Reinventing the complex wheel:** if you need complex components (autocomplete selects, treeviews, datepickers), it is strongly recommended to use robust and accessible libraries (e.g., Headless UI) rather than building proprietary logic from scratch.
+
+## 7. Verification workflow (Definition of Done)
+
+- [ ] **Technical check:** run the project's already configured static accessibility checks and engines such as `Axe` where applicable (see [`test-code-eng.md`](./test-code-eng.md) for tool selection). Do not install a tool solely to satisfy this item; record a required unavailable check as blocked.
+- [ ] **Tab order:** `Tab` key path manually validated (ensures absence of frontend dead-ends).
+- [ ] **Focus (SC 2.4.13, AAA when applicable):** measure the area equivalent to a 2 CSS pixel perimeter and 3:1 contrast between the same pixels in focused and unfocused states; also verify applicable non-text contrast.
+- [ ] **Dragging (SC 2.5.7, AA):** test every drag operation with a simple pointer alternative that does not require dragging; document the essentiality or user-agent exception, if any.
+- [ ] **Consistent help (SC 3.2.6, A):** compare pages in the same set and confirm repeated help mechanisms retain the same relative order, unless the user initiated a change.
+- [ ] **Redundant entry (SC 3.3.7, A):** run multi-step processes and confirm auto-population or selection of previously provided information, or record the applicable exception.
+- [ ] **Authentication (SC 3.3.8, AA):** test the whole flow, including MFA, without requiring unassisted memorization, solving, or transcription; confirm password-manager and paste support when they are the chosen mechanism.
+- [ ] **User flow and announcements:** manually test dynamic interactions without a mouse. Confirm DOM-present regions announce non-urgent messages through `role="status"` or `aria-live="polite"`, reserve `role="alert"` for urgent errors, and work in supported browser and assistive-technology combinations.
+- [ ] **Zoom and reflow:** text resizes up to 200% without loss of content or function (SC 1.4.4); content reflows at 320 CSS px width — equivalent to 400% zoom on a 1280px viewport — without two-dimensional scrolling (SC 1.4.10). Preserve flexibility using relative units (rem/em).
+- [ ] **Color and perception:** no functional loss when color is unavailable; confirm the additional channel appropriate to the meaning without requiring universal visual redundancy.
+- [ ] **Exceptions audit:** `EXCEPTIONS.md` reviewed — every active entry has a risk owner, approver, tracking issue, and expiry; no expired entries left unaddressed.
+
+---
+
+## References
+
+- Original project: https://github.com/fecarrico/A11Y.md (MIT license — Felipe A. Carriço)
+- WAI-ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/
+- WAI: Understanding SC 2.4.13 Focus Appearance: https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
+- WAI: Understanding SC 2.5.7 Dragging Movements: https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html
+- WAI: Understanding SC 3.2.6 Consistent Help: https://www.w3.org/WAI/WCAG22/Understanding/consistent-help.html
+- WAI: Understanding SC 3.3.7 Redundant Entry: https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html
+- WAI: Understanding SC 3.3.8 Accessible Authentication (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html
+- WAI: ARIA22 technique for `role="status"`: https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA22.html
+- WAI: ARIA19 technique for `role="alert"`: https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA19.html
+- eBay MIND Patterns: https://ebay.github.io/mindpatterns/
+- Deque Axe Core: https://github.com/dequelabs/axe-core
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- Optional templates from the original project: accessibility report (`REPORT.md`), exceptions log (`EXCEPTIONS.md`), and decisions log (`A11Y-DECISIONS.md`) — available under `docs/*/templates/` in the original repository.