diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml index a3ac3a7..c7f4c27 100644 --- a/.github/workflows/ecs.yml +++ b/.github/workflows/ecs.yml @@ -17,6 +17,6 @@ permissions: jobs: easy-coding-standard: - uses: php-forge/actions/.github/workflows/ecs.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/ecs.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 with: command-options: check src --config src/ecs-83.php --ansi diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index 165fd2f..1fa7abc 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -10,7 +10,7 @@ permissions: jobs: quality: - uses: php-forge/actions/.github/workflows/quality.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/quality.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 permissions: contents: read with: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 0000000..0640a44 --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,23 @@ +--- +on: + branch_protection_rule: + push: + branches: + - main + schedule: + - cron: "30 1 * * 6" + +name: scorecard + +permissions: + contents: read + +jobs: + scorecard: + uses: php-forge/actions/.github/workflows/scorecard.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 + permissions: + contents: read # Required to check out the repository. + id-token: write # Required to sign published results with the GitHub OIDC token. + security-events: write # Required to upload SARIF results to code scanning. + with: + publish-results: true diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index b3b632c..29b8119 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -10,7 +10,7 @@ permissions: jobs: security: - uses: php-forge/actions/.github/workflows/security.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0 + uses: php-forge/actions/.github/workflows/security.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2 permissions: contents: read with: diff --git a/CHANGELOG.md b/CHANGELOG.md index ccb662a..64a5c5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## 0.3.5 Under development - chore: standardize package guidance, skill discovery, configuration checks and security reporting. +- chore: align AI assistance guidance and add OpenSSF Scorecard publishing and its dynamic badge. ## 0.3.4 September 07, 2026 diff --git a/README.md b/README.md index 3441429..0ee82a2 100644 --- a/README.md +++ b/README.md @@ -187,15 +187,17 @@ Follow the same convention used across PHP Forge repositories: } ``` -## Testing +## AI assistance -Run `composer tests` to check that each versioned ECS and Rector configuration detects a sample transformation -without modifying the input. Development dependencies require PHP 8.3 or later; the package runtime supports PHP 8.1. +AI agents can use the [documentation index](https://yii2-framework.github.io/docs/llms.txt) to discover ecosystem pages +and fetch a page's Markdown version by appending `index.md` to its URL. The local +[AI assistance guide](docs/agents.md) covers skill installation, client setup and verification. -## AI assistance +- [`php-forge-coding-standard` skill](skills/php-forge-coding-standard/SKILL.md): ECS and Rector configuration. -Use the [php-forge-coding-standard skill](skills/php-forge-coding-standard/SKILL.md) and the [AI assistance guide](docs/agents.md) for -package-specific setup, invocation examples and verification. +Match guidance to the installed package revision. If hosted documentation is unavailable or does not match, use this +README, the [skill source](skills/php-forge-coding-standard/SKILL.md), the source configuration and the +[changelog](CHANGELOG.md). ## Package information @@ -206,9 +208,19 @@ package-specific setup, invocation examples and verification. ## Project status [![Quality](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/quality.yml?style=for-the-badge&label=Quality&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/quality.yml) -[![Zizmor](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/security.yml?style=for-the-badge&label=Zizmor&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/security.yml) [![StyleCI](https://img.shields.io/badge/StyleCI-Passing-44CC11.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.styleci.io/repos/1141292628?branch=main) +## Security + +[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/php-forge/coding-standard/badge?style=for-the-badge)](https://scorecard.dev/viewer/?uri=github.com/php-forge/coding-standard) +[![Zizmor](https://img.shields.io/github/actions/workflow/status/php-forge/coding-standard/security.yml?style=for-the-badge&label=Zizmor&logo=github)](https://github.com/php-forge/coding-standard/actions/workflows/security.yml) + +## Built with AI + +[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-D97757.svg?style=for-the-badge&logo=claude&logoColor=white)](https://claude.com/claude-code) +[![Built with Codex](https://img.shields.io/badge/Built%20with-Codex-10A37F.svg?style=for-the-badge&logo=openaigym&logoColor=white)](https://openai.com/codex) +[![Reviewed by CodeRabbit](https://img.shields.io/badge/Reviewed%20by-CodeRabbit-FF570A.svg?style=for-the-badge&logo=coderabbit&logoColor=white)](https://www.coderabbit.ai) + ## Our social networks [![Follow on X](https://img.shields.io/badge/-Follow%20on%20X-1DA1F2.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000)](https://x.com/Terabytesoftw) diff --git a/docs/agents.md b/docs/agents.md index e778020..36c1ffa 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -1,55 +1,74 @@ # AI assistance -Use the package-owned [php-forge-coding-standard](../skills/php-forge-coding-standard/SKILL.md) skill for selecting PHP Forge ECS and Rector configurations for a supported PHP target. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source. +The package owns [php-forge-coding-standard](../skills/php-forge-coding-standard/SKILL.md), a skill for selecting and +verifying shared ECS and Rector configurations against a consumer's minimum PHP version. ## Install in an application -Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does -not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust -`php-forge/coding-standard` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by -copying an example. With verified auto-sync enabled, installation/update can synchronize the bundle; otherwise use -`composer skills:update` and inspect `composer skills:show`. Composer exit zero is not proof of client activation. +### Automatic Composer installation -An optional pinned installer can use a local checkout or an installed package that contains the bundle: +Install `php-forge/coding-standard` as described in the [README](../README.md#installation). Complete the +[one-time application setup](https://yii2-framework.github.io/docs/project/ai-agents/#composer-installation) for +`llm/skills`, enable `auto-sync` in `skills.json`, and explicitly trust `php-forge/coding-standard` in +`dependencies.composer.trusted`. The installed package must contain the skill bundle declared by `extra.skills.source`. + +```bash +composer install +composer skills:show +``` + +With auto-sync disabled, run `composer skills:update` after installing or updating dependencies. Installing this package +alone does not register its skill at the application root. Check the synchronizer's output; Composer success alone does +not prove synchronization or activation. + +### Optional npx installation + +From the application root, list and install from a checkout containing the skill: ```bash npx skills@1.7.2 add /absolute/path/to/coding-standard --list -npx skills@1.7.2 add /absolute/path/to/coding-standard --skill php-forge-coding-standard --agent claude-code codex opencode +npx skills@1.7.2 add /absolute/path/to/coding-standard \ + --skill php-forge-coding-standard --agent claude-code codex opencode ``` -Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there. -Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation. +An installed `./vendor/php-forge/coding-standard` may be used when that revision contains the bundle. Inspect a remote +source before assuming it is published. Keep project scope and refresh copied skills after upgrades. -## Discover and invoke +## Native discovery and activation -Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-coding-standard/` and supports -`$php-forge-coding-standard` or its skill picker. Claude Code uses `.claude/skills/php-forge-coding-standard/` and `/php-forge-coding-standard`. For OpenCode, verify the -installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another. +| Client | Project directory | Explicit invocation | +| ----------- | ------------------------------------------- | ------------------------------------------------- | +| Codex | `.agents/skills/php-forge-coding-standard/` | `$php-forge-coding-standard` or the skill picker | +| Claude Code | `.claude/skills/php-forge-coding-standard/` | `/php-forge-coding-standard` | +| OpenCode | `.agents/skills/php-forge-coding-standard/` | Request the skill through the client's skill tool | + +The checkout links both discovery paths to the canonical directory. Open a fresh session at the application root and +check the available skills. Source listing, native discovery, activation and successful task behavior are separate +checks; manually reading the skill or supplying its body does not prove native activation. ## Example prompts -Explicit Codex invocation: +### Explicit invocation ```text $php-forge-coding-standard -Prepare ECS and Rector wrappers for a PHP 8.1 consumer using this package. Preserve its src/tests paths and demonstrate dry-run commands; do not upgrade syntax to the host PHP version. +Prepare ECS and Rector wrappers for a PHP 8.1 consumer using the installed package. Preserve src and tests paths. +Show non-mutating commands and check that the running PHP version does not change the target. Do not install +dependencies. ``` -Natural selection: +### Natural selection ```text -My project supports PHP 8.1 but runs tools on PHP 8.5. Configure its ECS and Rector wrappers using php-forge/coding-standard, preserve src and tests paths, and show non-mutating checks. +My project supports PHP 8.1 but runs tools on PHP 8.5. Configure ECS and Rector using the installed +php-forge/coding-standard package, preserve src and tests paths, and show non-mutating checks. ``` -Record whether the client loads this skill rather than a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the -repository or loading package skills. - -## Verify the result +### Verify the outcome -Capture the native load/tool evidence and selected source path, then execute the generated task checks against the -installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect -generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks -and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying -its body in a prompt does not prove native activation or functional execution. +Inspect the installed revision and the selected entrypoints. Confirm the ECS builder and Rector closure are used in the +correct wrappers, and run the proposed commands against disposable fixtures. Cover an unsupported target and check +that dry runs do not modify inputs. Capture native load evidence and the selected source path separately from executable +results. As a negative selection control, ask an unrelated question in a fresh session without loading package skills. [Back to README](../README.md) diff --git a/skills/php-forge-coding-standard/SKILL.md b/skills/php-forge-coding-standard/SKILL.md index 197975e..590405c 100644 --- a/skills/php-forge-coding-standard/SKILL.md +++ b/skills/php-forge-coding-standard/SKILL.md @@ -1,6 +1,6 @@ --- name: php-forge-coding-standard -description: Use when selecting PHP Forge ECS and Rector configurations for a supported PHP target. +description: Configure php-forge/coding-standard in a PHP project by selecting its ECS and Rector entrypoints for the project's minimum PHP version, writing or reviewing the root wrappers and verifying them with non-mutating runs. Use for this package rather than general ECS or Rector rule questions. license: BSD-3-Clause --- @@ -16,9 +16,15 @@ unverified current documentation. Installing this skill does not install depende ## Package contracts Select `src/ecs-81.php` through `ecs-84.php` and the corresponding Rector configuration from the consumer's minimum -supported PHP version, not the interpreter currently running. For other minimum versions, inspect the available sets and explain that no matching wrapper is provided. Plain -`ecs.php` and `rector.php` do not select a migration level. Inspect actual configuration files: an ECS entrypoint returns a builder; the Rector configuration returns a -closure that receives `RectorConfig`. Do not assume interchangeable wrapper shapes. +supported PHP version, not the interpreter currently running. For other minimum versions, inspect the available sets +and explain that no matching wrapper is provided. Plain `ecs.php` and `rector.php` do not select a migration level. +`ecs-83.php` applies the PHP 8.2 rule set because the package has no 8.3-specific ECS rules. Inspect actual +configuration files: an ECS entrypoint returns a builder; the Rector configuration returns a closure that receives +`RectorConfig`. Do not assume interchangeable wrapper shapes. + +The package can also scaffold the root `ecs.php` and `rector.php` wrappers through its `scaffold.json` in `preserve` +mode, which never overwrites an existing file. Check for existing root wrappers and the project's scaffold +configuration before writing one, and edit the existing wrapper instead of replacing it. Preserve consumer paths and justified skips. Run non-mutating checks first; ECS/Rector fix commands change files. Do not raise the language target merely to clear a finding. Verify installed ECS/Rector compatibility and the selected