Initialize project and ignore local references

2026-03-15 22:17:07 -04:00
1 parent a11ac3eaba
commit 2af82b6bb3
@@ -0,0 +1,199 @@
+# 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