arey-pi 0.1.0

package/rules/core/definition-of-done.md

@@ -0,0 +1,67 @@
+# Definition of Done
+
+## Core Rule
+
+A change is done only when specs, tests, and code are aligned.
+
+Completion is not based only on code compiling or tests passing. The durable project knowledge must also be correct.
+
+## Required Conditions
+
+A change is complete when:
+
+- relevant Gherkin specs exist or are explicitly confirmed unaffected;
+- production behaviour is covered by meaningful tests;
+- test quality has been assessed with mutation testing, coverage, or explicit review appropriate to risk;
+- TDD was followed for production behaviour;
+- bug fixes include regression tests;
+- tests pass, or any inability to run them is clearly documented;
+- weak, shallow, or unvalidated generated tests are not accepted as sufficient evidence;
+- architecture and code quality meet the senior engineering standard defined by Arey Pi;
+- formatting, linting/static analysis, type checking where applicable, and relevant dynamic analysis have passed or are explicitly blocked with evidence;
+- if the project lacks required quality tooling, tooling selection/configuration has been discussed with the user and captured as follow-up or implementation work;
+- specs, tests, and code agree;
+- architecture docs or high-quality ADRs are updated when durable decisions changed;
+- DBML database specs exist and are precisely synchronised when the project has a database and the change touches schema, migrations, ORM models, or persistence contracts;
+- glossary is updated when domain language changed;
+- code changes are scoped and minimal for the intended behaviour;
+- project-facing prose follows the configured language style, UK English by default;
+- specs use semantic line breaks, and touched documentation preserves or improves semantic line breaks;
+- residual risks are reported;
+- incremental Conventional Commits are created when work spans meaningful steps.
+
+## Not Done
+
+A change is not done if:
+
+- behaviour changed but Gherkin was not updated or justified unaffected;
+- tests were skipped silently;
+- production code was written without TDD evidence;
+- failing tests remain unresolved without explicit blocker status;
+- code contradicts canonical specs;
+- database schema, migrations, ORM models, or persistence code drift from canonical DBML;
+- implementation is correct but architecturally weak, brittle, overcomplicated, or low quality;
+- formatter, linter/static analyser, type checker, or required dynamic analysis fails without explicit blocker status;
+- the project lacks quality tooling and the gap has not been surfaced to the user;
+- significant technical decisions exist only in chat, implementation comments, or low-value ADRs that do not explain context, options, tradeoffs, and consequences;
+- project-facing prose mixes language styles without reason;
+- specs or touched docs ignore semantic line break conventions;
+- unrelated cleanup is mixed into the change without approval.
+
+## Completion Report
+
+Agents should close with:
+
+```txt
+Done summary:
+- Behaviour/spec impact:
+- Tests/TDD:
+- Validation:
+- Quality tooling:
+- Spec sync:
+- Architecture/code quality:
+- Architecture/ADR/glossary:
+- Database/DBML:
+- Commits:
+- Residual risks:
+```

package/rules/core/principles.md

