fix(qa): coordinate functional regression repair chain

[rechedev9]

Pre-flight Checklist

• I searched existing issues. Several findings overlap existing scopes; those relationships are listed below.
• I understand that implementation PRs require a linked issue with status:approved.

📝 Bug Description

Functional QA against commit d0571721d88518d2e7572211a0e93b5715c8643f confirmed 33 reproducible behavior and usability defects across the RDD/SDD lifecycle, workspace installation state, CLI/TUI output, backups, documentation, and E2E result handling.

This is a coordination issue, not an attempt to bypass existing issue ownership. It proposes a reviewable PR chain and asks maintainers to decide whether the chain should use this tracking issue, existing approved issues, or new child issues.

Scope: functional behavior and user experience only. No security review is requested.

Metric	Result
Confirmed defects	33
High severity	20
Medium severity	11
Low severity	2
Candidate diff	87 files, 2,256 additions, 498 deletions
Audit platform	Ubuntu 22.04-compatible Linux, Git 2.34.1, Go 1.26.4

Root causes

1. Contract drift across layers. Native CLI states, transition planners, installed SDD assets, fixtures, and documentation evolved independently, so valid native outcomes such as disabled/unmanaged were rejected by higher-level flows.
2. Lossy persisted context. Installation scope, workspace roots, authority provenance, and executable continuation context were not always persisted or propagated to later commands.
3. Presence checks substituted for semantic validation. Several paths treated non-nil files, printed output, or shaped JSON as success without validating content, canonical evidence, or process exit status.
4. Exact replay was not idempotent. CAS-backed mode writes and SDD attempt acquisition/settlement treated concurrent replays of the same intended state as conflicts.
5. Runtime assumptions leaked into supported environments. Git command capabilities, linked-worktree metadata, narrow terminal dimensions, and broken dependency executables were handled as if the happy-path environment were guaranteed.

Confirmed findings

ID	Severity	Area	Reproduced behavior
BUG-001	High	RDD / pre-PR	git merge-tree --write-tree fails on Ubuntu 22.04's Git 2.34.1 and is misreported as scope or merge conflict.
BUG-002	High	RDD / FINALIZE	Raw evidence bytes without a native outcome or binding can approve delivery.
BUG-003	High	RDD / global mode	A global mode write persists but exits 1 with contradictory JSON outside a repository.
BUG-004	High	RDD / transition contract	An executable review.recover transition omits execute.command.
BUG-005	Medium	RDD / recovery	STATUS asks for external recovery authorization that the CLI can derive itself.
BUG-006	High	RDD / precedence	An exact candidate decline wins over an exact escalated legacy authority.
BUG-007	High	RDD / release	Five empty files are accepted as complete sealed/current release evidence.
BUG-008	Medium	RDD / concurrency	Pre-commit can return allow after the index changes beyond its last snapshot.
BUG-009	High	RDD / consent	Relay invocations are not executable when --cwd contains spaces.
BUG-010	High	RDD / classification	child_process.spawn(..., {shell:true}) is classified below the equivalent process-boundary risk.
BUG-011	High	RDD / validator	Empty or whitespace-only validator evidence can approve an ineffective correction.
BUG-012	Medium	RDD / consent v1	English decline text claims nothing is persisted although durable authorization is written.
BUG-013	High	SDD / Engram	sdd-status does not discover an existing Engram-only change by default.
BUG-014	Medium	SDD / worktrees	Linked worktrees lose the canonical Engram project identity.
BUG-015	High	SDD / reviews disabled	Engram pre-verify guidance requires a review that the kill switch forbids starting.
BUG-016	High	SDD / archive	Installed assets require allow and a receipt when native delivery is correctly disabled/unmanaged.
BUG-017	High	install / sync	Sync forgets workspace scope and creates a second global installation.
BUG-018	High	install / uninstall	Uninstall reports success without removing a workspace installation.
BUG-019	High	install / restore	Workspace backups outside HOME are created but every recorded path is rejected during restore.
BUG-020	Medium	dependencies	Broken Node/npm executables satisfy preflight as healthy.
BUG-021	Medium	build / docs	Quickstart promises Go 1.24+ while go.mod requires Go 1.25.10.
BUG-022	High	CLI / doctor	Doctor prints unhealthy checks but exits 0.
BUG-023	High	CLI / dry-run	Global/workspace and stable/beta plans render the same preview and hide destinations and channel.
BUG-024	Medium	CLI / restore	restore --list suppresses corrupt manifests and falsely reports no backups.
BUG-025	Medium	TUI / viewport	The selected welcome option is off-screen at 40×15, making initial navigation blind.
BUG-026	High	E2E / CI	Tier 1 reports 79/79 PASS when every valid invocation is forced to exit 1 while preserving output.
BUG-027	Medium	documentation / RDD	Quickstart contradicts the README about stable RDD availability.
BUG-028	Low	E2E / docs	The guide omits Fedora although the quick command builds and runs it.
BUG-029	High	SDD / concurrency	Concurrent identical acquire/settle replays mostly return false invalid_continuation.
BUG-030	Medium	RDD / clone mode	Concurrent identical clone-mode writes fail CAS and sequential no-op writes still rewrite state.
BUG-031	High	RDD / next transition	STATUS emits START/FINALIZE commands without the requested --cwd.
BUG-032	Medium	RDD / error contract	FINALIZE before START is reported as unknown and creates a defect report instead of a known precondition failure.
BUG-033	Low	CLI / help	review --help hides the public capture-evidence and mode commands.

🔄 Steps to Reproduce

