tech-debt: 6 architectural follow-ups from audit-r-dogfood (ARCH-1/3/4/5/6/7)

[explosivebit]

Summary

Architectural debt accumulated during audit-r4..r7 + audit-r-dogfood cycles. None of these are blocking — they're refactor / methodology hardening items deferred from the v0.32.0 closing sprint. Tracking here so they don't get lost.

Items

ARCH-1: ADR for 3-field status deprecation timeline

Context: forgeplan_discover_* tools now expose three semantically-overlapping fields (status legacy + session_status + artifact_status) plus _field_warnings. No artifact (ADR-XXX) fixes the deprecation horizon. Without it, status lingers forever in the API surface.

Acceptance:

• Create ADR-XXX: discover_* status field deprecation timeline
• Define target removal version (proposal: v1.0.0)
• Update _field_warnings.message to reference the ADR
• Regression test: schema docs check on field removal

ARCH-3: Explicit git_root parameter (forgeplan_release_notes)

Context: find_git_root does magic discovery (walk-up + walk-down). Works, but introduces an invisible convention. Users in unusual layouts will hit edges. Better: explicit git_root: Option<PathBuf> parameter, magic helper becomes opt-in.

Acceptance:

• Add optional git_root to ReleaseNotes params
• When None, fall through to find_git_root (current behaviour, no break)
• When Some(path), skip discovery, validate .git/ exists at path
• Tests: explicit path takes precedence over discovery

ARCH-4: Invert apply_restore as shim

Context: Two near-identical public functions (apply_restore + apply_restore_with_target). Forks the API surface. Should be: _with_target is canonical, apply_restore(r) -> apply_restore_with_target(r, None) is the shim.

Acceptance:

• Refactor — single canonical impl, legacy is 1-line shim
• All existing tests still pass
• No external callers need to change (both signatures kept pub)

ARCH-5: PROB for pre-existing undo::restore projection bypass

Context: crates/forgeplan-core/src/undo/restore.rs calls store.create_artifact / store.update_artifact / store.delete_relation directly, bypassing projection::*_with_projection helpers. Pre-existing (from v0.22.x), not a regression of audit-r-dogfood. tests/adr_003_invariant.rs scope is commands/ + mcp/server.rs so this is exempt by the regression guard. Document as known exception or fix.

Acceptance:

• Open PROB-XXX: undo::restore bypass projection — file/store sync drift risk
• Decide: fix (route through projection) or document permanent exemption

ARCH-6: Move CROSS-REPO-WORKFLOW.ru.md to org-wide repo

Context: Methodology doc lives in forgeplan/docs/methodology/ — invisible to marketplace contributors. Belongs in ForgePlan/.github/profile/ (org-wide visibility) or dedicated forgeplan-rfcs/ meta-repo.

Acceptance:

• Copy to ForgePlan/.github/profile/CROSS-REPO-WORKFLOW.md
• Replace local doc with [!INFO] Canonical version at org/.github/...

ARCH-7: Shared evidence_recipe(artifact_id) helper

Context: 5-step EVID fix recipe (audit-r4 CODE-294 closure) is hardcoded in format! literal inside activate error path. Same recipe will be needed in forgeplan_review output, forgeplan_health blindspot advisory, CLI hint — copy-paste risk.

Acceptance:

• Extract lifecycle::evidence_recipe(artifact_id: &str) -> String
• Replace inline format! in activate error
• Add doc-comment + unit test
• Document as canonical hint pattern in PRD-071

Labels

enhancement, documentation (where applicable)

Origin

Filed from fix/issues-290-295-dogfood-findings branch closure (audit-r-dogfood 3-agent adversarial review).