@@ -0,0 +1,63 @@
+# Framework Principles
+
+## Purpose
+
+Arey Pi defines a software delivery model for projects that must remain understandable, testable, and rebuildable over time.
+
+Its central premise is:
+
+> Specs are durable. Tests are executable truth. Code is disposable.
+
+Arey Pi optimises for preserving intent outside the current implementation so that code can be refactored, replaced, or fully rewritten without losing product or domain knowledge.
+
+Rebuildability never lowers the quality bar. Arey Pi expects architecture and code to be designed and written at an exceptional senior engineering standard.
+
+## Core Model
+
+A project using Arey Pi is governed by three synchronised layers:
+
+1. **Canonical specs** define intended behaviour and durable project knowledge.
+2. **Tests** execute and verify the intended behaviour.
+3. **Code** implements the behaviour and may be replaced.
+
+The implementation is not the primary memory of the project. If important behaviour, constraints, or decisions only exist in code, the project is not fully captured.
+
+## Durable Knowledge
+
+Durable project knowledge belongs in:
+
+- Gherkin feature specs;
+- automated tests;
+- architecture documents;
+- Architecture Decision Records;
+- domain glossary entries;
+- explicit project rules and constraints.
+
+Production code may contain useful local explanations, but it must not be the only place where product behaviour, business rules, architectural decisions, or domain vocabulary are preserved.
+
+## Development Guarantees
+
+Every completed change must preserve these guarantees:
+
+1. **Canonical behaviour is represented in specs.**
+2. **Production behaviour is covered by meaningful tests.**
+3. **TDD is followed for production behaviour.**
+4. **Architecture and code meet a high senior engineering standard.**
+5. **Specs, tests, and code are synchronised before completion.**
+6. **Durable decisions are persisted outside implementation code.**
+7. **The resulting system remains rebuildable from durable knowledge.**
+
+## Work Modes
+
+Arey Pi supports two work modes:
+
+- **Spec-Driven Mode** for non-trivial, ambiguous, product, domain, API, or architectural work.
+- **Direct Change Mode** for small, local, obvious, or mechanical changes.
+
+Direct Change Mode is a lighter path, not an escape hatch. It still requires TDD where production behaviour is involved and always requires final spec synchronisation.
+
+## Agent Bias
+
+Agents should prefer the lightest workflow that preserves the guarantees.
+
+Do not add ceremony for simple tasks, but do not close work with missing tests, stale specs, undocumented decisions, or unresolved drift.

package/rules/engineering/engineering-quality.md

