AI-native hardening: validate-configuration.sh in CI, agent-docs drift check, .claude guardrails

[Kravalg]

Description

As a maintainer of php-service-template, I want the template's AI-agent guardrails to be enforced by CI and by machine-readable agent settings, so that an agent (or contributor) who weakens quality gates or lets agent docs drift is stopped automatically instead of relying on local hooks and manual review.

Today scripts/validate-configuration.sh — the lock on quality-gate configs (phpinsights.php, psalm.xml, deptrac.yaml, infection.json5, .php-cs-fixer.dist.php) — is only invoked from the local make ci target, and no GitHub workflow runs it, so an agent that weakens gates and bypasses local hooks (e.g. CAPTAINHOOK_DISABLE) is not blocked by CI. Nothing enforces that the make command lists cited in AGENTS.md, CLAUDE.md, and .claude/skills/*/SKILL.md stay in sync with the Makefile (issue #171 synced the content once, but there is no ongoing drift check). And there is no committed .claude/settings.json allowlisting safe make targets or a PreToolUse hook blocking edits to locked config files, so agent runs hit permission friction while dangerous edits are not machine-blocked.

Affected quality attributes

This issue is part of the enterprise quality audit (report: docs/audit/enterprise-quality-audit-2026-07.md on branch claude/enterprise-quality-audit-bc8jch).

• ai-native-readiness — 4/5, anti-tamper guardrail (scripts/validate-configuration.sh) not wired into any GitHub workflow; no docs-drift check; no .claude/settings.json — target 5/5.
• sustainability — 4/5, the lock on quality configs runs only in local make ci, so CI does not actually block gate-weakening PRs — target 5/5.
• adaptability — 4/5, locked config files have no documented escape hatch for legitimate downstream adaptation — target 5/5.
• tailorability — 3/5, template resists tailoring of core policy files with no sanctioned override/opt-out path for downstream services — target 5/5.

Tasks

• Add a required PR workflow step (new .github/workflows/validate-configuration.yml or a step in an existing required workflow) that runs scripts/validate-configuration.sh, so gate-weakening changes to phpinsights.php, psalm.xml, deptrac.yaml, infection.json5, or .php-cs-fixer.dist.php fail CI even when local captainhook hooks are bypassed
• Add a CI lint (script under scripts/ plus workflow step) that extracts the make targets cited in AGENTS.md, CLAUDE.md, and .claude/skills/**/SKILL.md and fails when any cited target is missing from the Makefile, preventing agent-guide drift going forward (complements the one-time sync from Synchronize AI agent support surfaces from user-service #171)
• Commit a .claude/settings.json that pre-approves the repository's safe commands (the documented make targets and read-only docker compose exec php ... invocations) to reduce agent permission friction
• Add a PreToolUse hook in .claude/settings.json that blocks edits to the locked quality-config files (phpinsights.php, psalm.xml, deptrac.yaml, infection.json5, .php-cs-fixer.dist.php), mirroring the LOCKED_CONFIG_FILES list in scripts/validate-configuration.sh
• Document the sanctioned adaptation path for locked configs (when downstream services may legitimately diverge and how) so the guardrails do not block legitimate template instantiation
• Evaluate adding executable assets to .claude/skills/ (e.g. small verification scripts a skill can invoke directly) where documentation-only skills fall short, and implement where clearly beneficial

Acceptance Criteria

• A PR that modifies a locked quality-config file fails the new required CI check via scripts/validate-configuration.sh
• A PR that removes or renames a Makefile target cited in AGENTS.md, CLAUDE.md, or .claude/skills/**/SKILL.md without updating the docs fails the docs-drift lint
• .claude/settings.json exists with a safe-command allowlist and a hook that blocks edits to the locked quality-config files
• The sanctioned downstream-adaptation path for locked configs is documented
• No existing quality gate is lowered — thresholds may only be added or raised
• All existing quality gates still pass (make ci)
• The linked PR passes GitHub CI checks and CodeRabbit review feedback is addressed

[coderabbitai]

🔗 Related PRs

#39 - add correct badges [merged]
#57 - update Readme, fix GitHub action, move AUTORELEASE.md [merged]
#135 - Rector php [merged]
#172 - feat(#171): synchronize AI agent support baseline [merged]
#175 - feat(#174): sync README and FrankenPHP enterprise baseline [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!