# ForgeFlow 0.6.0 release audit

## Scope

This audit covers the source release intended for publication to `Jens/ForgeFlow` and subsequent installation through ForgeFlow's built-in source updater.

Reviewed areas:

- local Git discovery, status, staging, commit, push, fetch and fast-forward;
- large Windows path selections and deleted/renamed files;
- stale Git lock diagnosis, conservative repair and automatic retry;
- divergence recovery with a safety branch;
- Gitea repository and Actions integration;
- SSH host identity, Unraid-to-Gitea preflight and exact-SHA deployment;
- Docker Compose identity normalization while preserving visible container names;
- DockerMan WebUI, icon and shell labels, XML fallback and cache refresh;
- interrupted/stale deployment reconciliation;
- renderer viewport behavior and guided troubleshooting;
- diagnostics redaction and support bundles;
- release publication and built-in source-update lifecycle.

## Regression coverage

The automated suite contains 99 passing tests, including real temporary Git repositories and bare remotes. High-risk regressions covered directly include:

- staged and unstaged deletions;
- renamed files;
- a local commit followed by a failed push;
- 850 long selected paths transported through NUL-delimited stdin;
- stale `HEAD.lock` removal while excluding Git object/LFS storage;
- backup-before-reset repair of a diverged branch;
- exact remote-SHA checks;
- background SSH deployment completion without a stuck operation;
- startup/manual reconciliation of live Unraid state;
- lowercase-safe Compose project/service/image identities with visible `Portfolio` casing;
- DockerMan labels, built-in icon upload, XML fallback and cache invalidation;
- source-updater STARTED handshake, result acknowledgement, direct Electron restart and rollback state.

## Product behavior added for the reported incidents

- Git mutations are serialized per repository.
- A lock failure triggers a safe diagnosis and one automatic repair/retry when no active Git process is detected.
- Git Tools provides personalized scan, lock repair, origin repair, fast-forward, push and safety-branch divergence recovery actions.
- Successful SSH deployments become terminal before the secondary server refresh, preventing a live container from leaving ForgeFlow in deployment mode.
- ForgeFlow refreshes configured server truth after startup and through the combined refresh action.
- A healthy live SHA equal to local/Gitea is not offered for deployment again.
- Running containers missing DockerMan metadata can be repaired individually or in one batch from Deployments.
- Built-in/uploaded icons are placed in persistent DockerMan storage, referenced through a `file:///` label, written into a user template and copied into known icon caches.
- WebUI uses the Unraid label placeholders based on the configured host port and path.
- Update publication creates and publishes `package-lock.json`; the updater uses `npm ci` when it is present.
- Update success is persisted before restart, and restart invokes Electron directly rather than relying on a detached npm process.

## Static and packaging checks

- every JavaScript/CJS/MJS source file passes `node --check`;
- required source, branding, documentation, updater and deployment files are present;
- direct dependency versions are pinned;
- renderer privileged actions remain behind the preload/IPC boundary;
- the PowerShell update helper starts with `param(`, has no UTF-8 BOM and contains lifecycle state before shutdown/restart;
- release archives exclude `.git`, `node_modules`, `dist`, update downloads and generated ZIPs;
- the generated source manifest records SHA-256 and size for every distributed source file.

## Remaining live acceptance step

The automated environment cannot execute Windows PowerShell 5.1 or connect to the user's private Gitea/Unraid services. The final live acceptance is therefore deliberately the requested workflow:

1. publish the release from an extracted Downloads folder;
2. leave the installed older source at `C:\Projects\ForgeFlow` untouched;
3. open that older ForgeFlow;
4. use **Settings → ForgeFlow updates → Check now → Download update → Apply & restart**;
5. confirm the restarted application reports version 0.6.0 and displays the persisted success result.

A failed handoff must keep the old app open. A failed validation must restore the previous source. A successful installation remains installed even when only automatic restart fails.