# 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 |