@@ -0,0 +1,285 @@
+# Engineering Quality
+
+## Purpose
+
+Engineering quality is the standard that keeps Arey Pi from becoming a documentation and test exercise around mediocre software.
+
+Specs, TDD, test quality, DBML, ADRs, quality tooling, and rebuildability all exist to support excellent engineering. They do not replace the need for excellent architecture and code.
+
+Arey Pi's expectation is simple:
+
+> Build as the most senior, careful, pragmatic software engineer on the team would build.
+
+## Core Rule
+
+Production code must be correct, well-tested, well-designed, maintainable, and consistent with the project's durable knowledge.
+
+Rebuildability never lowers the quality bar. Code may be replaceable, but the current implementation must still be excellent for its context, risk, and importance.
+
+Agents must not treat passing tests, generated code, or future rewriteability as excuses for weak design.
+
+## Priority Order
+
+When implementation tradeoffs arise, optimise in this order:
+
+1. Correct behaviour according to canonical specs.
+2. Meaningful tests that protect the behaviour.
+3. Excellent architecture and code quality.
+4. Precise synchronisation with durable knowledge.
+5. Rebuildability from specs, tests, ADRs, DBML, and architecture docs.
+6. Delivery speed.
+
+Speed matters only when it does not compromise correctness, test quality, architecture, maintainability, security, operability, or validation tooling.
+
+## Universal Design Standard
+
+The following principles are not team style preferences. They are baseline expectations for well-built software.
+
+Agents should apply them pragmatically, not dogmatically. A deliberate exception is acceptable only when the tradeoff is explicit and, if durable, documented in an ADR or architecture note.
+
+## Simplicity
+
+Prefer the simplest robust design that satisfies the known requirements.
+
+Good simplicity removes accidental complexity without hiding essential domain complexity.
+
+Agents should avoid:
+
+- speculative abstractions;
+- unnecessary layers;
+- cleverness that obscures intent;
+- generic frameworks for one concrete use case;
+- premature optimisation;
+- broad rewrites when a focused change is safer.
+
+## Cohesion and Coupling
+
+Code should have high cohesion and low unnecessary coupling.
+
+Responsibilities should be grouped by reason to change. Dependencies should be explicit, directional, and justified.
+
+Agents should avoid hidden coupling through global state, shared mutable data, implicit environment assumptions, temporal ordering, or undocumented side effects.
+
+## SOLID as Engineering Heuristics
+
+Use SOLID as practical design heuristics, not as ceremony.
+
+- **Single Responsibility:** modules should have a clear reason to change.
+- **Open/Closed:** design extension points where variation is real, not imagined.
+- **Liskov Substitution:** implementations must honour the contracts they claim to satisfy.
+- **Interface Segregation:** interfaces should be focused and not force irrelevant dependencies.
+- **Dependency Inversion:** depend on stable abstractions when doing so reduces real coupling and improves testability.
+
+Applying SOLID should make the system clearer. If it makes the design more abstract, indirect, or brittle without a real benefit, it is being misused.
+
+## Clean Boundaries
+
+Boundaries should make the system easier to understand, test, and change.
+
+Where applicable:
+
+- domain logic should not depend unnecessarily on infrastructure;
+- I/O, frameworks, persistence, and external services should sit at the edges;
+- core behaviour should be testable without heavy runtime setup;
+- adapters should be replaceable;
+- dependencies should point towards stable policy and domain concepts, not incidental mechanisms.
+
+Clean architecture is not mandatory layering. It is disciplined dependency direction and clear separation of responsibilities.
+
+## Domain Modelling
+
+Important domain concepts should be named and represented explicitly.
+
+Agents should prefer code that:
+
+- uses the language of the domain;
+- makes invariants visible;
+- makes invalid states hard to represent where the language allows it;
+- keeps business rules close to the concepts they govern;
+- avoids scattering domain rules across unrelated technical plumbing.
+
+If durable domain knowledge is discovered while coding, it should be reflected in Gherkin, glossary, tests, or architecture docs as appropriate.
+
+## Encapsulation and Information Hiding
+
+Implementation details should be hidden behind stable, meaningful interfaces.
+
+Encapsulation should protect invariants and reduce the cost of change. It should not be used to obscure behaviour, hide poor naming, or create unnecessary indirection.
+
+## Explicit Contracts
+
+Inputs, outputs, errors, side effects, and invariants should be explicit.
+
+Use types, schemas, validation, assertions, preconditions, postconditions, or tests as appropriate for the language and risk.
+
+Agents should avoid APIs where callers must guess:
+
+- what values are valid;
+- what errors can occur;
+- whether data is mutated;
+- whether operations are idempotent;
+- what external effects happen.
+
+## Error Handling
+
+Error handling is part of design quality.
+
+Good error handling:
+
+- distinguishes expected failures from programming errors;
+- preserves useful diagnostic context;
+- avoids swallowing errors silently;
+- avoids leaking secrets;
+- provides actionable messages where user-facing;
+- keeps recovery paths explicit;
+- is covered by tests for important failure modes.
+
+## Security and Privacy
+
+Security and privacy are default engineering responsibilities.
+
+Agents should consider:
+
+- least privilege;
+- input validation;
+- output encoding where relevant;
+- authentication and authorisation boundaries;
+- secret handling;
+- safe logging;
+- data minimisation;
+- retention and deletion rules;
+- dependency and supply-chain risk;
+- tenant or user data isolation.
+
+Security-sensitive tradeoffs must not be hidden in implementation details.
+
+## Operability
+
+Production-quality systems should be diagnosable and operable.
+
+Where relevant, design should include:
+
+- useful logs;
+- metrics;
+- traces;
+- health checks;
+- clear failure modes;
+- migration and rollback considerations;
+- performance characteristics that can be reasoned about.
+
+Do not add observability noise blindly. Add the signals needed to understand and operate the system.
+
+## Performance Awareness
+
+Avoid premature micro-optimisation, but do not ignore obvious performance risks.
+
+Agents should consider algorithmic complexity, N+1 queries, unbounded memory growth, excessive network calls, unnecessary serial work, lock contention, and expensive operations in hot paths.
+
+Performance decisions that shape architecture or user-visible guarantees should be persisted in architecture docs or ADRs.
+
+## Code Quality
+
+Production code should be:
+
+- consistently formatted by project tooling;
+- free of lint/static-analysis violations;
+- clear and readable;
+- minimal but complete;
+- appropriately typed where the language supports it;
+- explicit about errors and edge cases;
+- named with precision;
+- cohesive;
+- locally understandable;
+- consistent with surrounding patterns;
+- free of unrelated cleanup;
+- structured around domain behaviour rather than incidental mechanics.
+
+Good code makes intended behaviour obvious and incorrect changes harder.
+
+## Refactoring Discipline
+
+TDD is not only Red → Green. It includes Refactor.
+
+After tests are green, agents must ask whether the implementation is clean enough to accept.
+
+Refactoring should:
+
+- preserve behaviour;
+- keep tests green;
+- improve names, boundaries, cohesion, duplication, or clarity;
+- stay within scope;
+- avoid mixing unrelated cleanup with feature work;
+- be committed separately when it is a meaningful unit of work.
+
+If the green implementation is correct but low quality, the work is not done.
+
+## Generated and Agent-Written Code
+
+Generated code and agent-written code require review.
+
+Agents must not accept code simply because it compiles or passes tests. They must check whether it is understandable, maintainable, scoped, secure, and architecturally appropriate.
+
+Brittle generated code, shallow abstractions, duplicated implementation logic, and hard-coded paths to satisfy tests are engineering quality failures.
+
+## Relationship to Rebuildability
+
+Rebuildability means the system can be recreated from durable knowledge. It does not mean current code can be careless.
+
+High-quality code improves rebuildability because:
+
+- clean boundaries make partial replacement safer;
+- readable code reduces spec drift;
+- explicit contracts make tests stronger;
+- good domain modelling clarifies Gherkin and glossary entries;
+- documented tradeoffs make rewrites more reliable.
+
+## Relationship to Tooling
+
+Formatters, linters, type checkers, static analysers, dynamic analysers, coverage, and mutation testing are part of the engineering quality system.
+
+Tooling does not prove design excellence, but failing or absent tooling is a quality risk that must be addressed or explicitly reported.
+
+## Prohibited Behaviour
+
+Agents must not:
+
+- generate code that merely satisfies tests while being poorly designed;
+- hard-code behaviour just to turn tests green;
+- create broad abstractions without demonstrated need;
+- hide complexity behind vague helpers;
+- introduce global state casually;
+- weaken boundaries for convenience;
+- ignore errors, edge cases, security, or privacy;
+- mix unrelated refactors into feature work;
+- accept brittle generated code without review;
+- optimise for speed over long-term quality;
+- leave important design decisions only in chat, comments, or implementation details.
+
+## Review Expectations
+
+Engineering review should check:
+
+- correctness;
+- test strength;
+- architectural fit;
+- simplicity;
+- cohesion and coupling;
+- SOLID principle violations where relevant;
+- clean boundary and dependency direction;
+- domain modelling;
+- naming;
+- explicit contracts;
+- error handling;
+- security and privacy;
+- operability;
+- performance risks;
+- maintainability;
+- consistency with project patterns;
+- unnecessary complexity;
+- rebuildability.
+
+## Acceptance Rule
+
+A change is complete only when the implementation is not merely working, but designed and written to a high engineering standard appropriate to its risk and importance.
+
+If code is correct but architecturally weak, brittle, overcomplicated, insecure, unmaintainable, or inconsistent with durable project knowledge, it is not done.

