Skip to content

Clean up public repository documentation #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
josiahking merged 1 commit into from
Sep 2, 2026
Merged

Clean up public repository documentation #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 49 additions & 56 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,116 +1,111 @@
# Agent Workflow Rules
# Automation and Contribution Guide

Every coding agent must read and follow this file before auditing, planning or modifying this repository.
Every coding agent must read and follow this file as public automation guidance for this repository.

## 1. Scope discipline
This guide applies to repository work performed by contributors, automation tools and coding assistants. It keeps automated changes reviewable, evidence-based and aligned with the public EvolvePHP branch model.

- Work only on the requested phase and task.
## Scope Discipline

- Work only on the requested task.
- Do not add adjacent features because they appear useful.
- Keep commits and changes small and reviewable.
- Keep changes small and reviewable.
- Identify assumptions before implementation.
- Stop and report when a required dependency or decision is missing.

## 2. Pre-implementation audit
## Pre-Change Audit

Before code changes, every task must include:
Before modifying files, inspect the relevant files and summarize:

- Relevant-file inspection
- Current-behaviour summary
- Risks and dependencies
- Proposed files to modify
- Test plan
- Explicit non-goals
- current behavior;
- risks and dependencies;
- proposed files to modify;
- test plan;
- explicit non-goals.

## 3. Test-driven development
## Test-Driven Changes

All behavioural implementation must use:
Behavioral implementation must follow:

```text
RED -> GREEN -> REFACTOR
```

Rules:

- Write or update tests before implementation.
- Demonstrate that the test initially fails for the expected reason.
- Implement the smallest change that makes it pass.
- Refactor only after the tests pass.
- Run targeted tests and the relevant full suite.
- Never delete, weaken or bypass a valid test just to obtain a passing result.
- Documentation, configuration and architecture changes should receive automated policy or validation tests where reasonably possible.
Write or update tests before implementation, demonstrate the expected failing result, make the smallest passing change and refactor only after the tests pass. Do not delete, weaken or bypass a valid test just to obtain a passing result. Documentation, configuration and architecture changes should receive automated policy or validation tests where reasonably possible.

## 4. Legacy preservation
## Legacy Preservation

- `master` represents the EvolvePHP 1 legacy line.
- `master` is reserved for preserved EvolvePHP 1 history and explicitly approved legacy maintenance.
- `master` preserves the EvolvePHP 1 legacy line.
- EvolvePHP 1 maintenance must be clearly requested.
- An approved legacy-maintenance task must start from `master`, then continue on its own task-specific branch.
- Do not modernise EvolvePHP 1 unless a task explicitly targets legacy maintenance.
- Do not silently fix historical issues during documentation work.
- Preserve historical evidence and clearly document limitations.
- EvolvePHP 2 development must occur separately from the preserved legacy baseline.
- EvolvePHP 2 work is based on the current `2.x` branch.
- An approved legacy-maintenance task must start from `master` and continue on a task-specific branch.
- Do not modernize EvolvePHP 1 unless the task explicitly targets legacy maintenance.
- Preserve historical evidence and document limitations clearly.
- EvolvePHP 2 development is based on the current `2.x` branch.
- EvolvePHP 2 changes must never be merged into `master`.
- EvolvePHP 1 changes must not be silently mixed into `2.x`.
- EvolvePHP 1 changes must not be mixed into `2.x`.

## 5. Branch safety
## Branch Safety

- Do not work directly on `master`; direct work on `master` remains prohibited unless the task explicitly targets approved legacy maintenance, and approved legacy maintenance still requires a task-specific branch.
- Do not work directly on `master`; direct work on `master` is prohibited unless the task explicitly targets approved legacy maintenance, and even then it must continue on a task-specific branch.
- Confirm a clean working tree before editing.
- Verify the requested base branch and exact base SHA before editing.
- Agents must not infer the correct base branch from GitHub's current default branch.
- Contributors and automation tools must not infer the correct base branch from GitHub's current default branch.
- Use a task-specific branch.
- Do not push, merge, tag or open a pull request unless explicitly requested.
- Do not push, merge, tag or open a pull request unless explicitly requested; publication also requires explicit approval.
- Never rewrite shared history.
- Report unrelated pre-existing changes instead of overwriting them.

## 6. Public APIs and architecture
## Public APIs and Architecture

- Public contracts require deliberate review.
- Breaking changes require an RFC or explicit approval.
- Prefer composition over inheritance.
- Prefer dependency injection over service location.
- Prefer explicit behaviour over hidden magic.
- Prefer explicit behavior over hidden magic.
- Respect module ownership and dependency boundaries.
- Infrastructure implementations must remain replaceable through contracts.
- Core must not depend on optional outward packages.
- Production packages must not depend on Testing or DevTools.
- Package dependencies are declared through Composer only.
- Bridge remains outside Core.

