php-devops/FINDINGS.md

Phase 0 Findings — core-devops

Date: 2026-02-21 Issue: #1 — phase 0: environment assessment + test baseline Branch: main (assessed from feat/phase-0-assessment)

---

1. Repository Classification

This is a workspace orchestrator (meta package), not a PHP package.

Attribute	Value
Type	meta (as defined in repos.yaml)
Purpose	Developer workspace bootstrap for 18 Laravel packages
Primary languages	Bash, PowerShell, YAML
PHP code at root	None
composer.json	Absent
Packages directory	packages/ — git-ignored, populated at runtime

---

2. PHP Tooling Assessment

All standard PHP tooling tasks were attempted. Results below.

2.1 git checkout dev && composer install --no-interaction

Composer could not find a composer.json file in /path/to/php-devops
To initialise a project, please create a composer.json file.

Finding: No composer.json exists at the repo root. This is expected — core-devops contains only shell scripts and YAML configuration. PHP tools are not applicable here; they belong in packages/core-php/ and other individual packages.

2.2 vendor/bin/phpunit --testdox

/bin/bash: vendor/bin/phpunit: No such file or directory

Finding: No test suite. No vendor directory. Not applicable.

2.3 vendor/bin/pint --test

/bin/bash: vendor/bin/pint: No such file or directory

Finding: No linter. Not applicable.

2.4 vendor/bin/phpstan analyse --memory-limit=512M

/bin/bash: vendor/bin/phpstan: No such file or directory

Finding: No static analysis. Not applicable.

---

3. Shell Script Assessment

Shell scripts constitute the core deliverable of this repo.

3.1 Syntax validation

bash -n scripts/install-deps.sh   → OK
bash -n scripts/install-core.sh   → OK

Finding: Both Bash scripts pass syntax validation.

3.2 shellcheck availability

shellcheck: command not found

Finding: shellcheck is not installed in this environment. Static analysis of shell scripts cannot be completed without it. See TODO section.

3.3 Identified issues

File	Issue	Severity
scripts/install-core.sh	VERSION="v0.1.0" hardcoded — stale	Medium
scripts/install-deps.sh	COMPOSER_EXPECTED_SIG — pinned hash may be stale	Medium
scripts/install-deps.sh	GO_VERSION="1.22.0" — pinned, not latest 1.24.x	Low
scripts/install-core.sh	${actual_hash,,} — bash 4+ only, fails on bash 3 (macOS)	Medium

Note: The dev branch has a commit (fix(install): use latest release instead of hardcoded version) that resolves the VERSION hardcoding and the bash 3 compatibility issue. main has not received these fixes.

---

4. Architecture Patterns

4.1 Package registry (repos.yaml)

Canonical list of 18 packages with type, dependencies, and metadata. Consumed by the core CLI for cloning and workspace management. Package types: foundation, module, product, template, meta.

4.2 .core/ folder system

Standardised workspace configuration folder:

.core/
├── workspace.yaml       # Active package, clone defaults, paths
├── plugin/
│   ├── plugin.json      # Claude Code manifest with skills + hooks
│   ├── skills/          # Context-aware guidance files
│   └── hooks/           # prefer-core.sh — informational hints
└── docs/
    └── core-folder-spec.md  # Specification for per-package .core/

Used both by this orchestrator repo and by each package. Specification lives in .core/docs/core-folder-spec.md.

4.3 core CLI (external Go binary)

Multi-repo management tool (github.com/host-uk/core). Not included in this repo. Downloaded or built via scripts/install-core.sh. Provides core health, core php test, core commit, etc. Workspace root commands delegate to active package.

4.4 Cross-platform setup scripts

Script	Platform	Function
scripts/install-deps.sh	Unix (macOS/Linux)	Installs Git, Go, PHP, Composer, Node, pnpm
scripts/install-deps.ps1	Windows	Same via Chocolatey
scripts/install-core.sh	Unix	Downloads or builds core CLI binary
scripts/install-core.ps1	Windows	Same for Windows

4.5 Security controls

Both install-core.sh and install-core.ps1 implement:

• Version pinning to prevent supply chain attacks
• SHA256 hash verification before installation
• Symlink detection to prevent directory traversal
• GPG tag signature verification (optional, skips gracefully if GPG absent)
• Secure temp directory creation (mktemp with restrictive permissions)
• Trap-based cleanup on interrupt

Known limitations (documented in scripts):

• Checksums fetched from same origin as binaries (single trust root)
• No TLS certificate pinning (relies on system CA store)

4.6 Claude Code integration

plugin.json registers three skills (workspace, switch-package, package-status) and a pre_command hook that suggests core CLI equivalents when raw git or composer commands are detected. The hook is informational only (exit 0).

---

5. Divergence: main vs dev

main is behind dev by at least 20+ commits. dev contains:

• GitHub Actions workflows (auto-label, CodeQL, free-tier scanners, AI worker)
• Issue and PR templates
• JetBrains IDE configuration
• VitePress documentation site
• CONTRIBUTING.md, SECURITY.md, TEMPLATE_SETUP.md
• docker-compose.yml, .devcontainer/
• Additional skills (go-agent.md, php-agent.md)
• TODO.md (session summary from 2026-02-01)

Finding: main should receive a merge from dev after review. Most dev content is additive (documentation, CI workflows, IDE config) and does not risk regressions.

---

6. Summary

Check	Status	Notes
composer install	N/A — no composer.json	Meta repo, not a PHP package
PHPUnit tests	N/A	Not applicable
Pint lint	N/A	Not applicable
PHPStan analysis	N/A	Not applicable
Shell syntax check	Pass	Both scripts pass bash -n
shellcheck	Not run	Not installed
Security controls	Present	SHA256, symlink detection, GPG
Stale pinned versions	Found	VERSION, GO_VERSION, COMPOSER_EXPECTED_SIG on main
dev → main merge	Pending	dev is ahead by 20+ commits