package/rules/engineering/quality-tooling.md

@@ -0,0 +1,137 @@
+# Quality Tooling
+
+## Purpose
+
+Code quality includes style, formatting, static analysis, and dynamic validation.
+
+Arey Pi requires projects to define and use quality tooling as part of the normal validation and Definition of Done. Tooling is not optional polish; it is part of engineering quality.
+
+## Core Rule
+
+Every project must have explicit quality tooling for its language and stack.
+
+At minimum, a project should define:
+
+- a formatter;
+- a linter or static analyser;
+- type checking where the language supports it;
+- relevant dynamic analysis or runtime validation where practical;
+- commands that agents can run consistently.
+
+If this tooling is missing, agents must not silently proceed as if validation is complete. They must propose appropriate tooling and ask the user which option to install or configure.
+
+## Non-Negotiable Requirement
+
+Formatting and analysis are part of the validation phase and Definition of Done.
+
+A change is not complete until the relevant quality commands have been run successfully, or a blocker has been explicitly reported.
+
+## Tool Selection
+
+Tooling should match the project language, ecosystem, and existing conventions.
+
+Preferred examples:
+
+- **TypeScript/JavaScript:** Biome by default when no project standard exists; otherwise follow existing ESLint/Prettier/TypeScript configuration.
+- **Python:** Ruff for linting and import/style checks; Black when the project standard uses it or when formatting is not covered by Ruff configuration.
+- **Rust:** `cargo fmt`, `cargo clippy`.
+- **Go:** `gofmt`, `go vet`, relevant linters when configured.
+- **Java/Kotlin:** project formatter/linter plus build tool checks.
+
+These are defaults, not universal mandates. Existing project standards win unless they conflict with Arey Pi's quality guarantees.
+
+## Missing Tooling
+
+When a project lacks quality tooling, agents must:
+
+1. Identify the language and stack.
+2. Inspect existing package/build configuration.
+3. Propose a minimal quality toolchain.
+4. Ask the user before installing dependencies or changing project tooling.
+5. Persist the chosen commands in project scripts/docs/config.
+6. Use the tooling as part of validation going forward.
+
+Agents should not introduce major tooling churn without approval.
+
+## Validation Commands
+
+Projects should expose stable commands where possible, for example:
+
+```txt
+format
+lint
+typecheck
+test
+check
+```
+
+The exact command names can vary by ecosystem, but agents should be able to discover and run the standard validation path.
+
+A good `check` command should usually compose formatting checks, lint/static analysis, type checking, and tests.
+
+## Formatting
+
+Formatting should be automated and deterministic.
+
+Agents should not hand-format large code changes when a formatter exists. They should run the formatter or formatting check according to project convention.
+
+Formatting-only changes should be isolated from behaviour changes unless explicitly approved.
+
+## Static Analysis
+
+Static analysis should catch issues such as:
+
+- type errors;
+- unused code;
+- unreachable code;
+- unsafe patterns;
+- style violations;
+- import/order problems;
+- likely bugs;
+- security-sensitive patterns where tooling supports it.
+
+Agents must treat static analysis failures as validation failures unless explicitly classified as unrelated pre-existing issues.
+
+## Dynamic Analysis
+
+Where practical, projects should include dynamic validation appropriate to their risk profile, such as:
+
+- test suites;
+- mutation testing;
+- property-based tests;
+- runtime assertions in test environments;
+- integration checks;
+- security scanners;
+- performance checks for performance-sensitive code.
+
+Dynamic analysis should be selected based on risk, not added blindly.
+
+## Existing Failures
+
+If formatting, linting, type checking, or dynamic analysis already fails before the agent's change, the agent must:
+
+- record the baseline failure;
+- avoid making it worse;
+- fix it if within scope;
+- otherwise report it as pre-existing residual risk.
+
+Do not claim validation success when quality tooling fails.
+
+## Agent Behaviour
+
+Before changing code, agents should inspect available tooling.
+
+Before completion, agents should run relevant commands and report:
+
+- formatter/check command;
+- lint/static analysis command;
+- typecheck command where applicable;
+- test command;
+- dynamic analysis command where applicable;
+- failures, skips, and residual risks.
+
+## Acceptance Rule
+
+A code change is not done until style and analysis tooling have either passed or been explicitly blocked with evidence.
+
+If a project has no such tooling, adding or selecting it becomes part of the engineering work and must be discussed with the user.