## 7. Database migrations
## Database Migrations

- Do not modify an already released or applied migration.
- When a migration needs correction, create a new repair or follow-up migration.
- Migration changes require tests and rollback consideration.

## 8. Security
## Security

- Do not expose secrets, credentials, tokens or private information.
- Do not weaken validation, authorisation, CSRF, CORS or output escaping.
- Do not weaken validation, authorization, CSRF, CORS or output escaping.
- Security-sensitive changes require negative-path tests.
- Never hide a discovered security risk merely to keep the task small; document it and keep unrelated remediation out of scope.
- Document discovered security risks even when remediation is out of scope.

## 9. Dependencies
## Dependencies

- Do not add, remove or upgrade dependencies without explaining the need.
- Prefer existing standards and packages over custom implementations.
- Dependency changes require compatibility and licence review.
- Do not modernise legacy dependencies during preservation-only tasks.
- Dependency changes require compatibility and license review.
- Do not modernize legacy dependencies during preservation-only work.

## 10. Observability and performance
## Observability and Performance

- Do not make performance claims without reproducible measurements.
- Add telemetry to important framework lifecycle operations where required by the roadmap.
- Add telemetry to important framework lifecycle operations only when required by accepted design.
- Avoid logging secrets or sensitive payloads.
- Persistent-worker changes must test state reset and memory behaviour.
- Persistent-worker changes must test state reset and memory behavior.

## 11. Documentation
## Documentation

- Documentation must match implemented behaviour.
- Documentation must match implemented behavior.
- Do not claim features, compatibility, security or performance without evidence.
- Include commands that were actually executed.
- Clearly identify historical claims, maintainer-reported facts and independently verified facts.
- Keep public documentation tool-neutral and durable.

## 12. Completion evidence
## Completion Evidence

Every final agent report must include:
Every final agent report must include the same contribution evidence expected from any automated repository work:

1. Audit summary
2. Files created
Expand All @@ -122,5 +117,3 @@ Every final agent report must include:
8. Remaining risks
9. Deferred work
10. Confirmation that no out-of-scope files were changed

A statement such as "tests passed" without command and result evidence is insufficient.
23 changes: 11 additions & 12 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,11 +136,11 @@ Run deterministic/offline package release-readiness validation:
composer release:validate
```

Phase 2.10A keeps the release packages mapped explicitly in `release-packages.json`. Phase 6.4E extends that dependency-compatible map to seven packages by appending DevTools after the existing six-package order: contracts, core, module, plugin, http, testing and dev-tools. Package-local README and licence files exist so future split roots carry consumer documentation and legal text naturally. Package-local licences must remain identical to root `LICENSE.md`.
The release packages are mapped explicitly in `release-packages.json`. The dependency-compatible map contains seven packages in this order: contracts, core, module, plugin, http, testing and dev-tools. Package-local README and licence files exist so future split roots carry consumer documentation and legal text naturally. Package-local licences must remain identical to root `LICENSE.md`.

No package is being published by this command. No remote repositories are contacted, no tags/releases are created, and no split repositories are synchronized. Package Composer manifests remain authoritative for package metadata.

`release:validate` is distinct from `quality`. It is also distinct from network-dependent `supply-chain`. Package splitting is Phase 2.10B validation work, and prerelease consumer stability is validated by the Phase 2.10B consumer matrix. RFC 0003 remains authoritative for release and version policy.
`release:validate` is distinct from `quality`. It is also distinct from network-dependent `supply-chain`. Package splitting is validated by `release:split:validate`, and prerelease consumer stability is validated by the offline consumer matrix. RFC 0003 remains authoritative for release and version policy.

### Package Split Validation

Expand Down Expand Up @@ -229,7 +229,7 @@ Dependabot alerts and Dependabot security updates are GitHub settings. `.github/

## VS Code Developer Experience

VS Code is optional developer tooling, not framework runtime configuration. The repository root is the VS Code workspace; no separate `.code-workspace` file is required for this phase.
VS Code is optional developer tooling, not framework runtime configuration. The repository root is the VS Code workspace; no separate `.code-workspace` file is required.

The committed recommendations are intentionally minimal: EditorConfig for shared editor whitespace policy and Intelephense for PHP 8.4 language-analysis support. The Intelephense setting targets PHP 8.4 syntax and symbols for editor feedback, but it does not replace actual PHP 8.4+ execution.

