FINDINGS.md

@@ -0,0 +1,193 @@
+# 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 |

TODO.md

@@ -0,0 +1,48 @@
+# TODO — core-devops
+
+**Updated:** 2026-02-21 (Phase 0 assessment)
+**See:** [FINDINGS.md](FINDINGS.md) for full assessment details.
+
+---
+
+## Phase 1 — Immediate (main branch health)
+
+- [ ] Merge `dev` → `main` after review (dev is 20+ commits ahead)
+- [ ] Update `VERSION` in `scripts/install-core.sh` to auto-detect latest release (fix is on `dev`)
+- [ ] Verify `COMPOSER_EXPECTED_SIG` in `scripts/install-deps.sh` is current
+- [ ] Update `GO_VERSION` in `scripts/install-deps.sh` to 1.24.x
+
+## Phase 2 — Shell script quality
+
+- [ ] Install `shellcheck` in CI and run against all `.sh` files
+- [ ] Add BATS (Bash Automated Testing System) tests for `install-deps.sh` and `install-core.sh`
+- [ ] Fix `${var,,}` bash 4+ syntax in `install-core.sh` for macOS bash 3 compatibility (fix on `dev`)
+- [ ] Add GitHub Actions workflow to lint shell scripts on push
+
+## Phase 3 — CI/CD for this repo
+
+- [ ] Add `.github/workflows/ci.yml` to run `shellcheck` and BATS tests
+- [ ] Add `scripts/install-core.sh` smoke test in CI (build-from-source path)
+- [ ] Enable CodeQL scanning (workflow exists on `dev`)
+- [ ] Add Trivy/Gitleaks security scanning (workflows on `dev`)
+
+## Phase 4 — Documentation
+
+- [ ] Merge VitePress docs site from `dev` (`.vitepress/`, `doc/`)
+- [ ] Add architecture diagram to README
+- [ ] Document `.core/` folder spec for package maintainers
+- [ ] Add SECURITY.md (exists on `dev`)
+- [ ] Add CONTRIBUTING.md (exists on `dev`)
+
+## Phase 5 — Workspace tooling
+
+- [ ] Confirm `core` CLI v0.1.0 is released and binaries are available on GitHub
+- [ ] Add `core doctor --fix` smoke test to CI
+- [ ] Validate `repos.yaml` schema in CI (YAML lint + custom validation)
+- [ ] Add `make test` target that runs shell script tests
+
+## Deferred
+
+- [ ] TLS certificate pinning for script downloads (currently relies on system CA store)
+- [ ] Separate trust root for binary checksums (currently same origin as binaries)
+- [ ] GPG signing of `core` CLI release tags