package/rules/engineering/rebuildability.md

@@ -0,0 +1,49 @@
+# Rebuildability
+
+## Purpose
+
+Arey Pi treats production code as replaceable. A healthy project can discard and recreate implementation modules from durable knowledge.
+
+## Core Rule
+
+A module is rebuildable when another agent or developer can understand and recreate its intended behaviour from:
+
+- Gherkin specs;
+- tests;
+- architecture docs;
+- ADRs;
+- glossary;
+- project rules.
+
+The old implementation may be useful context, but it must not be required to recover intent.
+
+## Disposable Code Principle
+
+Code is valuable, but it is not the canonical memory of the system.
+
+Agents should actively move durable knowledge out of implementation-only places into specs, tests, architecture docs, ADRs, or glossary entries.
+
+## Rebuildability Signals
+
+A module may not be rebuildable when:
+
+- behaviour is only discoverable by reading implementation code;
+- tests assert mechanics but not intended behaviour;
+- Gherkin specs are missing or stale;
+- architectural constraints are implicit;
+- domain terms are undefined;
+- critical decisions exist only in comments, commit history, or chat.
+
+## Rewrites
+
+A rewrite should start from canonical specs and tests, not by copying the previous implementation.
+
+The previous code can be inspected for migration clues, edge cases, and compatibility risks, but canonical specs/tests define the target.
+
+## Agent Behaviour
+
+When working on a module, agents should ask:
+
+> Could this module be deleted and recreated from the durable project knowledge?
+
+If the answer is no, improve the specs/tests/docs when the current task touches the relevant area.

