Recover from stale or conflicted state

Applies to SiliconForge 0.1.2 · Updated 2026-09-30. Check platform limits.

Before this task: Understand what a checkpoint preserves →

A stale-state refusal protects work you may not have reviewed. Diagnose the changed state, preserve it, and prepare a fresh operation instead of forcing the old one.

Preserve before repairing#

Identify the project root and the operation that failed. Keep the error text, selected baseline/target IDs and affected paths. Do not begin with git reset --hard, git clean, deleting .git or deleting .siliconforge: those can destroy unrelated work, local history or recovery material.

If an editor buffer is unsaved, resolve it deliberately before changing branches or restoring files. For a significant repair, close the application and other writers and make a protected full-project backup first.

Worked flow: another client changed the index#

1. You select rtl/top.sv in SiliconForge. Another Git client stages tb/top_tb.sv before you choose Stage.
2. If the operation reports Git index changed; refresh status before modifying it, do not repeatedly retry the stale selection.
3. Finish or stop the competing operation safely, then choose Refresh in History.
4. Inspect Staged changes and Unstaged changes again. Decide whether the externally staged testbench belongs in the next commit.
5. Reselect the intended files and stage or unstage against the refreshed state. Before Commit, review the entire staged layer.

A changed HEAD is similar: refresh, identify the new commit and reconsider the operation. If an error says HEAD moved after commit publication, inspect local history before trying again. A commit may already exist; blindly repeating the action risks confusion.

Locks, conflicts and unsupported paths#

Git index is locked

Check whether another Git operation is active. Let it finish; do not delete another process's lock. For an abandoned lock after a confirmed crash, preserve the repository and use your Git administrator's recovery procedure before reopening the application.

Unresolved merge conflicts

Inspect and resolve them with your external Git tools, review the chosen contents and complete the merge there. The native commit workflow is not a merge-resolution UI.

Missing author identity

Configure the intended repository-local Git name and email, then refresh. Do not use someone else's identity simply to unblock a commit.

Clean-filter restriction

Native staging refuses configured external clean filters rather than running arbitrary programs. Use an approved Git client with the intended filter environment, then inspect the resulting staged content.

Symlink, secret-like or unsafe path

Investigate the path and project's intended layout. Do not bypass the safety check by renaming a secret. A non-actionable displayed path should be handled with an appropriate external tool.

Recover an applied candidate#

Follow the reviewed reversion workflow: use Revert candidate… when you want a newly reviewable reversal of an applied proposal. It uses the original rollback evidence, attempts to preserve non-conflicting later edits and refuses conflicts. The reversal remains a new candidate that needs validation, review and explicit application.

Rollback restores a proposal through its guarded rollback operation; it is not a generic “undo anything” command. Missing or changed rollback evidence and later modifications can block it. Preserve the newer work and use a reviewed manual recovery or verified backup rather than altering hashes or rollback records.

If application of a proposal succeeded but creation of its engineering checkpoint produced a warning, inspect current files and the proposal's state first. A failed checkpoint is not proof that the apply failed; do not automatically apply the change a second time.

Back up and test restoration#

1. Stop the application and other project writers. Save any intended editor changes first.
2. Copy the whole project to a protected backup destination, including .git, .siliconforge, untracked sources and relevant local inputs. Handle credentials and licensed assets under their own access rules.
3. Keep an off-device or otherwise independent copy. A checkpoint on the same disk is not disaster recovery.
4. Restore into a separate directory. Inspect Git status/history and open the restored project; verify retained checkpoints, source and expected local evidence before replacing anything.

A Git clone restores committed repository content, not untracked files or automatically the local candidate, checkpoint and evidence store. Installation rollback restores application files, not your design history. See checkpoint coverage and external Git interoperability before choosing a recovery source.

Share a bounded diagnostic#

For support, include the application version, OS, operation, redacted error, and whether another Git client was active. Review paths, author details and tool logs before sharing. Do not upload proprietary RTL, credentials, full Git configuration or the entire local state directory unless you have deliberately approved that disclosure.

Need help? Report an issue. Include your application version; never include credentials.