1. Check out commit d0571721d88518d2e7572211a0e93b5715c8643f.
2. Use an Ubuntu 22.04-compatible environment with Git 2.34.1 and Go 1.26.4.
3. Exercise the RDD/SDD, workspace lifecycle, CLI/TUI, backup, and E2E paths described in the finding table.
4. Run focused reproductions for each finding and repeat concurrency cases with identical inputs.
5. Observe the mismatches described above.

The detailed reproduction report is available locally and can be copied into child issues once maintainers choose the issue structure.

✅ Expected Behavior

• Supported platforms complete review delivery without hidden Git capability failures.
• Terminal approval is bound to canonical, non-empty, target-specific evidence.
• Every advertised executable transition is directly runnable and preserves --cwd.
• Disabled review mode remains unmanaged without fabricating review authority.
• Workspace scope survives install, sync, uninstall, backup, and restore.
• Exact concurrent replays converge idempotently.
• CLI, TUI, E2E, and documentation report the behavior users actually receive.

❌ Actual Behavior

The 33 defects above create false approvals, false denials, contradictory command outcomes, lost workspace scope, misleading health/preview output, unusable narrow-terminal navigation, and false-positive E2E success.

Proposed PR chain

Each slice will be extracted as a work-unit commit with its code, table-driven regression tests where applicable, and documentation. Every PR will remain at or below the 400 changed-line budget; a slice will be split again if the measured patch exceeds it.

Order	Proposed PR	Findings
1	fix(review): support legacy merge-tree and final snapshot checks	BUG-001, BUG-008
2	fix(review): require canonical finalization and release evidence	BUG-002, BUG-007, BUG-011
3	fix(review): complete recovery routing and authority precedence	BUG-004–006, BUG-031–032
4	fix(review): make mode and consent contracts executable	BUG-003, BUG-009–010, BUG-012, BUG-030, BUG-033
5	fix(sdd): align Engram discovery and disabled-mode routing	BUG-013–016
6	fix(sdd): make runtime attempt replay idempotent	BUG-029
7	fix(sync): preserve workspace installation scope	BUG-017
8	fix(uninstall): remove workspace-managed installations	BUG-018
9	fix(backup): preserve and validate workspace restore roots	BUG-019, BUG-024
10	fix(cli): report actionable diagnostics and visible state	BUG-020–023, BUG-025, BUG-027
11	test(e2e): fail closed on command errors	BUG-026, BUG-028

Dependencies will be expressed with stacked base branches only where unavoidable. Independent slices will target main directly.

Known related or overlapping issues

• fix(review): probe, surface, and document the Git >= 2.38 merge-tree --write-tree requirement #2051 overlaps BUG-001, but proposes a Git 2.38 floor while this QA reproduces the defect on an officially supported Ubuntu 22.04 default and has a compatibility candidate.
• fix(cli): authorized review.recover execute transition omits command #1864 directly overlaps BUG-004.
• fix(review): reject opaque sentinel-only evidence as sufficient high-risk gate authority #1843 is related to BUG-007's insufficient evidence admission.
• fix(sdd): honor disabled review mode before pre-verify routing #1932, fix(sdd): disabled review mode leaves stale binding that blocks apply #2069, and fix(sdd): archive gate blocks on a discovered invalidated receipt while review mode is disabled #2128 are related to BUG-015/016's disabled-mode routing and asset drift.
• fix(sync): sync command rejects --scope flag and is global-only, leaving no way to refresh a workspace-scoped install #1074 overlaps BUG-017's missing workspace-aware sync behavior.
• fix(backup): restore authorized workspace roots outside the user home #1722 directly overlaps BUG-019.
• Install fails agent opencode, claude-code and engram. No Node prereq check. #850 is related to BUG-020's dependency preflight behavior.
• fix(review): START and FINALIZE classify flag parse errors as unknown mutation outcome #1956 is related to BUG-032's unknown-outcome classification.

These references need maintainer triage before child issues or PRs are opened, so existing issue ownership is preserved and duplicate fixes are avoided.

Candidate solution and validation evidence

A local, unpublished candidate currently addresses all findings. It has not been committed, pushed, or opened as a PR and can be reshaped or discarded based on maintainer direction.

The candidate has passed:

• uncached full root tests and go vet ./...;
• bench module tests, vet, build, and the full 63-journey matrix;
• Tier 1 E2E at 79/79 plus a negative wrapper proving non-zero exits fail closed;
• focused race tests and 20 repeated concurrent replay/mode/gate runs;
• Linux, macOS amd64/arm64, and Windows amd64 cross-builds;
• shell syntax and diff whitespace checks.

🖥️ Environment

• Gentle AI version: 2.2.5-0.20260801101024-d0571721d885
• Operating system: Linux (Ubuntu/Debian compatible)
• Git: 2.34.1
• Go: 1.26.4
• AI clients exercised: native CLI and installed agent assets
• Affected area: Other — cross-cutting functional QA

Maintainer decision requested

@Alan-TheGentleman, could you confirm the preferred issue structure before publication?

1. Approve this tracking issue and specify how each PR should satisfy the issue-reference check; or
2. Reuse the related approved issues where scope matches and create separate child issues for the remaining slices.

Once that direction and status:approved coverage exist, the local candidate will be split into the review-budgeted chain above.

[dnlrsls]

This tracker identifies potentially valid reports, but it is not an implementable unit: it combines 33 findings and overlaps existing owned issues. Please provide a current-main mapping that assigns every finding to either a verified existing issue or a new narrow child issue, including a focused reproduction and acceptance criteria. We can then approve independent slices without duplicate PRs.