package/rules/engineering/tdd.md

@@ -0,0 +1,86 @@
+# TDD
+
+## Purpose
+
+TDD is mandatory for production behaviour.
+
+Tests are the executable truth that verifies canonical specs and makes rebuildable code possible.
+
+## Core Rule
+
+Production behaviour must be introduced or changed through:
+
+```txt
+Red → Green → Refactor
+```
+
+This applies to features, bug fixes, behaviour changes, risky refactors, API/CLI behaviour, validation, permissions, persistence, and error handling.
+
+## Red
+
+Before implementation, create, update, or identify a test that fails for the intended reason.
+
+Valid Red evidence includes:
+
+- a newly added failing test;
+- an updated failing test;
+- an existing failing test that already captures the intended behaviour;
+- a documented inability to run the test, including the exact intended command and reason.
+
+A failure caused by setup, syntax, environment, or unrelated behaviour does not count as valid Red evidence.
+
+## Green
+
+Implement the smallest scoped change that makes the relevant test pass.
+
+Green evidence should show:
+
+- the relevant test passes;
+- relevant surrounding tests pass where practical;
+- no assertions were weakened just to pass;
+- no unrelated behaviour was changed.
+
+## Refactor
+
+After Green, refactor only while tests remain green.
+
+Refactoring should improve clarity, structure, duplication, or maintainability without expanding scope or changing behaviour.
+
+## Bug Fixes
+
+Every bug fix requires a regression test.
+
+The expected flow is:
+
+```txt
+Reproduce with failing test → Fix → Passing regression test → Relevant suite green → Spec sync
+```
+
+## Pure Refactors
+
+A pure refactor may rely on existing tests if the agent can explain why coverage is sufficient.
+
+If coverage is weak and the refactor is risky, add characterization tests before changing production code.
+
+## Prohibited Practices
+
+Agents must not:
+
+- write production behaviour first and tests later;
+- weaken tests to make implementation pass;
+- delete failing tests without justification;
+- claim Red from irrelevant failures;
+- skip test execution silently;
+- expand scope beyond the spec/test intent.
+
+## Evidence
+
+Completion must report:
+
+- related Gherkin scenario if applicable;
+- Red evidence;
+- Green evidence;
+- refactor status;
+- commands run;
+- tests not run and why;
+- residual risks.