200 lines
8.5 KiB
Markdown
200 lines
8.5 KiB
Markdown
# Phase 11: ProjectManager Release Readiness
|
|
|
|
## Milestone Status
|
|
|
|
- architecture freeze: complete
|
|
- interactive prototype: complete
|
|
- internal alpha desktop shell: complete
|
|
- macOS local packaging validation: complete
|
|
- signed beta build: pending signing/notarization credentials and platform-host verification
|
|
- release candidate: pending Windows and Linux package validation
|
|
- production release readiness: pending platform signing completion and final release-channel credentials
|
|
|
|
## What Is Ready
|
|
|
|
- dedicated Electron-native desktop workspace under `AgentCompany`
|
|
- explicit main / preload / renderer / shared separation
|
|
- local-first profile, secret storage, orchestration worker, IPC contracts, and desktop shell
|
|
- onboarding to first usable shell flow
|
|
- packaging configuration for macOS, Windows, and Linux
|
|
- warning-free local lint baseline across main/preload/renderer
|
|
- validation gate rerun on 2026-03-13 passed (`lint`, `typecheck`, `test:run`, `build:dir`)
|
|
- **TODO**: PR CI quality gate workflow (`.github/workflows/agent-company-pr-verify.yml`) has not been created yet
|
|
- **TODO**: Electron production fuse hardening has not been configured yet (see doc 11)
|
|
- packaging script now defaults to `--publish never` unless explicitly overridden (`AGENTCOMPANY_ELECTRON_PUBLISH` or explicit `--publish`)
|
|
|
|
## Release Ownership Boundaries
|
|
|
|
| Area | Primary owner | Backup owner | Scope boundary | Exit evidence |
|
|
| --- | --- | --- | --- | --- |
|
|
| Release gate decision | CEO / ProjectManager | Product lead | Approves go/no-go only after all gates are green; does not bypass security/platform sign-off | Signed release checklist + release tag decision |
|
|
| Signing credentials | Security Auditor | Platform Release Engineer | Manages cert issuance/rotation and secret distribution; build operators never commit secrets | Secret inventory record + cert expiry check |
|
|
| macOS signing + notarization | macOS Release Engineer | Security Auditor | Runs signed build on macOS host and validates notarization ticket | `spctl`, `codesign`, `stapler` evidence |
|
|
| Windows signing + installer trust | Windows Release Engineer | Security Auditor | Runs NSIS build on Windows host and validates Authenticode chain | `Get-AuthenticodeSignature` evidence |
|
|
| Linux package validation | Linux Release Engineer | QA lead | Builds and smoke-tests AppImage on Linux host; verifies runtime dependencies | AppImage launch and smoke checklist |
|
|
| Updater endpoint trust | Security Auditor | SRE / Infra | Owns TLS/domain trust policy and update channel integrity checks | `latest*.yml` metadata + artifact hash verification |
|
|
| Cross-platform functional smoke | QA lead | Platform engineers | Verifies startup/onboarding/task-run/approval flows on each target OS | Smoke run logs + screenshots |
|
|
|
|
## Release Checklist (Production Candidate)
|
|
|
|
- [ ] `pnpm install --frozen-lockfile` completed on release host
|
|
- [ ] `pnpm lint` passed
|
|
- [ ] `pnpm typecheck` passed
|
|
- [ ] `pnpm test:run` passed
|
|
- [ ] `pnpm build:dir` passed
|
|
- [ ] signing environment variables are set from secret manager (not shell history files)
|
|
- [ ] `AGENTCOMPANY_UPDATE_URL` points to production or staging trusted domain (not `example.invalid`)
|
|
- [ ] updater checks are enabled for release validation (`AGENTCOMPANY_DISABLE_UPDATES=false`)
|
|
- [ ] macOS signed build + notarization validation completed on macOS host
|
|
- [ ] Windows signed installer validation completed on Windows host
|
|
- [ ] Linux AppImage validation completed on Linux host
|
|
- [ ] update metadata (`latest*.yml`) and published artifacts hash-match
|
|
- [ ] secrets regression check completed (existing local secrets remain readable after upgrade)
|
|
- [ ] local data migration test completed (old profile boots and migrates without data loss)
|
|
- [ ] final go/no-go approved by CEO / ProjectManager
|
|
|
|
## Runbook
|
|
|
|
### 1. Preflight (all platforms)
|
|
|
|
```sh
|
|
pnpm install --frozen-lockfile
|
|
pnpm lint
|
|
pnpm typecheck
|
|
pnpm test:run
|
|
pnpm build:dir
|
|
```
|
|
|
|
Expected: all commands pass; no skipped failures are allowed unless explicitly waived in release notes.
|
|
|
|
### 2. Signing Material Readiness
|
|
|
|
Prepare these values in CI secret manager or local secure vault:
|
|
|
|
- `AGENTCOMPANY_UPDATE_URL`
|
|
- `CSC_LINK`
|
|
- `CSC_KEY_PASSWORD`
|
|
- `WIN_CSC_LINK`
|
|
- `WIN_CSC_KEY_PASSWORD`
|
|
- macOS notarization credentials (`APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`) if using Apple ID flow
|
|
|
|
Sanity check before release build:
|
|
|
|
```sh
|
|
env | rg "^(AGENTCOMPANY_UPDATE_URL|CSC_LINK|WIN_CSC_LINK|APPLE_ID|APPLE_TEAM_ID)="
|
|
```
|
|
|
|
### 3. macOS Signed Build + Notarization (native macOS host)
|
|
|
|
1. Enable release-mode updater behavior and set trusted update URL.
|
|
2. Build signed artifacts.
|
|
3. Validate signature + notarization ticket.
|
|
|
|
```sh
|
|
export AGENTCOMPANY_DISABLE_UPDATES=false
|
|
export AGENTCOMPANY_UPDATE_URL="https://updates.<your-domain>/agentcompany/stable"
|
|
export CSC_LINK="file://$HOME/.signing/agentcompany-mac.p12"
|
|
export CSC_KEY_PASSWORD="<from-secret-manager>"
|
|
export CSC_IDENTITY_AUTO_DISCOVERY=true
|
|
export APPLE_ID="<apple-notarization-account>"
|
|
export APPLE_APP_SPECIFIC_PASSWORD="<app-specific-password>"
|
|
export APPLE_TEAM_ID="<team-id>"
|
|
|
|
pnpm build -- --mac dmg zip --publish never
|
|
|
|
spctl -a -vv "build/release/mac/AgentCompany.app"
|
|
codesign -dv --verbose=4 "build/release/mac/AgentCompany.app" 2>&1 | rg "Authority=|TeamIdentifier="
|
|
xcrun stapler validate "build/release"/*.dmg
|
|
```
|
|
|
|
Notes:
|
|
|
|
- For public macOS distribution, switch `mac.hardenedRuntime` to `true` with proper entitlements before final GA build.
|
|
- Keep ad-hoc signing only for local development and internal unsigned testing.
|
|
|
|
### 4. Windows Signed Installer Validation (native Windows host)
|
|
|
|
```powershell
|
|
$env:AGENTCOMPANY_DISABLE_UPDATES = "false"
|
|
$env:AGENTCOMPANY_UPDATE_URL = "https://updates.<your-domain>/agentcompany/stable"
|
|
$env:WIN_CSC_LINK = "C:\signing\agentcompany-win.pfx"
|
|
$env:WIN_CSC_KEY_PASSWORD = "<from-secret-manager>"
|
|
|
|
pnpm build -- --win nsis --x64 --publish never
|
|
|
|
Get-ChildItem .\build\release\*.exe | Get-AuthenticodeSignature |
|
|
Format-Table Path, Status, @{Name='Signer';Expression={$_.SignerCertificate.Subject}}
|
|
```
|
|
|
|
Expected:
|
|
|
|
- `Status` is `Valid`
|
|
- signer subject matches the intended publisher identity
|
|
|
|
### 5. Linux AppImage Validation (native Linux host)
|
|
|
|
```sh
|
|
export AGENTCOMPANY_DISABLE_UPDATES=false
|
|
export AGENTCOMPANY_UPDATE_URL="https://updates.<your-domain>/agentcompany/stable"
|
|
|
|
pnpm build -- --linux AppImage --x64 --publish never
|
|
|
|
chmod +x build/release/*.AppImage
|
|
./build/release/*.AppImage --appimage-version
|
|
```
|
|
|
|
Then run manual smoke validation on Linux:
|
|
|
|
- app launches and reaches main shell
|
|
- company/workspace/agent CRUD works
|
|
- task run + approval flow works
|
|
- settings toggle for updater works
|
|
|
|
### 6. Updater Endpoint Trust Verification
|
|
|
|
1. Validate update metadata endpoint and schema.
|
|
2. Verify published artifact hash against metadata.
|
|
3. Validate app update check in runtime.
|
|
|
|
```sh
|
|
curl -fsSL "$AGENTCOMPANY_UPDATE_URL/latest.yml" -o /tmp/latest.yml
|
|
rg "^(version|path|sha512):" /tmp/latest.yml
|
|
```
|
|
|
|
Hash verification (replace placeholders with actual artifact path/hash from metadata):
|
|
|
|
```sh
|
|
node -e "const fs=require('fs');const crypto=require('crypto');const [file,expected]=process.argv.slice(1);const got=crypto.createHash('sha512').update(fs.readFileSync(file)).digest('base64');if(got!==expected){console.error('sha512 mismatch');process.exit(1)}console.log('sha512 ok');" \
|
|
build/release/<artifact-file> \
|
|
"<sha512-from-latest-yml>"
|
|
```
|
|
|
|
Runtime verification:
|
|
|
|
- launch packaged app with `AGENTCOMPANY_DISABLE_UPDATES=false`
|
|
- trigger `Check for updates` from Settings
|
|
- confirm request goes only to trusted `AGENTCOMPANY_UPDATE_URL` domain
|
|
- confirm unsigned/untrusted update payloads are rejected by platform signing checks
|
|
|
|
### 7. Windows/Linux Native-Host QA Gate
|
|
|
|
Required evidence per platform:
|
|
|
|
- startup success + no crash in first 5 minutes
|
|
- create company + create workspace + create task + assign agent + run once
|
|
- approve one pending approval item
|
|
- inspect logs for uncaught errors
|
|
- close/reopen app and confirm local data persistence
|
|
|
|
### 8. Release Close-Out
|
|
|
|
- publish artifacts and corresponding `latest*.yml` only after all platform owners sign off
|
|
- attach evidence bundle (command output, screenshots, hash checks, signatures)
|
|
- mark release decision in changelog/release note with approver and timestamp
|
|
|
|
## Outstanding Risks Before Public GA
|
|
|
|
- current config keeps `mac.hardenedRuntime: false`; must be enabled with release entitlements for notarized public mac builds
|
|
- no trusted production updater endpoint is configured by default (`example.invalid` fallback)
|
|
- Windows and Linux validation still requires native host execution each release cycle
|