Expand Down Expand Up @@ -338,7 +338,7 @@ packages/plugin/src
packages/testing/src
```

Package tests are excluded from Phase 2.5 Deptrac boundary analysis so test dependencies cannot weaken production rules. Physical package paths define layers, and package namespaces must match the package paths:
Package tests are excluded from Deptrac boundary analysis so test dependencies cannot weaken production rules. Physical package paths define layers, and package namespaces must match the package paths:

```text
Contracts -> packages/contracts/src/.* -> Evolve\Contracts\
Expand Down Expand Up @@ -378,7 +378,7 @@ PsrHttpMessage
PsrHttpServer
```

`PsrContainer` represents the approved PSR-11 interoperability layer used by Core and, starting in Phase 5.4, by Contracts specifically for the public `ServiceDefinitionRegistrar` service-definition factory contract. Contracts remains first-party-inward and has no first-party EvolvePHP dependency; the PSR-11 reference documents the optional resolver argument accepted by component service-definition factories and does not make Contracts a container implementation. Core remains the implementation owner for the registry, frozen resolver, execution scopes and restricted registration coordinator. `PsrHttpMessage` represents the approved `Psr\Http\Message` namespace used by Http for PSR-7 message interfaces and PSR-17 factory interfaces, including `psr/http-message` and `psr/http-factory`. `PsrHttpServer` represents the approved PSR-15 server middleware/handler interface layer used by Http.
`PsrContainer` represents the approved PSR-11 interoperability layer used by Core and by Contracts for the public `ServiceDefinitionRegistrar` service-definition factory contract. Contracts remains first-party-inward and has no first-party EvolvePHP dependency; the PSR-11 reference documents the optional resolver argument accepted by component service-definition factories and does not make Contracts a container implementation. Core remains the implementation owner for the registry, frozen resolver, execution scopes and restricted registration coordinator. `PsrHttpMessage` represents the approved `Psr\Http\Message` namespace used by Http for PSR-7 message interfaces and PSR-17 factory interfaces, including `psr/http-message` and `psr/http-factory`. `PsrHttpServer` represents the approved PSR-15 server middleware/handler interface layer used by Http.

These PSR HTTP interfaces are external interoperability standards and do not change the first-party Evolve package dependency direction. Adding `psr/http-factory` does not require a new Deptrac external namespace layer because PSR-17 factory interfaces live under `Psr\Http\Message`. Http still depends inward on Contracts and Core, while the other first-party packages do not receive direct PSR HTTP access in this foundation.

Expand Down Expand Up @@ -434,9 +434,9 @@ The root quality matrix runs PHP 8.4 and PHP 8.5. Each matrix entry validates Co
composer quality
```

The initial Phase 2.6 CI matrix has successfully executed. Root quality passes on PHP 8.4 and PHP 8.5, and the root policy job passes on PHP 8.4 for the current tooling and package foundation. This evidence applies to the current workspace, tooling and package foundation only.
The current CI matrix has successfully executed. Root quality passes on PHP 8.4 and PHP 8.5, and the root policy job passes on PHP 8.4 for the current tooling and package foundation. This evidence applies to the current workspace, tooling and package foundation only.

PHP 8.5 evidence for the current root quality pipeline is recorded by the Phase 2.6 CI matrix.
PHP 8.5 evidence for the current root quality pipeline is recorded by the CI matrix.

The EvolvePHP 2 runtime implementation is incomplete, so this is not a broader runtime-production compatibility claim.

Expand All @@ -446,17 +446,16 @@ Action dependencies are pinned by immutable full-SHA references. The reviewed re

## Compatibility Evidence

EvolvePHP 2 requires PHP 8.4 as the baseline. The Phase 2.6 CI matrix has successfully executed in GitHub Actions: the current root quality pipeline passes on PHP 8.4 and PHP 8.5, and the root policy job passes on PHP 8.4.
EvolvePHP 2 requires PHP 8.4 as the baseline. The current CI matrix has successfully executed in GitHub Actions: the current root quality pipeline passes on PHP 8.4 and PHP 8.5, and the root policy job passes on PHP 8.4.

This verifies the current workspace, tooling and package foundation only. The preserved EvolvePHP 1 runtime is excluded, and the EvolvePHP 2 runtime implementation remains incomplete.

## Deferred Work

The following work remains deferred:

- committed-ref package split validation after a reviewed Phase 4.7 commit
- package publication, tags and GitHub releases
- Runtime framework implementation beyond the completed Phase 4 HTTP package foundation
- Phase 5 module/plugin runtime work
- Runtime framework implementation beyond the completed HTTP package foundation
- full Module/Plugin runtime managers
- broader developer tooling beyond `module:new` and `plugin:new`
- Phase 6.4F broader Testing utilities beyond the command-output recorder
- broader Testing utilities beyond the command-output recorder
Loading